autoreg¶

Registers one or several pairs of images with a linear transformation, a nonlinear one, or both, by minimising a composite loss with PyTorch's automatic differentiation.

nitorch autoreg LOSS [FACTOR] -fix FILE... [OPTIONS] -mov FILE... [OPTIONS]
                     [LOSS-OPTIONS]
                ...
                TRANSFORM [FACTOR] [OPTIONS] [REGULARISER [VALUE...]]...
                ...
                [OPTIMISER [OPTIONS]]...
                [-all DEFAULTS]
                [-prg [BOOL]] [-pad PAD [UNIT]] [-v [LEVEL]] [-cpu | -gpu [N]]

Description¶

An autoreg command describes a registration problem in three parts, which you can write in any order and repeat as needed:

• What to match. One or more loss groups each name a similarity measure (mutual information, mean squared error, ...) and the fixed and moving images it compares. Several loss groups add up to a composite loss, which lets you register on several contrasts at once, or mix intensity images and segmentations.
• What to optimise. One transformation group selects the kind of transformation: a linear one (translation, rigid, similitude or affine), a nonlinear one (a free-form deformation or a diffeomorphism), or one of each. The transformation groups also carry the regularisation of the nonlinear field.
• How to optimise. Optionally, one or more optimiser groups choose the algorithm (Adam, gradient descent, OGM or L-BFGS) and its settings. Adam is the default.

The moving images are warped to the fixed images, and the loss is minimised with respect to the parameters of the transformation by back-propagation. Because the loss is evaluated by resampling the moving images, interpolation and boundary options are available for each image.

By default, the linear parameters are freed in stages (translations, then rotations, then scaling, then shears) and the nonlinear field is then refined from a coarse grid to a fine one. See Optimisation.

autoreg always writes the estimated transformations, and by default also writes each moving image with the transformation applied. See Outputs.

Command-line grammar¶

The command line is a sequence of groups. A group is opened by a group tag and extends over the options that follow it, up to the next tag that the group does not recognise. The same short tag can therefore mean different things in different groups (-o writes an image inside -fix and -mov, and a transformation inside a transformation group; -lr sets the learning rate of an optimiser or a relative learning rate of a transformation; -h is the help except inside an -lbfgs group, where it is the history size).

Any argument that begins with a dash is a tag, unless it is a number: -1, -.5 and -1e-3 are values, so negative numbers can be given wherever a value is expected (factors, -w, -t, -lr, ...). Every argument that is not a tag must belong to a group. File names therefore cannot start with a dash.

Running nitorch autoreg with no arguments prints the help. If the command line cannot be parsed, or if the registration fails, autoreg prints [ERROR] followed by a message on the standard error stream, without a traceback, and exits with status 1.

The following tags open a group:

Other top-level options (-prg, -pad, -v, -cpu, -gpu, -h) take effect wherever they appear but also end the group that precedes them.

Loss groups¶

A loss group starts with the loss tag, optionally followed by a numeric FACTOR that multiplies this loss in the sum (default 1). It then contains a -fix and a -mov image block, in any order, and finally options of the loss.

-mi 0.5 -fix target.nii.gz -mov source.nii.gz -b 64

An image block starts with -fix (aliases --fixed, -trg, --target) or -mov (aliases --moving, -src, --source), followed by one or more file names, followed by options that apply to this image only (see the image block options). The block ends at the first tag that it does not recognise, so options of the loss itself, such as -b 64 above, must come after the image blocks, and the options -inter, -bnd, -ex and -pyr that follow a -fix or -mov belong to that image.

The -oth loss is not a loss. It declares extra moving images that are carried along: they are warped with the final transformation, but play no role in the optimisation. It takes a -mov block only.

An image can have several channels, and several files given to the same block are concatenated into one multi-channel image (they must have the same voxel grid). To select channels inside a 4D file, append their 1-based indices to the file name, separated by commas: dwi.nii.gz,1,3 loads the first and the third volumes. Fixed and moving images of the same group should have the same number of channels, which are matched one to one.

Transformation groups¶

A transformation group starts with its tag, optionally followed by a numeric FACTOR that scales all its regularisers (default 1), then any of the options of the transformation tables. Regularisers have the form -abs, -mem, -ben, -le, each followed by its strength.

-dif 2 -mem 0.002 -ben 0.4 -pyr 1:3

Optimiser groups¶

An optimiser group is its tag followed by its options. Several optimiser groups are run one after the other, in the order given, at each stage of the registration.

-adam -nit 100 -lr 0.05  -lbfgs -nit 20

Default values¶

The -all group holds values that apply everywhere (see the table). A value set in a group wins over the one in -all, which wins over the built-in default. An -all group ends at the first tag it does not recognise, so it can be placed anywhere, for example first:

