register

Synopsis

register -images <images.lst> [options]
register -image <image1> [-dof <dof1>] -image <image2> [-dof <dof2>]... [options]
register -image <image1> <image2>... [options]
register <image1> <image2>... [options]
register <image_sequence> [options]
register -pset <pointset1> [-dof <dof1>] -pset <pointset2> [-dof <dof2>]... [options]
register <dataset1> <dataset2>... [options]
register -pset <pointset1> <pointset2>... [options]
register -image <image1> -points <pointset1> [-dof <dof1>]... [options]

Description

Registers a set of images, polygonal surface meshes, and/or point clouds (e.g. fiducial markers). The set of input images can be comprised of multiple channels (e.g., acquired with different imaging modalities) at different time points. For longitudinal data, the temporal origin in the NIfTI header identifies the time point that each input image belongs to. How all input images and polydata sets are registered with one another is determined by an energy function. This energy function is formulated in a simplified math expression using MATLAB-style indexing for the individual input files, i.e.,

Energy function =      SIM[Image dissimilarity](I(1), I(2:end) o T)...
                +      PDM[Point set distance](T o P(1), P(2:end))...
                + 1e-3 BE[Bending energy](T)...
                +    0 LE[Linear energy](T)...
                +    0 TP[Topology preservation](T)...
                +    0 VP[Volume preservation](T)...
                +    0 LogJac[LogJac penalty](T)...
                +    0 NegJac[NegJac penalty](T)...
                +    0 Sparsity(T)

where only energy terms with non-zero weights are active during the registration. The image dissimilarity term is only added if at least two input images are given. Similarly, only with at least two input polydata sets, the PDM term is added. These energy terms are referenced in the configuration file using their respective identifier in square brackets. For example, to change the weight of the bending energy smoothness term, add “Bending energy weight = 0.01” to the configuration file or use the -par option on the command-line. To enable volume preservation, set the parameter “Volume preservation weight” to a positive value.

Output options

-dofout <file>

Write transformation to specified file.

-output <file>

Write (first) transformed source image to specified file. Given the flexibility of the energy function formulation, this option may not always give the desired output and is limited to standard pairwise image registration using a single image dissimilarity term. Use transform-image command with the -dofout file as input otherwise.

Input options

-image <file>...

Input image to be registered. The order in which the images are given on the command-line corresponds to the image indices used in the registration energy formulation. The first input image has index 1 and is denoted by the symbol I(1) in the image similarity term.

-pset <file>...

Input points, curve(s), surface(s), or other simplicial complex(es). The order in which the point set files are given on the command-line corresponds to the point set indices used in the registration energy formulation. The first input point set has index 1 and is denoted by the symbol P(1), C(1), or S(1), respectively, in the point set distance measure (PDM) term.

-dof <file>

Specifies a pre-computed affine transformation to be applied to the preceeding image and/or polydata. Note the difference to -dofin, which specifies an initial estimate of the -dofout transformation. (default: none)

-dof_i <file>

Specifies a pre-computed affine transformation whose inverse is to be applied to the preceeding image and/or polydata (see -dof). (default: none)

-images <file>

Text file with N lines containing the file names of each 2D/3D input image, optionally followed by a space character and the associated (relative) acquisition time (in ms). If no acquisition time is given, the temporal offset of the image header is used. Images specified as positional arguments are read before the images named in this (then optional) text file and the index of the images given in the text file are offset by the number of images named as positional arguments or using -image, respectively.

-psets <file>

Equivalent to -images, but for point sets (-pset).

-dofs <file>

Read names of affine transformations of input images from specified text file. The affine transformations are set as if the images had been transformed by these before. Hence, these transformations are not part of the output transformation. The text file must contain on each line the basename of the input image followed by the corresponding affine transformation file. Input images not included are assumed to not be further pre-transformed. (default: none)

-dofins <file>

Read pairwise transformations from the files specified in the given text file which lists for each pair-wise transformation the corresponding target image, followed by the source image and the name of the transformation file. Note that the target and source image names must be listed in the -images list file. (default: none)

-dofin <file>

