simplereg¶

Pairwise affine + nonlinear registration of a moving image to a fixed image, with a classical -m MOVING -f FIXED interface. It is meant as the entry point for people who want a deformable registration without learning the nested syntax of register. For an affine-only registration, use affreg (or simplereg --nonlin none).

nitorch simplereg -m FILE -f FILE [-i FILE]
                  [--fwhm VAL [UNIT]] [--pad VAL [UNIT]] [--bound BND]
                  [--order N] [--rescale [MN] MX] [--discretize [N]]
                  [-a FILE] [-w FILE] [-x FILE] [-r FILE]
                  [-l LOSS] [-k SIZE... [UNIT]] [-s [BOOL]]
                  [--affine [{translation,rigid,similitude,affine,none}]]
                  [--no-affine] [-z {gn,lbfgs,powell}]
                  [-n N] [-t TOL] [--line-search N]
                  [--nonlin {svf,shoot,smalldef,none}] [--no-nonlin]
                  [--penalty F] [--absolute F] [--membrane F]
                  [--bending F] [--lame F [F]]
                  [--nonlin-optimizer {gn,lbfgs}] [--nonlin-iter N]
                  [--outer-iter N] [-p LEVEL... | --no-pyramid]
                  [-v [LEVEL]] [--cpu [THREADS] | --gpu [ID]]

Description¶

simplereg is a thin wrapper: it reads its options, builds the equivalent register command line, and runs it. The command

nitorch simplereg -m FLAIR.nii.gz -f T1w.nii.gz

is equivalent to

nitorch register --verbose 0 --cpu \
    @loss nmi @@fix T1w.nii.gz -o false @@mov FLAIR.nii.gz \
        -o '{dir}/{base}.moved{ext}' -r False \
    @affine rigid -o '{dir}/{name}.lta' \
        @@optim powell -n 50 -t 1e-05 -s wolfe \
    @nonlin svf -o '{dir}/{name}.nii.gz' \
        @@optim unset \
    @optim interleaved \
    @pyramid --levels 0 1 2

so everything said on the register page about losses, the position of the affine, the regularisation of the nonlinear part, the pyramid and the output files applies here. What simplereg fixes for you:

• One pair of images (one -m, one -f) and one loss.
• An affine part, rigid (6 parameters) by default, placed symmetrically (sym). --affine TYPE chooses another model (translation, similitude, or affine); a bare --affine (no value) fits a full affine (12 parameters).
• A nonlinear part, a stationary velocity field (svf) by default, or geodesic shooting (shoot) or a small deformation field (smalldef) with --nonlin. Its regularisation defaults to those of register.
• Both parts are optimised jointly (@optim interleaved): at each pyramid level, --outer-iter passes alternate between the affine and the nonlinear parts.
• The default loss is normalised mutual information. The affine optimiser is Powell's method with this loss; otherwise both optimisers are chosen by register (Gauss-Newton when the loss has a Hessian, L-BFGS otherwise).
• The preprocessing options (--fwhm, --pad, --bound, --order, --rescale, --discretize) apply to both images. When they are not given, the defaults of register apply.

Use --nonlin none (or its alias --no-nonlin) for an affine-only registration (then simplereg behaves like affreg), or --affine none (or --no-affine) for a nonlinear-only one. The two cannot be combined.

Outputs¶

• The affine, in LTA format, written to {dir}/{name}.lta (rigid.lta, affine.lta, ... after the --affine type) in the directory of the fixed image. Use -a (--output-affine) to choose another path. Not written with --affine none.
• The nonlinear field, written to {dir}/{name}.nii.gz (svf.nii.gz, shoot.nii.gz or smalldef.nii.gz) in the directory of the fixed image. It is a velocity field for svf and shoot (with a shoot.json file next to it), a displacement field for smalldef. Use -w (--output-warp) to choose another path. Not written with --nonlin none.
• The moved moving image, {base}.moved{ext}, in the directory of the moving image: the image carried into the space of the fixed one (minimal reslicing; see Outputs of register). It is written by default. -x changes its path, and -x false suppresses it. The fixed image is never rewritten.
• The resliced moving image, -r PATH: the moving image resampled on the grid of the fixed image through the full (affine + nonlinear) transformation. It is not written unless you ask for it.

To apply the transformations to other images, use reslice with the chain for the sym position given in Applying the transformations:

nitorch reslice FLAIR_mask.nii.gz -l2 rigid.lta -v svf.nii.gz -l2 rigid.lta \
    -t T1w.nii.gz -i 0

Options¶

Input¶

Preprocessing¶

Applied to both images. When omitted, the default of register is used.

Output¶

Loss¶

Affine¶

Nonlinear¶

Joint optimisation¶

Other¶

Examples¶

Rigid + SVF registration of a FLAIR scan to a T1-weighted scan, writing the FLAIR resliced on the T1w grid:

nitorch simplereg -m FLAIR.nii.gz -f T1w.nii.gz -r FLAIR_in_T1w.nii.gz -v

This writes rigid.lta and svf.nii.gz next to T1w.nii.gz, and FLAIR.moved.nii.gz next to FLAIR.nii.gz.

Full affine, a smoother deformation, and local correlation:

nitorch simplereg -m sub01.nii.gz -f template.nii.gz --affine \
    -l lcc -k 5 vox --penalty 5 -r sub01_in_template.nii.gz

Affine only (equivalent to affreg):

nitorch simplereg -m FLAIR.nii.gz -f T1w.nii.gz --nonlin none

Similitude + SVF, with explicit output paths:

nitorch simplereg -m sub01.nii.gz -f template.nii.gz --affine similitude \
    -a sub01_to_template.lta -w sub01_to_template.nii.gz

See also¶

• affreg — affine-only registration with a similar interface.
• register — full control: several image pairs or losses, per-image preprocessing, label maps, masks, other optimisation strategies.
• reslice — apply the transformations to other images.