ITK Registration

5.4.6 verified Mon Apr 27 auth: no python

The ITK Registration module provides algorithms for image registration, including rigid, affine, deformable (BSpline, Demons), and groupwise methods. This Python package wraps the ITK C++ registration framework. Current version 5.4.6, with a stable release cadence.

pip install itk-registration

Common errors

error NameError: name 'FixedImageType' is not defined ↓

cause Forgot to define the image type before using it in registration templates.

fix

Define FixedImageType = itk.Image[itk.F, 2] (or itk.D) before creating the registration object.

error RuntimeError: Exception thrown in SimpleITK ImageRegistrationMethod_New ↓

cause Mismatch between template types and actual image dimensions or pixel type.

fix

Ensure FixedImageType and MovingImageType dimensions and pixel types match your images.

error TypeError: in method 'New', argument 1 of type 'itkImageToImageMetricv4...' ↓

cause Incorrect metric type template parameters.

fix

Use metric = itk.MeanSquaresImageToImageMetric[FixedImageType, MovingImageType].New() with matching types.

Warnings

gotcha When using itk.imread, specify the pixel type explicitly with a numeric value or itk.ctype('float'). Default is itk.ctype('float') but be consistent with template types. ↓

fix Use PixelType = itk.ctype('float') and itk.imread('image.nii', PixelType).

gotcha ImageRegistrationMethod templates require both FixedImageType and MovingImageType. The types must match the actual image dimensions and pixel type. ↓

fix Define FixedImageType and MovingImageType with correct dimensions (e.g., itk.Image[itk.F, 3] for 3D float).

deprecated The 'itk.ImageRegistrationMethod' (v4 style) is still available but ITK v6 introduces a new registration framework. Users should migrate to the new API once stable. ↓

fix Monitor https://discourse.itk.org for migration guides to ITK 6 registration.

Imports

itk
wrong
```
import itkRegistration
```
correct
```
import itk
```
All modules are accessed via the 'itk' package.

Quickstart

Basic affine registration of 2D images using MeanSquares metric.

import itk

# Define image types
PixelType = itk.ctype('float')
FixedDimension = 2
MovingDimension = 2
FixedImageType = itk.Image[PixelType, FixedDimension]
MovingImageType = itk.Image[PixelType, MovingDimension]

# Read images
fixed_image = itk.imread('fixed_image.nii', PixelType)
moving_image = itk.imread('moving_image.nii', PixelType)

# Set up registration
RegistrationType = itk.ImageRegistrationMethod[FixedImageType, MovingImageType]
registration = RegistrationType.New()
registration.SetFixedImage(fixed_image)
registration.SetMovingImage(moving_image)

# Set metric (e.g., MeanSquares)
metric = itk.MeanSquaresImageToImageMetric[FixedImageType, MovingImageType].New()
registration.SetMetric(metric)

# Set transform (e.g., Affine)
transform = itk.AffineTransform[itk.D, 2].New()
registration.SetInitialTransform(transform)

# Set optimizer
optimizer = itk.RegularStepGradientDescentOptimizerv4.New()
registration.SetOptimizer(optimizer)

# Set interpolator
interpolator = itk.LinearInterpolateImageFunction[MovingImageType, itk.D].New()
registration.SetInterpolator(interpolator)

# Run registration
registration.Update()

# Get result
result = registration.GetOutput()
itk.imwrite(result, 'registered_image.nii')