Parameter Maps

Overview

Parameter maps are the primary mechanism for configuring image registration in elastix. A parameter map is a collection of key-value pairs that specifies the components and settings of a registration procedure — including the transform type, optimizer, metric, and multi-resolution strategy. SimpleITK provides a programmatic interface for creating, modifying, reading, and writing these maps.

File Format

Elastix parameter files are plain text files where each line contains a key and one or more values enclosed in parentheses. Comments begin with //. String values are quoted; numeric values are not. When multiple values are provided, they typically correspond to per-resolution settings.

// An affine registration parameter file
(FixedInternalImagePixelType "float")
(MovingInternalImagePixelType "float")

(Registration "MultiResolutionRegistration")
(Interpolator "BSplineInterpolator")
(Metric "AdvancedMattesMutualInformation")
(Optimizer "AdaptiveStochasticGradientDescent")
(ResampleInterpolator "FinalBSplineInterpolator")
(Resampler "DefaultResampler")
(Transform "AffineTransform")

(NumberOfResolutions 4)
(MaximumNumberOfIterations 500)
(AutomaticParameterEstimation "true")
(AutomaticTransformInitialization "true")

For a comprehensive reference of all available parameters, see the elastix 5.2.0 manual.

Getting Default Parameter Maps

SimpleITK provides pre-configured default parameter maps for common registration scenarios:

• translation — Translation only

• rigid — Rotation and translation (6 DOF in 3D)

• affine — Affine transformation (12 DOF in 3D)

• bspline — Non-rigid B-spline deformation

• groupwise — Simultaneous registration of multiple images

C#C++JavaLuaPython

// Get a default parameter map for a common registration type
var parameterMap = SimpleITK.GetDefaultParameterMap("translation");

// Print parameter map to see its contents
SimpleITK.PrintParameterMap(parameterMap);

Modifying Parameter Maps

Parameter maps behave like dictionaries mapping string keys to vectors of string values. You can override any default setting by assigning new values to specific keys:

C#C++JavaLuaPython

// Modify parameter map entries (values are VectorString)
VectorString transformValue = new VectorString();
transformValue.Add("AffineTransform");
parameterMap["Transform"] = transformValue;

VectorString iterValue = new VectorString();
iterValue.Add("512");
parameterMap["MaximumNumberOfIterations"] = iterValue;

VectorString samplesValue = new VectorString();
samplesValue.Add("8192");
parameterMap["NumberOfSpatialSamples"] = samplesValue;

Multi-Stage Registration

Complex registration problems benefit from a coarse-to-fine approach. Use SetParameterMap for the first stage, then AddParameterMap for subsequent stages. Each stage uses the result of the previous stage as initialization. A common progression is translation → affine → B-spline:

C#C++JavaLuaPython

// Multi-stage registration: translation -> affine -> bspline
ElastixImageFilter elastixImageFilter = new ElastixImageFilter();
elastixImageFilter.SetFixedImage(fixedImage);
elastixImageFilter.SetMovingImage(movingImage);

elastixImageFilter.SetParameterMap(SimpleITK.GetDefaultParameterMap("translation"));
elastixImageFilter.AddParameterMap(SimpleITK.GetDefaultParameterMap("affine"));

var bsplineMap = SimpleITK.GetDefaultParameterMap("bspline");
VectorString gridSpacing = new VectorString();
gridSpacing.Add("8.0");
bsplineMap["FinalGridSpacingInPhysicalUnits"] = gridSpacing;
elastixImageFilter.AddParameterMap(bsplineMap);

elastixImageFilter.LogToConsoleOff();
Image resultImage = elastixImageFilter.Execute();

// Retrieve transform parameter maps from the result
VectorOfParameterMap transformParameterMaps = elastixImageFilter.GetTransformParameterMaps();

Reading and Writing Parameter Maps

Parameter maps can be saved to and loaded from elastix-format text files. This enables sharing registration configurations, reproducing results, and applying the same strategy to multiple datasets:

C#C++JavaLuaPython

// Write a parameter map to a file
SimpleITK.WriteParameterFile(parameterMap, "parameters.txt");

// Read a parameter map from a file
var readMap = SimpleITK.ReadParameterFile("parameters.txt");

See Also

• elastix 5.2.0 manual — Comprehensive documentation of all elastix parameters

• elastix model zoo — Pre-configured parameter files for various registration tasks

• Registration and Transformation — Basic registration example

• SimpleITK ElastixImageFilter API