0
# Registration Framework
1

2
Comprehensive image registration system for aligning medical images, time series data, and multi-modal datasets. ITK's registration framework supports multiple transform types, similarity metrics, optimization algorithms, and multi-resolution strategies with both modern functional interfaces and traditional component-based approaches.
3

4
## Capabilities
5

6
### High-Level Registration Interface
7

8
Modern functional interface for common registration tasks with automatic parameter selection and sensible defaults.
9

10
```python { .api }
11
def registration_method_v4(fixed_image, moving_image, 
12
                          metric: str = 'mutual_information',
13
                          transform: str = 'affine', 
14
                          optimizer: str = 'gradient_descent',
15
                          sampling_percentage: float = 0.2,
16
                          multi_resolution_levels: int = 3) -> dict:
17
    """
18
    Perform image registration using ITKv4 registration framework.
19
    
20
    Parameters:
21
    - fixed_image: Reference image (target for alignment)
22
    - moving_image: Image to be transformed to match fixed image
23
    - metric: Similarity metric ('mutual_information', 'mean_squares', 'correlation')
24
    - transform: Transform type ('translation', 'rigid', 'affine', 'bspline')
25
    - optimizer: Optimization algorithm ('gradient_descent', 'regular_step_gradient_descent')
26
    - sampling_percentage: Fraction of pixels to use for metric computation
27
    - multi_resolution_levels: Number of resolution levels for multi-scale registration
28
    
29
    Returns:
30
    - Dictionary containing: final_transform, metric_value, optimizer_stop_condition
31
    """
32

33
# Specialized registration functions
34
def rigid_registration(fixed_image, moving_image, initial_transform=None) -> dict: ...
35
def affine_registration(fixed_image, moving_image, initial_transform=None) -> dict: ...
36
def deformable_registration(fixed_image, moving_image, grid_size: Sequence[int] = None) -> dict: ...
37
def demons_registration(fixed_image, moving_image, iterations: int = 50, 
38
                       standard_deviations: float = 1.0) -> dict: ...
39
```
40

41
### Registration Components
42

43
Core components of the ITK registration framework for building custom registration pipelines.
44

45
```python { .api }
46
# Main registration method
47
class ImageRegistrationMethodv4[TFixedImage, TMovingImage, TTransform]:
48
    """
49
    Primary registration class coordinating all registration components.
50
    """
51
    def SetFixedImage(self, image: TFixedImage) -> None: ...
52
    def SetMovingImage(self, image: TMovingImage) -> None: ...
53
    def SetMetric(self, metric: MetricType) -> None: ...
54
    def SetOptimizer(self, optimizer: OptimizerType) -> None: ...
55
    def SetTransform(self, transform: TTransform) -> None: ...
56
    def SetInitialTransform(self, transform: TransformType) -> None: ...
57
    def SetMovingInitialTransform(self, transform: TransformType) -> None: ...
58
    def SetFixedInitialTransform(self, transform: TransformType) -> None: ...
59
    def SetNumberOfLevels(self, levels: int) -> None: ...
60
    def SetSmoothingSigmasPerLevel(self, sigmas: Sequence[float]) -> None: ...
61
    def SetShrinkFactorsPerLevel(self, factors: Sequence[Sequence[int]]) -> None: ...
62
    def StartRegistration(self) -> None: ...
63
    def GetTransform(self) -> TTransform: ...
64
    def GetOptimizer(self) -> OptimizerType: ...
65
    def GetMetric(self) -> MetricType: ...
66

67
# Transform initialization
68
class CenteredTransformInitializer[TTransform, TFixedImage, TMovingImage]:
69
    """Initialize transforms using image centers and moments."""
70
    def SetTransform(self, transform: TTransform) -> None: ...
71
    def SetFixedImage(self, image: TFixedImage) -> None: ...
72
    def SetMovingImage(self, image: TMovingImage) -> None: ...
73
    def MomentsOn(self) -> None: ...
74
    def GeometryOn(self) -> None: ...
75
    def InitializeTransform(self) -> None: ...
76
```
77

78
### Similarity Metrics
79

80
Various similarity measures for comparing fixed and moving images during registration.
81

