nnUNetPipeline
: Structured DICOM-to-NIfTI Conversion for Deep Learning#
TL;DR#
nnUNetPipeline
is a variation of AutoPipeline
that simplifies the messy reality of clinical imaging data by converting raw DICOM files into the nnUNet standard.
It's fast, reproducible, and designed for segmentation workflows using CT/MR with RTSTRUCT
or SEG
.
Why nnUNetPipeline
?#
nnUNet
is the standard for training deep automated segmentation models on medical images.
nnUNetPipeline
:
- Crawls and indexes DICOM files
- Links scans to associated segmentations
- Applies optional transforms (e.g., resample, window/level)
- Matches ROI labels to your standard keys
- Outputs clean NIfTI files for training with
nnUNet
Comparison to AutoPipeline
#
Feature | nnUNetPipeline |
Autopipeline |
---|---|---|
Primary Use Case | Converts clinical DICOMs into nnUNet-ready | General-purpose medical image processing |
Modalities | Specific pairs of CT/MR with RTSTRUCT or SEG |
Flexible, supports any modality list |
ROI Matching | Requires roi_match_map for nnUNet compatibility |
Optional, with more flexibility for handling ROIs |
Mask Saving Strategy | Uses MaskSavingStrategy (e.g., sparse_mask ) |
Saves each ROI as a separate mask file |
ROI Strategy | ROIMatchStrategy.MERGE for overlaps |
Default is ROIMatchStrategy.SEPARATE |
Key Features#
- ✅ Supports modality pairs:
["CT", "SEG"]
,["MR", "SEG"]
,["CT", "RTSTRUCT"]
,["MR", "RTSTRUCT"]
- ✅ Supports different
mask_saving_strategy
options ("label_image"
,"sparse_mask"
,"region_mask"
) - ✅ Matches ROIs via regex patterns (
"GTV": ["gtv", "Gross.*Volume"]
) - ✅ Provides
nnUNet
-specific scripts for preprocessing and training
Mask Saving Options#
When converting segmentations (e.g., from RTSTRUCT
or SEG
) into NIfTI masks for training, you have multiple options depending on how you want to handle overlapping regions and label representation.
label_image
#
- Single-channel label image
- Each voxel contains an integer label corresponding to a single region.
- Limitations:
- Does not allow overlapping ROIs.
- Each voxel can belong to only one region.
- Use this when you're certain there are no overlaps, and you want compatibility with standard segmentation workflows.
sparse_mask
#
- Single-channel label image
- Each voxel contains an integer label corresponding to a single region.
- Overlapping regions are allowed in the input, but only one label is assigned per voxel in the output.
- When overlaps occur, the label from the last matching region (highest index) is assigned, and earlier labels are overwritten.
- User can decide the order when passing in ROI map.
- Lossy if regions overlap, since only one region label is retained per voxel and all others are discarded.
region_mask
(Recommended for nnU-Net)#
- Bitmask encoding of overlapping ROIs
- Inspired by nnU-Net’s region-based training.
- Every unique combination of ROIs gets its own integer label — preserving overlap information without loss.
- Enables multi-class region training with full overlap preservation.
How It Works#
Internally, this uses a bitmask approach. Each voxel stores a value representing a combination of active ROI channels (up to 32 ROIs supported).
Imagine you have three regions of interest (ROIs):
GTV
assigned to bit 0 → value2^0 = 1
Cord
assigned to bit 1 → value2^1 = 2
Parotid_L
assigned to bit 2 → value2^2 = 4
Each voxel in the mask encodes a combination of these ROIs using bitwise addition.
Voxel Location | Present ROIs | Bitmask Calculation | Encoded Value |
---|---|---|---|
(10, 30, 40) | GTV | 2^0 |
1 |
(12, 30, 40) | Cord | 2^1 |
2 |
(15, 30, 40) | Parotid_L | 2^2 |
4 |
(17, 30, 40) | GTV + Parotid_L | 2^0 + 2^2 = 2^0 + 2^2 = 1 + 4 |
5 |
(20, 30, 40) | GTV + Cord + Parotid_L | 2^0 + 2^1 + 2^2 = 1 + 2 + 4 |
7 |
Choosing the Right Strategy#
Option | Overlaps | Lossless |
---|---|---|
label_image |
❌ | ✅ |
sparse_mask |
✅ | ❌ |
region_mask |
✅ | ✅ |