nitorch autoreg -all -nit 200 -mi -fix ... -mov ... -aff

Arguments¶

autoreg has no positional arguments. Files are given in -fix, -mov and -init options.

A bare -- adds the arguments that follow it to the -fix or -mov file list just before it, or to the value of a preceding -o or -r, so that file names can start with a dash. Other options need ./-name.

Options¶

Losses¶

All images are rescaled before the registration, channel by channel, so that the 1st percentile of intensities maps to 0 and the 95th percentile to 1.

For -dice, the images can be soft segments (one channel per class) or integer label volumes, which are converted on the fly to one-hot maps, with one channel per label.

Options common to all loss groups¶

These options apply to the group as a whole. They are written after the image blocks.

Options -inter, -bnd, -ex and -pyr can also be given at the group level. To affect both images, put them straight after the loss tag (and its factor), before -fix and -mov. They are then the default for both image blocks.

Mutual information (-mi)¶

With several channels, the loss is the average of the mutual information of each pair of channels.

Dice (-dice)¶

The loss is the soft Dice coefficient averaged over labels; the background is excluded.

Image block options¶

These options follow a file list in a -fix or -mov block.

Transformations¶

Linear transformations¶

The linear transformation maps world coordinates of the moving images to world coordinates of the fixed images.

Nonlinear transformations¶

The nonlinear field lives on the mean space of all the fixed and moving images that are not excluded with -exc, at the resolution of its pyramid level (see Pyramids). Its displacements are expressed in voxels of that grid. The extent of the grid can be enlarged with -pad.

A -dif field is stored at the resolution of the current pyramid level. An -ffd field is different: its parameters live on a grid of nodes whose size is set by -g, and which keeps this size across pyramid levels. The pyramid only changes the resolution of the dense field that the nodes encode.

Options common to all transformations¶

The -stop option is also accepted in a transformation group but has no effect there.

Regularisers¶

Regularisers apply to the nonlinear field (to the velocity field for -dif, unless -sd is given). Each one is followed by an optional strength; a bare tag means a strength of 1. The strengths are multiplied by the FACTOR of the transformation group.

If you give none of them, the following set is used: -abs 0.0001 -mem 0.001 -ben 0.2 -le 0.05 0.2. As soon as you give at least one regulariser, the others are switched off: -dif -ben 0.5 penalises the bending energy only. The built-in help says that only the bending energy is penalised by default, which is not what the code does. No regulariser is placed on linear transformations.

Optimisers¶

Defaults (-all)¶

The built-in help also lists -init and -exc as default options; the code does not accept them in an -all group.

Other options¶

Boolean options¶

-exc, -z, -sd and -prg take an optional boolean. A bare flag means true. Otherwise the value is true, false, yes or no in any case, or an integer, where 0 means false and any other integer means true. Any other word is an error, for example -z/--zero expects <bool>, got 'maybe'.

A value that cannot be read as a number is also reported with the name of the option that received it, as in -w/--weights expects <float>, got 'abc'.

Optimisation¶

The parameters are not all optimised from the start. With progressive freeing, the registration runs through stages. At each stage, every optimiser group is run in turn, each up to its maximum number of iterations, over the parameters that are free so far, and then more parameters are freed. The order is:

1. The linear transformation, in steps. Translations first; then rotations (for -rig, the final step); then isotropic scaling (for -sim, the final step); then zooms and shears (for -aff). A step is skipped if the chosen group does not contain it.
2. The nonlinear field, from the coarsest to the finest resolution level (see Pyramids). Once free, the linear parameters keep being optimised.

With -prg false, all parameters are free from the first stage. A nonlinear field with several pyramid levels then gets one more stage for each finer level.

