nnU-Net Documentation

nnU-Net is a semantic segmentation framework that automatically adapts its pipeline to a dataset by analyzing training data, creating a dataset fingerprint, and configuring U-Net variants.

Key workflows include:

• Dataset Preparation: Preparing your data for the framework.
• Training: Running the training workflow to build models.
• Inference: Using trained models to segment new data.

If you are using the older version (v1), please use the dedicated v1 branch or consult the migration guide.

PrimusV3 was developed to address a bottleneck in PrimusV2 where the channel dimension grew too slowly relative to spatial downsampling, causing heavy representation compression.

Key differences:

• Channel Scaling: PrimusV2 scales channels modestly (32 $\rightarrow$ 128). PrimusV3 scales channels aggressively (32 $\rightarrow$ 1024) to offset spatial downsampling.
• Skip Connections: PrimusV3 uses a direct skip connection where each spatial resolution is projected to the final embedding dimension and added to the token sequence using learnable scales ($\Sigma \text{scale}_i \cdot \text{proj}_i$). This creates composite tokens of varying kernel sizes ($k8, k4, k2$).
• Parameter Distribution: PrimusV3 concentrates more parameters in the patch embedding ($\sim$60M) compared to previous versions.

nnU-Net adapts its pipeline using three types of parameter decisions derived from the dataset fingerprint (which includes image sizes, spacings, and intensity information):

1. Fixed parameters: Stable defaults that do not change per dataset.
2. Rule-based parameters: Heuristics derived directly from the dataset fingerprint (used to determine preprocessing, target spacing, patch size, and network topology).
3. Empirical parameters: Decisions based on comparisons, such as selecting the best configuration or determining postprocessing steps.

nnU-Net v2 uses MetaLogger to distribute logs to multiple destinations.

• LocalLogger: Always enabled. It is the source of truth for training curves and generates the progress.png file in the fold output folder.
• External loggers (e.g., WandbLogger): Optional.

By default, the following values are logged per epoch:

• mean_fg_dice
• ema_fg_dice
• dice_per_class_or_region
• train_losses
• val_losses
• lrs
• epoch start and end timestamps

Logging state is saved and restored during checkpoint resumption to ensure training curves remain continuous.

In nnU-Net V2, configurations are managed via plans.json files. These files contain two types of settings:

1. Global settings: Applied to all configurations in the file (e.g., image_reader_writer, label_manager, foreground_intensity_properties_by_modality).
2. Local settings: Stored within the configurations dictionary, these are specific to an individual configuration (e.g., spacing, patch_size, batch_size, network_arch_class_name).

Configurations can use the inherits_from key to inherit settings from another configuration, allowing you to create variations without duplicating the entire setup.

If you want to train nnU-Net on your own dataset, follow the structured path for new users:

1. Installation and setup: Set up your environment.
2. Prepare a dataset: Format your data according to nnU-Net requirements.
3. Plan and preprocess: Run the planning and preprocessing steps.
4. Train models: Execute the training pipeline.

The nnunetv2/dataset_conversion folder contains multiple example scripts designed to help you convert custom datasets into the nnU-Net format.

Note: These scripts are templates and cannot be run exactly as provided. You must open them and update the file paths to match your local environment. Use the script that most closely resembles your data structure as a starting point.

To scale to multiple GPUs, do not simply increase the VRAM target to the sum of all GPUs, as this may create patch sizes too large for individual cards.

Instead, follow these steps:

1. Run nnUNetv2_plan_experiment for the VRAM budget of one single GPU.
2. Manually edit the generated plans JSON file to increase the batch_size using configuration inheritance.
3. Add a new entry to the configurations dictionary in the JSON file.
4. Train using the -num_gpus flag.

Example: If one GPU has a batch size of 2 and you are scaling to 8 GPUs, set the new batch size to 16.

After setting up the dataset, run the default nnU-Net planning and preprocessing for dataset ID 311 using the 3d_fullres configuration.

nnUNetv2_plan_and_preprocess -d 311 -c 3d_fullres