Image registration command file reference

The registration command file uses the “ini file” format. There are two possible sections: GLOBAL, and STAGE. There should be exactly one GLOBAL section, and there can be multiple STAGE sections.

In general, the GLOBAL section defines the input files and output files for a single registration. Each STAGE section defines a single processing stage within a registration pipeline.

Global options

The GLOBAL section has only a limited set of allowed parameters. However, some GLOBAL parameters are also allowed in a STAGE section, as noted below.

option

type

value

fixed

GLOBAL

Filename of fixed (reference) image

moving

GLOBAL

Filename of moving (target) image

fixed_roi

GLOBAL, STAGE

Filename of a binary mask for the fixed image; only pixels which are non-zero in this image will contribute to the registration result

moving_roi

GLOBAL, STAGE

Filename of a binary mask for the moving image; only pixels which are non-zero in this image will contribute to the registration result

fixed_landmarks

GLOBAL, STAGE

Filename of a list of landmark locations within the fixed image which can be used to guide the registration

moving_landmarks

GLOBAL, STAGE

Filename of a list of landmark locations within the moving image which can be used to guide the registration

warped_landmarks

GLOBAL, STAGE

Filename of output landmarks, warped by the registration result

xform_in

GLOBAL

Initial guess for transform

xform_out

GLOBAL, STAGE

Filename of output transform

vf_out

GLOBAL, STAGE

Filename of output transform, as vector field

img_out

GLOBAL, STAGE

Filename of warped image

img_out_fmt

GLOBAL, STAGE

Output format, which must be either “auto” (default), which means the filename extenstion is used to determine the file format, or “dicom”, which interprets img_out as a directory name to output the dicom files

img_out_type

GLOBAL, STAGE

Data type of the output image. Either “auto” (default), or an image type string: char, uchar, short, ushort, int, uint, float, or double

resample_when_linear

GLOBAL, STAGE

Setting this field to true will cause plastimatch to resample the moving image to the fixed image geometry when warping the image with a linear (translation, rigid, similarity, affine) transform. Setting this field to false will cause plastimatch to warp the image by changing the image origin and direction cosines. In versions through 1.8.x, the default is true. In version 1.9.0, the default value will be changed to false.

logfile

GLOBAL

Filename for output log of registration progress

Stage options

Each STAGE section generates a computational stage within a computational sequence. Therefore, a command file with three STAGE sections will have three registration stages. The stages are executed in the same order as they appear in the command file. The registration result from a previous stage is passed as the starting point to the next stage. After all three stages are complete, the output files are generated.

As a general rule, all parameters are optional. When they are specified, they are used. When they are not specified, they are set automatically. There are different ways they are automatically set.

  • Any parameters not specified in the first stage are given default values.

  • Any parameters not specified in subsequent stages are given the same value they had in the previous stage.

  • Some parameters can have a value of “auto.” That means the value can be chosen dynamically based on registration inputs or optimization results.

A registration stage is classified according to its transform (xform), its implementation, and its optimizer. Only certain combinations are possible, as shown in the following table.

xform

impl

optim

align_center

itk

N/A

translation

itk

amoeba, rsg

plastimatch

grid_search

rigid (default)

itk

amoeba, versor (default)

affine

itk

amoeba, rsg

bspline

itk

lbfgs, lbfgsb

plastimatch (default)

lbfgsb (default), steepest

vf

itk

demons

plastimatch

demons

The following specific parameters are used to refine the optimization. Depending on the choice of xform, impl, and optim a different set of specific parameters are available.

option

xform+optim+impl

default

units

description

background_max

any+any+any

-999.0

image intensity

This is a threshold value that is used to automatically determine the registration region of interest.

convergence_tol

any+not demons+any

1e-6

score

Stop optimization if change in score between iterations falls below this value

default_value

any+any+any

-999.0

image intensity

(needs description)

demons_acceleration

vf+demons+plastimatch

1.0

unitless

(needs description)

demons_filter_width

vf+demons+plastimatch

[3 3 3]

voxels

(needs description)

demons_homogenization

vf+demons+plastimatch

1.0

unitless

(needs description)

demons_std

vf+demons+any

6.0

mm

width of demons smoothing kernel

demons_gradient_type

vf+demons+itk

symmetric

enumeration

Type of gradient that will be used to compute update force, choose from {symmetric, fixed, warped_moving, mapped_moving}

demons_smooth_update_field

vf+demons+itk

false

bool

Set whether the update field is smoothed

demons_std_update_field

vf+demons+itk

1

std-dev.

Width of Gaussian used to smooth update field

demons_smooth_deformation_field

vf+demons+itk

true

bool

Set whether the deformation field is smoothed

demons_std_deformation_field

vf+demons+itk

1

std-dev.

Width of Gaussian used to smooth deformation field

demons_step_length

vf+demons+itk

1

mm

maximum update step length. 0 implies no restriction

grad_tol

any+{lbfgs}+itk

1.5

score per unit parameter

Gradient convergence tolerance for LBFGS optimizer. The optimizer can be asked to stop when the gradient magnitude is below this number.

grid_spac

bspline+any+any

[20 20 20]

mm

Spacing between control points in B-spline grid. The minimum spacing is 4*(Pixel Size); if a smaller size is specified, it will be adjusted upward.

gridsearch_min_overlap

translation+grid_search +plastimatch

[0.5 0.5 0.5]

percent

Minimum amount of overlap required during grid search. The smaller of the two images must overlap the larger image by at least this amount in three dimensions.

histoeq

vf+demons+itk

0

boolean

specify whether or not to equalize intensity histograms before registration

landmark_stiffness

bspline+any+plastimatch

1.0

float

Relative contribution of landmark distance in cost function

lbfgsb_mmax