82
```python { .api }
83
# Mutual information (for multi-modal registration)
84
class MutualInformationImageToImageMetricv4[TFixedImage, TMovingImage]:
85
    """
86
    Mutual information metric for multi-modal image registration.
87
    """
88
    def SetNumberOfHistogramBins(self, bins: int) -> None: ...
89
    def SetUseMovingImageGradientFilter(self, use: bool) -> None: ...
90
    def SetUseFixedImageGradientFilter(self, use: bool) -> None: ...
91
    def SetUseFixedSampledPointSet(self, use: bool) -> None: ...
92
    def GetValue(self) -> float: ...
93
    def GetDerivative(self) -> DerivativeType: ...
94
    def GetValueAndDerivative(self) -> tuple[float, DerivativeType]: ...
95

96
# Mean squares (for mono-modal registration)
97
class MeanSquaresImageToImageMetricv4[TFixedImage, TMovingImage]:
98
    """Mean squares metric for mono-modal image registration."""
99
    def GetValue(self) -> float: ...
100
    def GetDerivative(self) -> DerivativeType: ...
101

102
# Correlation metric
103
class CorrelationImageToImageMetricv4[TFixedImage, TMovingImage]:
104
    """Correlation metric for mono-modal registration."""
105
    def GetValue(self) -> float: ...
106

107
# Advanced metrics
108
class MattesMutualInformationImageToImageMetricv4[TFixedImage, TMovingImage]:
109
    """Mattes mutual information with improved efficiency."""
110
    def SetNumberOfHistogramBins(self, bins: int) -> None: ...
111
    def SetUseExplicitPDFDerivatives(self, use: bool) -> None: ...
112

113
class DemonsImageToImageMetricv4[TFixedImage, TMovingImage]:
114
    """Demons metric for deformable registration."""
115
    def SetIntensityDifferenceThreshold(self, threshold: float) -> None: ...
116
```
117

118
### Optimization Algorithms
119

120
Optimizers for iteratively improving transform parameters during registration.
121

122
```python { .api }
123
# Gradient descent optimization
124
class GradientDescentOptimizerv4:
125
    """
126
    Gradient descent optimizer with adaptive step size.
127
    """
128
    def SetLearningRate(self, rate: float) -> None: ...
129
    def SetNumberOfIterations(self, iterations: int) -> None: ...
130
    def SetConvergenceMinimumValue(self, value: float) -> None: ...
131
    def SetConvergenceWindowSize(self, size: int) -> None: ...
132
    def SetMinimumConvergenceValue(self, value: float) -> None: ...
133
    def SetDoEstimateLearningRateAtEachIteration(self, estimate: bool) -> None: ...
134
    def SetDoEstimateLearningRateOnce(self, estimate: bool) -> None: ...
135
    def GetCurrentIteration(self) -> int: ...
136
    def GetValue(self) -> float: ...
137
    def GetCurrentPosition(self) -> ParametersType: ...
138

139
# Regular step gradient descent
140
class RegularStepGradientDescentOptimizerv4:
141
    """Regular step gradient descent with step length control."""
142
    def SetLearningRate(self, rate: float) -> None: ...
143
    def SetMinimumStepLength(self, length: float) -> None: ...
144
    def SetRelaxationFactor(self, factor: float) -> None: ...
145
    def SetNumberOfIterations(self, iterations: int) -> None: ...
146
    def SetGradientMagnitudeTolerance(self, tolerance: float) -> None: ...
147

148
# Advanced optimizers
149
class ConjugateGradientLineSearchOptimizerv4:
150
    """Conjugate gradient optimization with line search."""
151
    def SetLearningRate(self, rate: float) -> None: ...
152
    def SetNumberOfIterations(self, iterations: int) -> None: ...
153

154
class LBFGSBOptimizerv4:
155
    """Limited-memory BFGS optimizer with bounds."""
156
    def SetCostFunctionConvergenceFactor(self, factor: float) -> None: ...
157
    def SetProjectedGradientTolerance(self, tolerance: float) -> None: ...
158
    def SetMaximumNumberOfIterations(self, iterations: int) -> None: ...
159
    def SetMaximumNumberOfEvaluations(self, evaluations: int) -> None: ...
160
    def SetMaximumNumberOfCorrections(self, corrections: int) -> None: ...
161
```
162

163
### Multi-Resolution Framework
164

165
Multi-scale registration for improved robustness and convergence.
166

