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 nonzero 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 nonzero 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 
1e6 
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 
stddev. 
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 
stddev. 
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 Bspline 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, violawells} 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 
1e5 
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 Bspline 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 linearelastic 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. 