SimpleElastix Documentation

Image registration is the process of finding a spatial mapping (a transform) that aligns a moving image ($I_M$) to a fixed image ($I_F$).

SimpleElastix implements this as an optimization problem using three core components:

1. Transform ($T$): Represents the spatial mapping of points from the fixed image domain to the moving image domain. It deforms the moving image to match the fixed image.
2. Similarity Metric: A quantitative measure of how well the images match. The metric provides a value that the optimizer attempts to minimize (or maximize) to achieve alignment. It can be based on pixel intensities, point positions, or pre-computed features.
3. Optimizer: Adjusts the parameters of the transform in small steps to minimize the cost function (the metric). The process repeats until convergence criteria are met.

To improve robustness and avoid local minima, SimpleElastix often employs a multi-resolution approach (starting with smoothed images and gradually increasing detail) and can include regularization terms to penalize unwanted or non-smooth transformations.

To perform image registration using the ImageRegistrationMethod class, you must select and configure four essential components that define the registration instance:

1. Transformation: Defines the mapping between the fixed and moving images (e.g., TranslationTransform, AffineTransform, BSplineTransform). The framework modifies the parameters returned by the transform's GetParameters() method.
2. Similarity Metric: Reflects the relationship between image intensities (e.g., MeanSquares, MattesMutualInformation). Note that all metrics are minimized; for metrics that typically maximize (like mutual information), SimpleITK negates the value internally.
3. Optimizer: The algorithm used to find the optimal transform parameters (e.g., Gradient Descent, Nelder-Mead, L-BFGS-B).
4. Interpolator: Determines how pixel values are calculated between grid points (e.g., linear interpolation, which is the default).

Use SetMetricAsX(), SetOptimizerAsX(), and SetInterpolator() to configure these components.

Samplers

Determines which locations in the images are evaluated by the metric. Controlled via the ImageSampler parameter.

• grid: Selects coordinates on a regular grid (effectively down-sampling without smoothing).
• random: Selects a user-specified number of voxels randomly.
• random coordinate: Samples positions between voxels using interpolation.
• full: Samples all voxels.

Interpolators

Used to evaluate image intensity at non-grid positions during transformation.

• NearestNeighborInterpolator: Fast, low quality. Best for binary images.
• LinearInterpolator: Fast and highly optimized. Recommended for use with random coordinate sampler during optimization.
• BSplineInterpolator / BSplineInterpolatorFloat: High quality. For final result generation, use a higher-order version (e.g., $N=3$).

Note on Final Resampling: To use an interpolator for the final output image, prepend the name with Final (e.g., FinalBSplineInterpolatorFloat).

SimpleITK uses JSON files to wrap ITK filters. A template file consists of a single data object {} containing string keys and various value types (strings, numbers, lists [], or sub-objects {}).

Example of a LaplacianRecursiveGaussian filter definition:

{
  "name" : "LaplacianRecursiveGaussianImageFilter",
  "template_code_filename" : "ImageFilter",
  "template_test_filename" : "ImageFilter",
  "doc" : "",
  "number_of_inputs" : 1,
  "pixel_types" : "BasicPixelIDTypeList",
  "output_pixel_type" : "float",
  "members" : [
    {
      "name" : "Sigma",
      "type" : "double",
      "default" : "1.0",
      "doc" : "",
      "briefdescriptionSet" : "",
      "detaileddescriptionSet" : "Set Sigma value. Sigma is measured in the units of image spacing.",
      "briefdescriptionGet" : "",
      "detaileddescriptionGet" : "Set Sigma value. Sigma is measured in the units of image spacing."
    }
  ],
  "tests" : [
    {
      "tag" : "default",
      "description" : "Simply run with default settings",
      "settings" : [],
      "tolerance" : 0.0001,
      "inputs" : [
        "Input/RA-Float.nrrd"
      ]
    }
  ],
  "briefdescription" : "Computes the Laplacian of Gaussian (LoG) of an image.",
  "detaileddescription" : "Computes the Laplacian of Gaussian (LoG) of an image by convolution with the second derivative of a Gaussian.",
  "itk_module" : "ITKImageFeature",
  "itk_group" : "ImageFeature"
}

Unlike many image libraries that treat images as simple arrays, SimpleITK treats images as objects occupying a physical region in space. This means an image is defined not just by its pixel values, but by its spatial metadata. Two images with identical pixel data and spacing are considered different if they occupy different locations or orientations in the physical world.

An image's physical region is defined by four key metadata components:

1. Origin: The location in the world coordinate system of the voxel with all zero indexes.
2. Spacing: The distance between pixels along each dimension.
3. Size: The number of pixels in each dimension.
4. Direction cosine matrix: A matrix (in row-major order) representing the direction of each axis.

Because images represent physical structures, developers must ensure that all images used in a pipeline use consistent metric units (e.g., all in mm or all in cm). SimpleITK does not enforce a specific unit, but it assumes consistency.

# Example of creating a 2D image with specific spatial metadata
import SimpleITK as sitk

# Create a 2D image, 10x10 size, with 5 float channels
image = sitk.Image([10, 10], sitk.sitkVectorFloat32, 5)

# Set spatial metadata
image.SetOrigin((3.0, 14.0))
image.SetSpacing((0.5, 2.0))