167
```python { .api }
168
class MultiResolutionImageRegistrationMethodv4[TFixedImage, TMovingImage]:
169
    """
170
    Multi-resolution registration with automatic pyramid generation.
171
    """
172
    def SetNumberOfLevels(self, levels: int) -> None: ...
173
    def SetSmoothingSigmasPerLevel(self, sigmas: Sequence[float]) -> None: ...
174
    def SetShrinkFactorsPerLevel(self, factors: Sequence[Sequence[int]]) -> None: ...
175
    def SetSmoothingSigmasAreSpecifiedInPhysicalUnits(self, physical: bool) -> None: ...
176
    def GetNumberOfLevels(self) -> int: ...
177
    def GetSmoothingSigmasPerLevel(self) -> Sequence[float]: ...
178
    def GetShrinkFactorsPerLevel(self) -> Sequence[Sequence[int]]: ...
179

180
# Image pyramid generation
181
class MultiResolutionPyramidImageFilter[TInputImage, TOutputImage]:
182
    """Generate multi-resolution image pyramids."""
183
    def SetNumberOfLevels(self, levels: int) -> None: ...
184
    def SetStartingShrinkFactors(self, factors: Sequence[int]) -> None: ...
185
    def SetUseShrinkImageFilter(self, use: bool) -> None: ...
186
    def GetOutput(self, level: int) -> TOutputImage: ...
187
```
188

189
## Usage Examples
190

191
### Basic Registration Workflow
192

193
```python
194
import itk
195

196
# Load images
197
fixed_image = itk.imread('fixed.png')
198
moving_image = itk.imread('moving.png')
199

200
# Perform affine registration using high-level interface
201
result = itk.registration_method_v4(
202
    fixed_image=fixed_image,
203
    moving_image=moving_image,
204
    metric='mutual_information',
205
    transform='affine',
206
    multi_resolution_levels=3
207
)
208

209
# Extract registration results
210
final_transform = result['final_transform']
211
metric_value = result['metric_value']
212
print(f"Final metric value: {metric_value}")
213

214
# Apply transform to moving image
215
resampled = itk.resample_image_filter(
216
    moving_image,
217
    transform=final_transform,
218
    reference_image=fixed_image
219
)
220

221
# Save registered image
222
itk.imwrite(resampled, 'registered.png')
223
```
224

225
### Custom Registration Pipeline
226

227
```python
228
import itk
229

230
# Load images
231
fixed_image = itk.imread('fixed.mhd')
232
moving_image = itk.imread('moving.mhd')
233

234
# Set up transform
235
transform = itk.AffineTransform[itk.D, 3].New()
236

237
# Initialize transform using image centers
238
initializer = itk.CenteredTransformInitializer[
239
    itk.AffineTransform[itk.D, 3],
240
    itk.Image[itk.F, 3],
241
    itk.Image[itk.F, 3]
242
].New()
243
initializer.SetTransform(transform)
244
initializer.SetFixedImage(fixed_image)
245
initializer.SetMovingImage(moving_image)
246
initializer.MomentsOn()
247
initializer.InitializeTransform()
248

249
# Set up metric
250
metric = itk.MutualInformationImageToImageMetricv4[
251
    itk.Image[itk.F, 3],
252
    itk.Image[itk.F, 3]
253
].New()
254
metric.SetNumberOfHistogramBins(50)
255

256
# Set up optimizer
257
optimizer = itk.GradientDescentOptimizerv4.New()
258
optimizer.SetLearningRate(1.0)
259
optimizer.SetNumberOfIterations(100)
260
optimizer.SetConvergenceMinimumValue(1e-6)
261
optimizer.SetConvergenceWindowSize(10)
262

263
# Set up registration method
264
registration = itk.ImageRegistrationMethodv4[
265
    itk.Image[itk.F, 3],
266
    itk.Image[itk.F, 3],
267
    itk.AffineTransform[itk.D, 3]
268
].New()
269

270
registration.SetFixedImage(fixed_image)
271
registration.SetMovingImage(moving_image)
272
registration.SetMetric(metric)
273
registration.SetOptimizer(optimizer)
274
registration.SetTransform(transform)
275

276
# Configure multi-resolution
277
registration.SetNumberOfLevels(3)
278
registration.SetSmoothingSigmasPerLevel([4.0, 2.0, 0.0])
279
registration.SetShrinkFactorsPerLevel([[4, 4, 4], [2, 2, 2], [1, 1, 1]])
280

281
# Execute registration
282
registration.StartRegistration()
283

284
# Get results
285
final_transform = registration.GetTransform()
286
final_parameters = final_transform.GetParameters()
287
print(f"Final transform parameters: {final_parameters}")
288
```
289

