Metadata-Version: 2.4
Name: nnworkbench
Version: 0.1.0
Summary: A GUI for nnU-Net workflows and nnInteractive-powered annotation
Author-email: Lars Krämer <lars.kraemer@dkfz-heidelberg.de>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/MIC-DKFZ/nnWorkbench
Project-URL: Repository, https://github.com/MIC-DKFZ/nnWorkbench
Project-URL: Documentation, https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/README.md
Project-URL: Issues, https://github.com/MIC-DKFZ/nnWorkbench/issues
Keywords: nnU-Net,nnInteractive,segmentation,annotation,medical imaging,deep learning,GUI,napari
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nnunetv2<3,>=2.8.1
Provides-Extra: gui
Requires-Dist: qtpy<3,>=2.4; extra == "gui"
Requires-Dist: mitk-python<2027,>=2026.06; extra == "gui"
Requires-Dist: napari<1,>=0.9; extra == "gui"
Requires-Dist: napari-layer-statistics<2,>=1; extra == "gui"
Requires-Dist: napari-nninteractive[local]<3,>=2.5.4; extra == "gui"
Provides-Extra: all
Requires-Dist: nnworkbench[gui]; extra == "all"
Requires-Dist: PySide6<7,>=6.6; extra == "all"
Provides-Extra: dev
Requires-Dist: qtpy<3,>=2.4; extra == "dev"
Requires-Dist: PySide6<7,>=6.6; extra == "dev"
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: pytest-timeout<3,>=2.3; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/MIC-DKFZ/nnWorkbench/main/src/nnworkbench/assets/images/readme-header.png" alt="nnWorkbench: from a few labels to your own segmentation model" width="720">
</p>

<p align="center">
  <a href="https://pypi.org/project/nnworkbench/"><img alt="PyPI" src="https://img.shields.io/pypi/v/nnworkbench"></a>
  <a href="https://doi.org/10.5281/zenodo.24013948"><img alt="DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.24013948.svg"></a>
  <img alt="Python 3.12" src="https://img.shields.io/badge/python-3.12-blue">
  <img alt="Platforms: Linux, Windows, macOS" src="https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey">
  <img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-green">
  <a href="https://github.com/MIC-DKFZ/nnWorkbench/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MIC-DKFZ/nnWorkbench/actions/workflows/ci.yml/badge.svg"></a>
</p>

> A GUI for nnU-Net and nnInteractive-powered annotation that keeps the entire workflow in one place.
> - **nnU-Net Workflow:** train, validate and apply nnU-Net on images that already have labels.
> - **Annotation Workflow:** for images without labels. Create labels efficiently with nnInteractive and scribbles, then train, validate and improve the model in iterations.

<p align="center">
  <a href="#installation"><b>Installation</b></a> ·
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="#cli-overview"><b>CLI</b></a> ·
  <a href="#work-with-an-ai-agent"><b>AI agents</b></a> ·
  <a href="#qa"><b>Q&amp;A</b></a> ·
  <a href="#documentation"><b>Documentation</b></a> ·
  <a href="#citation"><b>Citation</b></a> ·
  <a href="#license"><b>License</b></a>
</p>

## Why nnWorkbench

- **Everything in one place:** All your datasets with their images, labels, preprocessed data, trained models and validation results, connected in one window, from the first image to the final prediction.
- **nnInteractive and nnU-Net, connected:** Create labels with nnInteractive in Napari, save them directly as nnU-Net training data, and continue with preprocessing and training without any conversion.
- **Guidance along the way:** Each stage shows what is done, what can run next and what has to be fixed first, with a short how-to on every page and a step-by-step guide built in.
- **Inspection at every stage:** Open raw images and labels, preprocessed data, predictions and validation results in Napari, with the matching files loaded together, and find the weakest cases with one click.
- **Simple by default, full control when needed:** nnWorkbench works for users of every experience level. Short dialogs with sensible defaults get you going; planners, trainers and additional arguments are there when you need them, and every step can be copied as the exact nnU-Net command for a terminal or a cluster.