Within a stage, the learning rate is reduced automatically when the loss stops improving (PyTorch's ReduceLROnPlateau). The stage stops after -nit iterations, or as soon as the learning rate of every parameter group has decayed to -stop times its initial value. With -ls, each step is shortened by backtracking until it lowers the loss, and discarded if no shortened step does. For -dif, the gradient is preconditioned with the Green's function of the regulariser.

Pyramids¶

A pyramid level \(l\) is an image downsampled by a factor \(2^{l-1}\) with average pooling, so that level 1 is the full resolution. -pyr takes a list of levels, or ranges written [START]:STOP[:STEP] with both ends included: -pyr 1:3 is -pyr 1 2 3. Ranges and single levels can be mixed.

The -pyr option has two roles.

• On an image (in a -fix or -mov block, in a loss group, or in -all), it lists the resolutions at which the images are compared. The loss is the average of the losses over all listed levels, which are evaluated at every iteration. The levels are not a coarse-to-fine schedule.
• On a nonlinear transformation, it lists the resolution levels of the deformation field. The field is created at the coarsest listed level, and progressive freeing then moves to each finer level in turn, up-sampling the current estimate.

To get a classic coarse-to-fine registration, pass the same levels to both, which -all -pyr 1 2 3 does.

Outputs¶

Transformations. The estimated transformations are always written. The default names are written in the current directory.

Linear transformations are written as world-to-world (RAS-to-RAS) affine matrices in the FreeSurfer LTA format, so FreeSurfer tools can read them.

You can change this with -o in the transformation group or in -all. The value is either a switch or a path template. true, yes, 1, or no value at all, keep the default path ({name}{ext}); false, no or 0 skip the output; anything else is the path to write to. In a template, {name} is replaced by the name of the transformation (rigid, affine, ffd, diffeo, ...) and {ext} by its default extension. A directory must be part of the path, so -o results/{name}{ext} works if results exists. A template with any other key, such as {nmae}, is rejected before the fit starts with an Invalid path template error. The linear matrix, which is left-multiplied onto the orientation matrix of the moving image to align it with the fixed image, can be applied to images with reslice; see that page for the options that apply linear and velocity transformations, and their inverses.

Images. Each image block can write two kinds of output.

• The updated image keeps its voxel grid and its data (except for the nonlinear part, which is applied by resampling in the original space). The linear transformation is folded into the orientation matrix in the header. By default, the updated version of every moving image is written, to {dir}/{base}.registered{ext}. Fixed images are not written unless you give -o; -o false turns the output off for a moving image. For a fixed image, the inverse transformation is applied, so that it is aligned with the moving image.
• The resliced image is resampled onto the grid of the other image of the pair: a moving image is resliced to the fixed grid and a fixed image to the moving grid. It is not written unless you give -r. Its default name is {dir}/{base}.resliced{ext}.

Both -o and -r take the same kind of value as the transformation output: true, yes, 1 or no value selects the default name, false, no or 0 skips the output, and anything else is a path template. In a template, {dir}, {base} and {ext} are replaced by the directory, the base name and the extension (including .nii.gz) of the corresponding input file; other keys are rejected as above.

When a block has several input files, give either one value per file or a single value for all of them. For example, -mov a.nii b.nii -o true false writes the updated version of a.nii only. A single value is repeated for every file only if it is true or false, or a template that contains {base} or {dir} and so gives each file its own name: -o {base}.moved{ext}. A single plain path is accepted only when the block has one file; with more, every file would be written to the same place, and autoreg stops with an error that suggests a template. Any other number of values is also an error: -o expects 1 value per input file (2), or a single template; got 3.

Examples¶

Register a FLAIR image to a T1-weighted image with a rigid transformation. This writes rigid.lta and FLAIR.registered.nii.gz:

nitorch autoreg -mi -fix T1w.nii.gz -mov FLAIR.nii.gz -rig

Add a nonlinear component on top of a similitude. A diffeomorphic field is estimated after the linear parameters, with the default regularisation:

nitorch autoreg -mi -fix T1w.nii.gz -mov FLAIR.nii.gz -sim -dif

Also write the moving image on the grid of the fixed image, with a rigid transformation and the output name of the transformation chosen explicitly:

nitorch autoreg -mi -fix T1w.nii.gz -mov FLAIR.nii.gz -r -rig -o FLAIR_to_T1w.lta

Register a template to tissue maps of a subject, and write the subject's maps in the space of the template. The template is the moving image, so -o in the -fix block warps the fixed images to it:

nitorch autoreg -cat -fix c1T1w.nii.gz c2T1w.nii.gz -o -mov TPM.nii -dif -rig

Run a multi-resolution registration with at most 200 iterations per stage. The same three levels apply to the images and to the deformation field:

nitorch autoreg -all -nit 200 -pyr 1:3 \
        -mi -fix T1w.nii.gz -mov FLAIR.nii.gz \
        -aff -dif -ben 0.4

Optimise with gradient descent and a backtracking line search:

nitorch autoreg -mi -fix T1w.nii.gz -mov FLAIR.nii.gz -rig -gd -ls

Use Adam first and refine with L-BFGS:

nitorch autoreg -mi -fix T1w.nii.gz -mov FLAIR.nii.gz -aff \
        -adam -nit 100 -lbfgs -nit 20 -h 50

Register intensity images and carry a segmentation along, with nearest-neighbour interpolation. The segmentation is not part of the loss:

nitorch autoreg -mi -fix T1w.nii.gz -mov FLAIR.nii.gz \
        -oth -mov FLAIR_seg.nii.gz -inter 0 \
        -rig

See also¶

• register: the newer registration command.
• reslice: apply the estimated transformations to images.
• compose, vexp: combine and integrate transformations.
• Spatial transformations.