290
### Deformable Registration Example
291

292
```python
293
import itk
294

295
def deformable_registration_demons(fixed_image, moving_image, iterations=50):
296
    """Perform deformable registration using Demons algorithm."""
297
    
298
    # Create demons filter
299
    demons = itk.DemonsRegistrationFilter[
300
        itk.Image[itk.F, 3],
301
        itk.Image[itk.F, 3],
302
        itk.Vector[itk.F, 3]
303
    ].New()
304
    
305
    demons.SetFixedImage(fixed_image)
306
    demons.SetMovingImage(moving_image)
307
    demons.SetNumberOfIterations(iterations)
308
    demons.SetStandardDeviations(1.0)
309
    demons.SetUseImageSpacing(True)
310
    
311
    # Create initial deformation field
312
    initial_field = itk.Image[itk.Vector[itk.F, 3], 3].New()
313
    initial_field.SetRegions(fixed_image.GetRequestedRegion())
314
    initial_field.SetOrigin(fixed_image.GetOrigin())
315
    initial_field.SetSpacing(fixed_image.GetSpacing())
316
    initial_field.SetDirection(fixed_image.GetDirection())
317
    initial_field.Allocate()
318
    initial_field.FillBuffer(itk.Vector[itk.F, 3]([0.0, 0.0, 0.0]))
319
    
320
    demons.SetInitialDeformationField(initial_field)
321
    
322
    # Execute registration
323
    demons.Update()
324
    deformation_field = demons.GetOutput()
325
    
326
    # Warp moving image using deformation field
327
    warper = itk.WarpImageFilter[
328
        itk.Image[itk.F, 3],
329
        itk.Image[itk.F, 3],
330
        itk.Image[itk.Vector[itk.F, 3], 3]
331
    ].New()
332
    
333
    warper.SetInput(moving_image)
334
    warper.SetDeformationField(deformation_field)
335
    warper.SetOutputSpacing(fixed_image.GetSpacing())
336
    warper.SetOutputOrigin(fixed_image.GetOrigin())
337
    warper.SetOutputDirection(fixed_image.GetDirection())
338
    warper.SetEdgePaddingValue(0.0)
339
    
340
    warper.Update()
341
    return warper.GetOutput(), deformation_field
342

343
# Usage
344
fixed = itk.imread('fixed_brain.nii.gz')
345
moving = itk.imread('moving_brain.nii.gz')
346

347
registered, field = deformable_registration_demons(fixed, moving, iterations=100)
348

349
itk.imwrite(registered, 'registered_brain.nii.gz')
350
itk.imwrite(field, 'deformation_field.nii.gz')
351
```
352

353
### Time Series Registration
354

355
```python
356
import itk
357

358
def register_time_series(image_list, reference_index=0):
359
    """Register a time series of images to a reference timepoint."""
360
    
361
    reference_image = image_list[reference_index]
362
    registered_images = [reference_image]  # Reference doesn't need registration
363
    transforms = []
364
    
365
    for i, moving_image in enumerate(image_list):
366
        if i == reference_index:
367
            transforms.append(None)
368
            continue
369
            
370
        print(f"Registering timepoint {i} to reference {reference_index}")
371
        
372
        # Perform rigid registration for time series (assuming small motion)
373
        result = itk.registration_method_v4(
374
            fixed_image=reference_image,
375
            moving_image=moving_image,
376
            metric='mean_squares',
377
            transform='rigid',
378
            multi_resolution_levels=2
379
        )
380
        
381
        transform = result['final_transform']
382
        transforms.append(transform)
383
        
384
        # Apply transform
385
        registered = itk.resample_image_filter(
386
            moving_image,
387
            transform=transform,
388
            reference_image=reference_image
389
        )
390
        
391
        registered_images.append(registered)
392
        
393
    return registered_images, transforms
394

395
# Usage example (assuming list of cardiac images)
396
# cardiac_images = [itk.imread(f'cardiac_{i:03d}.png') for i in range(20)]
397
# registered_cardiac, transforms = register_time_series(cardiac_images, reference_index=0)
398
```