MaskRegistration

MaskRegistration is a tool for aligning segmentation masks between different DICOM series using SimpleITK.

Registration Steps:

1. Convert the mask file to DICOM format in a temporary directory
2. If auto-detect mode: try both slice directions (normal and reverse), compare results by number of preserved labels and pixels, pick the better one
3. Optionally upsample target Z-axis by subpixel factor for finer registration
4. Use ResampleImageFilter with nearest neighbor interpolation to align mask with target geometry
5. If subpixel was used: downsample back using OR-logic (if any sub-voxel is positive, result is positive)
6. Save result as NIFTI file

Installation

# Clone repository
git clone https://github.com/ludgerradke/MaskRegistration
cd MaskRegistration

# Install dependencies
uv sync

Web Interface

The web interface provides an interactive viewer for comparing source and target DICOM images with mask overlay.

uv run maskregistration-web

Opens browser at http://localhost:8000.

UI Layout

Area	Description
Left Sidebar	Load Source/Target DICOM, view spatial overlap, settings, export
Viewer	Curtain comparison with drag handle, slice navigation, zoom
Right Panel	Optional manual transform (Offset, Rotation, Scale)

Workflow

1. Load source DICOM and mask
2. Load target DICOM
3. Registration runs automatically
4. Use curtain to compare alignment
5. Optionally adjust with manual transforms
6. Export registered mask

Command Line Interface

uv run maskregistration -d1 <source_dicom> -m <mask> -d2 <target_dicom> -o <output>

Required arguments:

• -d1, --input_dcm1 - Path to source DICOM folder
• -m, --input_mask - Path to mask file (NIFTI format)
• -d2, --input_dcm2 - Path to target DICOM folder
• -o, --output_mask - Path to output NIFTI file

Optional arguments:

• --reverse - Slice direction: auto (default), true, or false
• --subpixel N - Upsample factor for preserving small structures (default: 1)

Example:

uv run maskregistration -d1 dicom1 -m mask.nii.gz -d2 dicom2 -o output.nii.gz --subpixel 9

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Format code
uv run black .

License

GNU General Public License 3