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.