## Why Annotation Workflow

No labels yet? The Annotation Workflow gets you from raw images to a trained model with as little manual work as possible:

- **Annotate smart, not hard:** Label only parts of many images instead of everything in a few (*sparse labels*): nnInteractive outlines a whole 3D object in a few clicks, scribbles cover the rest.
- **Improve in iterations:** Train early, see where the model fails, and annotate exactly there.
- **Made for sparse labels:** A trainer bundled with nnWorkbench learns from sparse labels and is selected automatically.
- **Guided from start to finish:** A built-in guide explains every step, from defining your classes to deciding when the model is good enough.

![Annotation Workflow: describe, define, annotate, train, validate, predict, with a loop back to annotation](https://raw.githubusercontent.com/MIC-DKFZ/nnWorkbench/main/src/nnworkbench/assets/images/annotation-workflow-header.png)

## Installation

**Requirements:**

- **Python 3.12**
- Windows 10/11, macOS 13 or newer, or Linux with glibc 2.35 or newer (e.g. Ubuntu 22.04+)
- Conda or another Python environment manager
- For training: an NVIDIA GPU, 24 GB of memory for the recommended setup, 8 GB at minimum with a smaller planner (see [Planners and GPU Memory](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/4-train.md#planners-and-gpu-memory) in the guide). Annotating, validating and predicting also work without one.

**From PyPI:**

```bash
conda create -n nnworkbench python=3.12
conda activate nnworkbench
pip install "nnworkbench[all]"
nnworkbench-gui
```

**From source:**

```bash
conda create -n nnworkbench python=3.12
conda activate nnworkbench
git clone https://github.com/MIC-DKFZ/nnWorkbench.git
cd nnWorkbench
pip install -e ".[all]"
nnworkbench-gui
```

Depending on your system, you may need to install PyTorch manually before installing nnWorkbench, as described on [pytorch.org](https://pytorch.org/get-started/locally/). This is required on Windows to use an NVIDIA GPU.
For a lightweight installation without the GUI on a remote machine, and for notes on using nnWorkbench on macOS, see the instructions below.

<details>
<summary><b>Windows</b></summary>

pip installs a CPU-only PyTorch on Windows, so an NVIDIA GPU would not be used. Install the CUDA build of PyTorch **before** nnWorkbench, in the activated environment:

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu128
```

If a CPU-only PyTorch is already installed, add `--force-reinstall` (pip keeps the installed version otherwise); the Info dialog of the GUI (top right) shows this command when the GPU is not usable.

Then install nnWorkbench from PyPI:

```bash
pip install "nnworkbench[all]"
```

or from source (inside the cloned repository):

```bash
pip install -e ".[all]"
```

The right command for your CUDA version is on [pytorch.org](https://pytorch.org/get-started/locally/). These installation commands work in PowerShell and the Windows command prompt. Commands that nnWorkbench shows or copies (**Copy command**) are written for PowerShell (as for bash and zsh on Linux and macOS), not for the command prompt.

</details>

<details>
<summary><b>macOS</b></summary>

nnWorkbench itself runs fully on macOS (13 or newer). For the GPU-heavy parts, it relies on nnU-Net and nnInteractive, which differ on Apple silicon:

- **nnU-Net (training and prediction):** runs on the Apple GPU with `-device mps` (choose **MPS** under **Device** in the Train and Predict dialogs). It works, but is much slower than an NVIDIA GPU, and the GPU shares its memory with the system: prefer `nnUNetPlannerResEncM` or `ExperimentPlanner` over `nnUNetPlannerResEncL`. A Mac is fine for predicting and short test runs; train on a GPU machine or cluster.
- **nnInteractive (annotation):** the napari-nninteractive plugin uses only CUDA GPUs, so on a Mac it runs on the CPU, which is slow. For a smooth experience, connect the plugin to an nnInteractive server on a GPU machine (see the [napari-nninteractive documentation](https://github.com/MIC-DKFZ/napari-nninteractive)).

</details>

<details>
<summary><b>Remote machines and clusters</b></summary>

On a cluster, the core installation is enough: nnU-Net, the bundled trainers and the command-line tools, without the nnWorkbench GUI, Napari or nnInteractive.

```bash
# from PyPI
pip install nnworkbench

# from source (inside the cloned repository)
pip install -e .
```

Save the nnU-Net folders on the remote machine once:

```bash
nnworkbench-set-paths --raw /path/to/nnUNet_raw --preprocessed /path/to/nnUNet_preprocessed --results /path/to/nnUNet_results
```

`nnworkbench-run` then uses them for nnU-Net commands and dataset tools.
Optionally, you can prepare this in the nnWorkbench GUI: on the overview, add a remote path profile with the folders of the remote machine; **Export** then copies the `nnworkbench-set-paths` command above with these paths. The commands themselves can also be configured in the GUI: **Copy command** in the run dialogs gives the matching `nnworkbench-run` command, which uses the paths saved on the remote machine. The GUI does not need the cluster's data for this: plans that are only preprocessed on the cluster, and models or folds that only exist there, can be chosen or typed in the Train and Predict dialogs. The run button then stays disabled, and **Copy command** gives the command for the cluster. All commands and dataset tools for the remote machine are listed in the [CLI overview](#cli-overview).

</details>

<details>
<summary><b>Troubleshooting</b></summary>

- **Windows, preprocessing or prediction fails with *Unable to open … for reading* or *Error while creating the NDArray*:** a folder path contains non-ASCII characters (e.g. `C:\Users\Jürgen\…`), which nnU-Net cannot use on Windows. Move the nnU-Net folders (and prediction input/output folders) to a path with ASCII characters only, e.g. `C:\nnUNet\nnUNet_raw`, and set them again. nnWorkbench marks such folders in red.
- **`No matching distribution found for mitk-python`:** the environment does not use Python 3.12, or the system is too old (macOS below 13, Linux with glibc below 2.35). Create the environment with `python=3.12`; on older Linux systems, use the core installation (`pip install nnworkbench`) without the GUI.
- **Info shows *CPU only* although there is an NVIDIA GPU:** PyTorch was installed without CUDA support or does not match the driver; Info shows the cause and the fix.
- **Qt 5 instead of Qt 6:** install the GUI without a Qt binding and add PyQt5: `pip install "nnworkbench[gui]" PyQt5` (from source: `pip install -e ".[gui]" PyQt5`).

</details>

## Quick start

Start the GUI with `nnworkbench-gui`.

![The overview: the three nnU-Net folders, all datasets found in them and the details of the selected dataset](https://raw.githubusercontent.com/MIC-DKFZ/nnWorkbench/main/src/nnworkbench/assets/images/gui-overview.png)

1. **Set your folders.** On the overview, select three folders: `nnUNet_raw` for your datasets (images, labels and `dataset.json`), `nnUNet_preprocessed` for the preprocessed data used in training, and `nnUNet_results` for the trained models and their validation results. nnU-Net fills the last two. Empty folders are fine. nnWorkbench lists every dataset it finds in them.
2. **Create a dataset or select an existing one.** Click **＋ New dataset**, or open a dataset from the list. Put your images into `imagesTr` (and, if you have them, your labels into `labelsTr`), and describe the classes with **Edit** next to `dataset.json`. Red badges on the **Data** page tell you what is still missing.
3. **Annotate** *(Annotation Workflow only)*. On the **Data** page, click the pencil next to an image, annotate in Napari with nnInteractive or the brush, and click **Save annotation**. Labels can be *dense* (every voxel is labelled; the mask starts as background, e.g. to segment a single organ with nnInteractive) or *sparse* (you annotate only parts of each image; the rest stays *ignore* and is not used for training). For sparse labels, add an `ignore` class with the highest ID to `dataset.json`.
4. **Preprocess.** On **Preprocess**, click **▶ Preprocess…** and then **▶ Preprocess**, or **Copy command** to run it on a remote machine. The defaults are a good start.
5. **Train.** On **Train**, click **▶ Train…**, choose the folds and click **▶ Train**, or **Copy command** to run it on a remote machine. The console at the bottom shows the progress.
6. **Validate.** On **Validate**, click a fold of your model to see its Dice score per case, sort by **Dice** to see the weakest cases first, and open any case in Napari to compare the prediction with your label.
7. **Iterate** *(Annotation Workflow only)*. Where the model is still wrong, start another iteration: select the dataset on the overview and click **＋ New iteration**. It copies the images and labels into a new dataset (or links the images, to save space); continue there with step 3 and annotate where the model fails.
8. **Predict.** On **Predict**, choose a folder of new images and an output folder and click **▶ Predict**, or **Copy command** to run it on a remote machine.

![The Data page of a dataset with sparse labels: the cases with their images and labels, dataset.json and the how-to](https://raw.githubusercontent.com/MIC-DKFZ/nnWorkbench/main/src/nnworkbench/assets/images/gui-data.png)

Every page has a short how-to on the left, and **? Guide** in the top bar opens the full [nnWorkbench guide](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/README.md). It explains both workflows step by step: how to understand your images, define classes, annotate efficiently, read the validation results, and decide when a model is good enough.

## CLI overview

nnWorkbench can be used entirely through the GUI. If you prefer not to use the GUI, or are working on a remote system, the same workflows are available from the command line.

After configuring the paths with `nnworkbench-set-paths`, use `nnworkbench-run` to run any nnU-Net command with those saved paths:

```bash
nnworkbench-run nnUNetv2_plan_and_preprocess -d 42 -c 3d_fullres -pl nnUNetPlannerResEncL --verify_dataset_integrity
nnworkbench-run nnUNetv2_train 42 3d_fullres 0 -p nnUNetResEncUNetLPlans
nnworkbench-run nnUNetv2_predict -i /path/to/input -o /path/to/output -d 42 -c 3d_fullres -p nnUNetResEncUNetLPlans
```

These use the recommended `nnUNetPlannerResEncL`, which the GUI also preselects. For sparse annotations from the Annotation Workflow, add `-tr nnUNetTrainerBetterIgnoreSampling` to training and prediction.

It also provides the following dataset tools:

```bash
# List the datasets in the nnU-Net folders: ID, name, where they exist and the iteration (add --json)
nnworkbench-run list

# Create a dataset with imagesTr, labelsTr and dataset.json (add --ignore for sparse labels)
nnworkbench-run create-dataset -d 42 --name CellSegmentation --labels background,cell,nucleus --ignore --channels fluorescence

# Add dataset-description.md: a template to describe the images and define the classes (also: create-dataset --add-description)
nnworkbench-run describe -d 42

# Show what is done and what is next for a dataset, and the device (GPU / MPS / CPU) (add --json for scripts)
nnworkbench-run status -d 42

# The command the GUI would prefill for preprocess, train or predict, and why each option was chosen
nnworkbench-run suggest -d 42 --step train

# Validation results: Dice per fold and class, and the weakest cases first (as the Validate page; add --json)
nnworkbench-run validation -d 42
# ... and open a validation case in Napari: image, label and prediction
nnworkbench-run validation -d 42 --open cells_017

# Open predictions with their input images in Napari
nnworkbench-run inspect-predictions /path/to/output --images /path/to/input

# Start the next iteration: copy images, labels and dataset.json into a new dataset
nnworkbench-run new-iteration -d 42

# Open a dataset's images and labels in Napari, starting at a case (or -i 12 for the 12th image)
nnworkbench-run inspect -d 42 --case cells_012

# Annotate a case in Napari with nnInteractive (as the pencil in the GUI; saves to labelsTr)
nnworkbench-run annotate -d 42 --case cells_012

# Compute statistics (as on the Data page): classes per image and voxels per class, from labelsTr
nnworkbench-run compute-statistics -d 42 --workers 4

# Stack naturally ordered 2D slices (e.g. TIFF or PNG) into one 3D NIfTI volume
nnworkbench-run stack-images /path/to/image_slices --file-type .tif --spacing 1 1 1

# Remove everything a trained model folder does not need for prediction, e.g. before sharing (in place, cannot be undone)
nnworkbench-run reduce-checkpoints /path/to/nnUNet_results/Dataset042_CellSegmentation/MODEL_FOLDER --yes
```

Add `--json` to any tool that returns a result for machine-readable output, e.g. for scripts or agents. Steps that cannot be undone ask for confirmation: `reduce-checkpoints` and training a fold that already has results need `--yes`; add `--dry-run` to see what would happen without changing anything. `-d` (or `--dataset`) specifies the numeric nnU-Net dataset ID under the saved `nnUNet_raw` path. For example, use `-d 42` for `Dataset042_CellSegmentation`. Run `nnworkbench-get-paths` to view the saved path configuration, and add `--help` to any tool to see all its options.

## Work with an AI agent

nnWorkbench is ready for AI coding agents such as Claude Code or Codex. Open the repository (or your working folder with it) in
the agent and describe your goal, e.g. *"Help me train a model that segments the nuclei in my microscopy images in
/data/images."* The agent follows [AGENTS.md](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/AGENTS.md): it asks about your images and labels in plain words, sets
up the dataset, runs preprocessing and training, and summarises the results. You do what needs your eyes and
expertise: it opens the images for you to annotate and the predictions for you to check, and continues when you are
done.

## Q&A

<details>
<summary><b>Do I need a GPU?</b></summary>

For training, an NVIDIA GPU is strongly recommended; on the CPU, training takes days per fold. Everything else (managing datasets, annotating, inspecting, validating, predicting) also works without one. **Info** (top right in the GUI) shows which device was found.

</details>

<details>
<summary><b>I already use nnU-Net. Can I use my existing datasets and models?</b></summary>

Yes. nnWorkbench works directly on the standard nnU-Net folders: choose your existing `nnUNet_raw`, `nnUNet_preprocessed` and `nnUNet_results` on the overview, and all datasets, plans and trained models appear. Nothing is converted or moved.

</details>

<details>
<summary><b>Are my data and trained models still compatible with nnU-Net?</b></summary>

Yes. Datasets, preprocessed data and models stay in the standard nnU-Net folders and formats, and every step runs a regular nnU-Net command, so you can continue with nnU-Net alone at any time. Models trained with the bundled `nnUNetTrainerBetterIgnoreSampling` need this trainer for prediction: use `nnworkbench-run nnUNetv2_predict …`, or make the model usable with plain nnU-Net via `nnworkbench-run reduce-checkpoints MODEL_FOLDER --reset-trainer-name --yes`, which removes what prediction does not need and sets the trainer to `nnUNetTrainer`.

</details>

<details>
<summary><b>Can I train on a cluster and keep working in the nnWorkbench GUI on my computer?</b></summary>

Yes. Use the core installation on the cluster (see *Remote machines and clusters* above) and copy the commands from the GUI (see the [CLI overview](#cli-overview)). If the cluster's `nnUNet_results` folder is mounted on your computer, the GUI shows the training progress and the validation results as if they ran locally. If it is not mounted, you can still configure training and prediction in the GUI: enter the plans, trainer, configuration and folds that exist on the cluster, and copy the command.

</details>

<details>
<summary><b>Where does my data have to be for a remote setup?</b></summary>

Each step needs the folder written by the previous one on the machine that runs it: preprocessing needs `nnUNet_raw`, training needs `nnUNet_preprocessed`, and prediction needs the model in `nnUNet_results`. The GUI on your computer uses `nnUNet_raw` for annotating and `nnUNet_results` for validation. The simplest setup is storage both machines can access, e.g. a mounted network drive; otherwise copy `nnUNet_raw` to the remote machine after each iteration and copy `nnUNet_results` back.

</details>

<details>
<summary><b>Which file formats are supported?</b></summary>

The formats nnU-Net reads: for 3D images `.nii.gz` / `.nii` (recommended), `.nrrd`, `.mha`, `.gipl` and `.tif` / `.tiff`; for 2D images `.png`, `.bmp` and `.tif`. JPEG is not supported, because its lossy compression alters the images. All images and labels of a dataset use the same file ending, set in `dataset.json`. A folder of 2D slices can be combined into one 3D volume with `nnworkbench-run stack-images` (see the [CLI overview](#cli-overview)); more in the guide under [Prepare Your Images](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/setup.md#prepare-your-images-optional).

</details>

<details>
<summary><b>Does nnWorkbench work with 2D images?</b></summary>

Yes. The nnU-Net Workflow works the same for 2D and 3D images. The Annotation Workflow also works with 2D images, but annotate them with scribbles (the brush in Napari): nnInteractive does not work on 2D images. Preprocessing, training, validation and prediction with nnU-Net work in any case.

</details>

<details>
<summary><b>Can I annotate with nnInteractive without a local GPU?</b></summary>

Yes. nnInteractive can run on a server with a GPU, while you annotate in Napari on your computer. Set up the server and connect the plugin as described in the [napari-nninteractive documentation](https://github.com/MIC-DKFZ/napari-nninteractive). Without a GPU or a server, nnInteractive runs on the CPU, which is slow (on a Mac always, see *macOS* above).

</details>

## Documentation

The **[nnWorkbench guide](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/README.md)** explains both workflows step by step, with the matching command for each step. It is also built into the GUI: **? Guide** in the top bar and **More in the guide · …** on every page.

- **[Setup](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/setup.md):** nnU-Net folders, remote machines, creating a dataset and `dataset.json`.
- **[1. Describe](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/1-describe.md)** and **[2. Define](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/2-define.md):** understanding your images, defining classes, dense or sparse labels.
- **[3. Annotate](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/3-annotate.md):** annotating efficiently with nnInteractive and scribbles.
- **[4. Train](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/4-train.md):** preprocessing, planners and GPU memory, trainers, folds and device.
- **[5. Validate](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/5-validate.md):** inspecting predictions, metrics, typical errors and the next iteration.
- **[6. Predict](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/src/nnworkbench/assets/annotation_workflow/6-predict.md):** applying and sharing a trained model.

**For AI agents:** [AGENTS.md](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/AGENTS.md) guides an agent (e.g. Claude Code or Codex) through the whole process with CLI commands, and tells it where you take over (annotating, looking at results).

**Underlying tools:**

- **[nnU-Net](https://github.com/MIC-DKFZ/nnUNet)** and its **[documentation](https://github.com/MIC-DKFZ/nnUNet/tree/master/documentation):** dataset format, planners, trainers and everything below nnWorkbench.
- **[nnInteractive](https://github.com/MIC-DKFZ/nnInteractive):** the interactive 3D segmentation model behind the annotation.
- **[napari-nninteractive](https://github.com/MIC-DKFZ/napari-nninteractive):** the Napari plugin for nnInteractive, including an nnInteractive server for annotating without a local GPU.

## Citation

If nnWorkbench helps your research, please cite it together with the methods you used: nnInteractive for the annotation, nnU-Net for preprocessing, training and prediction. The software citation is also in [`CITATION.cff`](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/CITATION.cff) (**Cite this repository** on GitHub).

**nnWorkbench**:

> Krämer, L., Isensee, F., Maier-Hein, K. H., & Dreher, K. K. (2026). nnWorkbench (Version 0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.24013948

<details>
<summary>BibTeX</summary>

```bibtex
@software{nnworkbench2026,
  author  = {Krämer, Lars and Isensee, Fabian and Maier-Hein, Klaus H. and Dreher, Kris K.},
  title   = {nnWorkbench},
  version = {0.1.0},
  year    = {2026},
  doi     = {10.5281/zenodo.24013948},
  url     = {https://github.com/MIC-DKFZ/nnWorkbench}
}
```

</details>

**nnInteractive** (annotation):

> Isensee, F.\*, Rokuss, M.\*, Krämer, L.\*, Dinkelacker, S., Ravindran, A., Stritzke, F., Hamm, B., Wald, T., Langenberg, M., Ulrich, C., Deissler, J., Floca, R., & Maier-Hein, K. (2025). nnInteractive: Redefining 3D Promptable Segmentation. https://arxiv.org/abs/2503.08373 \
> \*: equal contribution

<details>
<summary>BibTeX</summary>

```bibtex
@article{isensee2025nninteractive,
  author  = {Isensee, Fabian and Rokuss, Maximilian and Krämer, Lars and Dinkelacker, Stefan and Ravindran, Ashis and Stritzke, Florian and Hamm, Benjamin and Wald, Tassilo and Langenberg, Moritz and Ulrich, Constantin and Deissler, Jonathan and Floca, Ralf and Maier-Hein, Klaus},
  title   = {nnInteractive: Redefining 3D Promptable Segmentation},
  journal = {arXiv preprint arXiv:2503.08373},
  year    = {2025},
  url     = {https://arxiv.org/abs/2503.08373}
}
```

</details>

**nnU-Net** (preprocessing, training and prediction):

> Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., & Maier-Hein, K. H. (2021). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature Methods, 18(2), 203-211.

<details>
<summary>BibTeX</summary>

```bibtex
@article{isensee2021nnunet,
  author  = {Isensee, Fabian and Jaeger, Paul F. and Kohl, Simon A. A. and Petersen, Jens and Maier-Hein, Klaus H.},
  title   = {{nnU-Net}: a self-configuring method for deep learning-based biomedical image segmentation},
  journal = {Nature Methods},
  volume  = {18},
  number  = {2},
  pages   = {203--211},
  year    = {2021},
  doi     = {10.1038/s41592-020-01008-z}
}
```

</details>

**nnU-Net Revisited** (the residual encoder planners, including the default `nnUNetPlannerResEncL`):

> Isensee, F., Wald, T., Ulrich, C., Baumgartner, M., Roy, S., Maier-Hein, K., & Jaeger, P. F. (2024). nnU-Net Revisited: A Call for Rigorous Validation in 3D Medical Image Segmentation. MICCAI 2024. https://arxiv.org/abs/2404.09556

<details>
<summary>BibTeX</summary>

```bibtex
@inproceedings{isensee2024nnunetrevisited,
  author    = {Isensee, Fabian and Wald, Tassilo and Ulrich, Constantin and Baumgartner, Michael and Roy, Saikat and Maier-Hein, Klaus and Jaeger, Paul F.},
  title     = {{nnU-Net} Revisited: A Call for Rigorous Validation in {3D} Medical Image Segmentation},
  booktitle = {Medical Image Computing and Computer Assisted Intervention -- MICCAI 2024},
  year      = {2024},
  url       = {https://arxiv.org/abs/2404.09556}
}
```

</details>


## License

nnWorkbench is licensed under the [Apache License 2.0](https://github.com/MIC-DKFZ/nnWorkbench/blob/main/LICENSE).

> **Note:** The [nnInteractive model weights](https://huggingface.co/MIC-DKFZ/nnInteractive), downloaded on first use
> for interactive annotation, are licensed under
> [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/): **non-commercial use only**. nnU-Net and the
> rest of nnWorkbench are not affected.

## Acknowledgements

<p>
  <img src="https://raw.githubusercontent.com/MIC-DKFZ/nnWorkbench/main/src/nnworkbench/assets/images/helmholtz-imaging-logo.svg" alt="Helmholtz Imaging" height="40">
  &nbsp;&nbsp;&nbsp;&nbsp;
  <img src="https://raw.githubusercontent.com/MIC-DKFZ/nnWorkbench/main/src/nnworkbench/assets/images/dkfz-logo.svg" alt="German Cancer Research Center (DKFZ)" height="38">
</p>

This repository is developed and maintained by the Applied Computer Vision Lab (ACVL)
of [Helmholtz Imaging](https://www.helmholtz-imaging.de/).