Read initial transformation from file if -dofins not specified. When no initial guess is given, and the first transformation model is a homogeneous transformation, a translation which aligns image foreground centers of mass is used. The identity mapping (‘Id’ or ‘identity’) is used as initial guess for deformable models unless the <file> argument is ‘guess’ to align the centers. If the given transformation cannot be used directly as starting point of the registration, it will be approximated by an instance of the chosen transformation model at the initial resolution level. The input transformation may thus be of different type than the output transformation of the registration. (default: guess or Id/identity)

-mask <file>

Reference mask which defines the domain within which to evaluate the energy function (i.e. image similarity). The registered images will thus be resampled within the corresponding domain of the world system. By default, the foreground of the target image defines this domain.

Configuration options

-parin <file>

Read parameters from configuration file. If <file> is “stdin” or “cin”, the parameters are read from standard input instead. (default: none)

-par <name> <value>

Specify any parameter value usually found in -parin file as command argument. The other configuration options are convenient shortcuts for commonly customized parameters.

-model <m1>[+<m2>...]

“Transformation model”. Multiple models can be concatenated using a plus sign. (default: Rigid+Affine+FFD)

-multi-level-model, -composition None|Sum|Fluid|LogSum

“Multi-level transformation model” used to combine global affine transformation with the local free-form deformations at each resolution level. (default: Sum)

-sim <value>

Specifies concrete “Image (dis-)similarity” measure of SIM “Energy function” term. Most often used measures are MSE/SSD, NMI, and NCC/LNCC. (default: NMI)

-bins <n>

“No. of bins” used for NMI image similarity measure.

-window <width> [<units> [<type>]]

Local window used for (local) NCC/LNCC image similarity measure. A window <width> of zero corresponds to a global NCC measure. The <units> can be either “vox” (default) or “mm”. The type of the window can be “box” (default), “sigma”, “fwhm”, or “fwtm”, where the latter correspond to a Gaussian window with either the specified standard deviation, full width at half maximum, or full width at tenth maximum, respectively. The default is a box window with uniform weights for each voxel.

-interp, -interpolation <mode>

“Image interpolation” mode. (default: “Fast linear [with padding]”)

-extrap, -extrapolation <mode>

“Image extrapolation” mode. (default: “Default” for used interpolation mode)

-levels <from> [<to>]

Image/FFD resolution levels. The <from> number corresponds to the “No. of levels”, and the <to> number is the final level which is 1 by default. When images are given as input, the default number of levels is 4 and 1 otherwise.

-level <n>

Alias for -levels <n> <n> which only performs the registration on a single level.

-bg, -background, -padding <value>

“Background value” (threshold) of input and output images (default: none)

-ds <width>

“Control point spacing” of free-form deformation on highest resolution level. (default: 4x min voxel size)

-be <w>

“Bending energy weight” of free-form deformation. (default: 0.001)

-le <w> [<lambda>]

“Linear energy weight” of free-form deformation. (default: 0)

-tp <w>

“Topology preservation weight” of free-form deformation. (default: 0)

-vp <w>

“Volume preservation weight” of free-form deformation. (default: 0)

-lj, -jl, -log-jac, -jac <w>

“LogJac penalty weight” of free-form deformation. For a classic FFD transformation model this penalty term is equivalent to the volume preservation term. When applied to the SVFFD model, however, this penalty applies to the Jacobian determinant of the velocity field. (default: 0)

-nj, -neg-jac <w>

“NegJac penalty weight” of free-form deformation. For a classic FFD transformation model this penalty term is equivalent to the volume preservation term. When applied to the SVFFD model, however, this penalty applies to the Jacobian determinant of the velocity field. (default: 0)

-parout <file>

Write parameters to the named configuration file. Note that after initialization of the registration, an interim configuration file is written. This file is overwritten once the registration finished with final configuration used during the course of the registration. (default: none)

Standard options

-v, -verbose [n]

Increase/Set verbosity of output messages. (default: 1)

-debug [level]

Increase/Set debug level for output of intermediate results. (default: 0)

-version [major.minor]

Print version and exit or set version to emulate.

-revision

Print revision (or version) number only and exit.

-h, -help

Print help and exit.

Terminal options

-color, -nocolor

Enable/disable colored output. (default: off)

Parallelization options

-threads <n>

Use maximal <n> threads for parallel execution. (default: automatic)