bspline+any+plastimatch

(AUTO)

integer

Maximum number of histories retained by the lbfgsb optimizer.

mattes_fixed_minVal, mattes_fixed_maxVal

bspline+any+itk

0

image intensity

Min and max intensity values of intensity range for fixed image used for MI calculation. If values are not set by user min and max values will be calculated from images. Only used for optimized version of itk implementation.

mattes_moving_minVal, mattes_moving_maxVal

bspline+any+itk

0

image intensity

Min and max intensity values of intensity range for moving image used for MI calculation. If values are not set by user min and max values will be calculated from images. Only used for optimized version of itk implementation.

max_its

any+any+any

25

iterations

Maximum number of iterations (or sometimes function evaluations) performed within a stage.

max_step

any+{versor, rsg}+itk

10.0

scaled parameters

(needs description)

metric

any+not demons+any

mse

string

Cost function metric to be optimized. The choices are {mse, mi, nmi, mattes, viola-wells} when impl=itk, and {gm, mse, mi} when impl=plastimatch.

mi_histogram_bins

any+any+any

20

number of histogram bins

Only used for plastimatch mi metric, and itk mattes metric.

min_its

any+any+any

2

iterations

(needs description)

min_step

any+{versor, rsg}+itk

0.5

scaled parameters

(needs description)

num_hist_levels_equal

vf+demons+itk

1000

unsigned int

set number of histogram levels for histogram equalization

num_matching_points

vf+demons+itk

500

unsigned int

set number of histogram levels for histogram equalization

num_samples

any+any+itk

-1

voxels

Number of voxels to randomly sample to score the cost function. Only used for itk mattes metric. If this parameter is not specified, num_samples_pct will be used instead.

num_samples_pct

any+any+itk

0.3

percent

Percent of voxels to randomly sample to score the cost function. Only used for itk mattes metric.

num_substages

translation+grid_search +plastimatch

1

stages

Number of times to refine the grid search. By default, the first search is global, and the subsequent searches refine the result within a local region.

optim_subtype

vf+demons+itk

fsf

string

Demons algorithm subtype used in ITK implementation. Values are {fsf(default), diffeomorphic, log_domain, sym_log_domain}.

pgtol

any+{lbfgsb}+any

1e-5

score per unit parameter

Projected gradient tolerance for LBFGSB optimizer. The optimizer can be asked to stop when the projected gradient is below this number. The projected gradient is defined as max{proj g_i | i = 1, …, n} where proj g_i is the ith component of the projected gradient.

regularization

bspline+any+plastimatch

analytic

string

Implmentation variant for plastimatch B-spline regularization. Choices are { analytic, numeric, semi_analytic }.

diffusion_penalty

bspline+any+plastimatch

0

unitless

Relative contribution of first derivative regularization as compared to metric.

curvature_penalty

bspline+any+plastimatch

0

unitless

Relative contribution of second derivative regularization as compared to metric.

linear_elastic_multiplier

bspline+any+plastimatch

1

unitless

Relative contribution of linear-elastic regularization as compared to metric.

third_order_penalty

bspline+any+plastimatch

0

unitless

Relative contribution of third derivative regularization as compared to metric.

total_displacement_penalty

bspline+any+plastimatch

0

unitless

Relative contribution of total displacement regularization as compared to metric.

lame_coefficient_1

bspline+any+plastimatch

0

Pa

First Lame’ coefficient

lame_coefficient_2

bspline+any+plastimatch

0

Pa

Second Lame’ coefficient

res

Alias for “res_vox”

res_mm

any+any+any

automatic

mm

Subsampling rate (in mm) for fixed and moving images. This can be either “automatic”, a single integer (for isotropic subsampling), or three integers (for anisotropic subsampling). For example, “3 3 3” would have voxels sampled once every 3 mm. In automatic mode, image is subsampled to the maximum rate which yields less than 100 voxels in each dimension.

res_mm_fixed

any+any+any

automatic

mm

Equivalent to res_mm, but only applied to the fixed image.

res_mm_moving

any+any+any

automatic

mm

Equivalent to res_mm, but only applied to the moving image.

res_vox

any+any+any

automatic

voxels

Subsampling rate (in voxels) for fixed and moving images. This can be either “automatic”, a single integer (for isotropic subsampling), or three integers (for anisotropic subsampling). For example, “3 3 3” would have one voxel for every 3 voxels in the input image. In automatic mode, image is subsampled to the maximum rate which yields less than 100 voxels in each dimension.

res_vox_fixed

any+any+any

automatic

voxels

Equivalent to res_vox, but only applied to the fixed image.

res_vox_moving

any+any+any

automatic

voxels

Equivalent to res_vox, but only applied to the moving image.

rsg_grad_tol

any+{rsg, versor}+itk

0.001

score per unit parameter

Gradient magnitude tolerance for RSG and Versor optimizers. The optimizer can be asked to stop when the cost function is in a stable region where the gradient magnitude is smaller than this value.

ss

Alias for “res_vox”

ss_fixed

any+any+any

automatic

voxels

Alias for “res_vox_fixed”

ss_moving

any+any+any

automatic

voxels

Alias for “res_vox_moving”

threading

any+any+plastimatch

openmp

string

Threading method used for parallel cost and gradient computations. The choices are {cuda, opencl, openmp, single}. If an unsupported threading choice is made (such as cuda with demons), the nearest valid choice will be used.

thresh_mean_intensity

vf+demons+itk

0

boolean

Set the threshold at mean intensity flag. If true, only source (reference) pixels which are greater than the mean source (reference) intensity is used in the histogram matching. If false, all pixels are used.

translation_scale_factor

any+{rigid, affine}+itk

1000

ratio

Sets the relative scale of translation when compared to rotation, scaling, and shearing.