CLI modules

This page documents the installed console commands from the live parser objects so the Sphinx reference stays aligned with the CLI help text.

robreg

IRLS robust 3-D image-to-image registration. Uses Iteratively Reweighted Least Squares with Tukey biweights, closely matching FreeSurfer’s mri_robust_register algorithm.

usage: robreg [-h] --mov FILE --ref FILE --out LTA [--mov-mask FILE]
              [--ref-mask FILE] [--dof {6}] [--nmax N] [--sat FLOAT] [--nosym]
              [--init-lta FILE] [--init-header | --init-centroid |
              --init-center] [--mapmov FILE] [--mapmovhdr FILE] [--keep-dtype]
              [--outliers FILE] [--device DEVICE] [--verbose] [--debug]

Named Arguments

--mov

Moving (source) image (NIfTI or MGZ).

--ref

Reference (target/fixed) image (NIfTI or MGZ).

--out

Output LTA file for the recovered transformation.

--mov-mask

Optional moving/source mask. Voxels outside the mask are ignored during registration.

--ref-mask

Optional reference/target mask. Voxels outside the mask are ignored during registration.

--dof

Possible choices: 6

Degrees of freedom: 6=rigid. IRLS robreg currently supports rigid registration only.

Default: 6

--nmax

Maximum number of outer IRLS iterations per pyramid level.

Default: 5

--sat

Tukey biweight saturation threshold (higher = less robust).

Default: 6.0

--nosym

Disable symmetric halfway-space registration and run directed registration.

--init-lta

Initialize from an existing LTA transform. When given, other init flags are ignored.

--init-header

Use header alignment only.

--init-centroid

Initialize by aligning intensity centroids in RAS.

--init-center

Initialize by aligning geometric image centers in RAS (FreeSurfer cras0-style).

--mapmov

Save the mapped moving image resliced into reference geometry.

--mapmovhdr

Save a header-only mapped moving image with no interpolation.

--keep-dtype

Write cubic –mapmov output in the moving-image dtype instead of float32. Equivalent to FreeSurfer mri_vol2vol –keep-precision.

Default: False

--outliers

Save outlier map (1 - Tukey weights) to this file (MGZ format). High values indicate poorly registered regions (outliers), low values indicate well-registered regions. Use with heat colormap in freeview for visualization.

--device

Torch device string, e.g. ‘cpu’, ‘cuda’, ‘mps’, or ‘gpu’. IRLS falls back to CPU on MPS (float64 limitation).

Default: 'gpu'

--verbose

Enable INFO-level logging.

Default: False

--debug

Enable DEBUG-level logging.

Default: False

Python module

Command-line interface for IRLS-backed robust registration (robreg).

neuroreg.cli.robreg.main(args=None)[source]

Entry point for the robreg command.

Parameters:
argslist of str or None, optional

Command-line arguments. When None, arguments are read from sys.argv.

Returns:
None

This function is invoked for its side effects: registration, optional mapped-image export, and writing the output transform.

Raises:
SystemExit

If argument parsing fails or image loading raises an exception.

Return type:

None

multireg

FreeSurfer-style multi-timepoint robust registration. Registers all time points to a deterministic initial target, constructs an unbiased mean space, and iteratively refines the template.

usage: multireg [-h] --mov FILE [FILE ...] [--mov-mask [FILE ...]]
                --template FILE [--lta [FILE ...]] [--mapmov [FILE ...]]
                [--ixforms [FILE ...]] [--average MODE] [--inittp N]
                [--seed INT] [--fixtp] [--cras-center] [--noit | --iterate N]
                [--template-eps FLOAT] [--nmax N] [--sat FLOAT] [--nosym]
                [--init-header | --init-centroid | --init-center]
                [--device DEVICE] [--keep-dtype] [--verbose] [--debug]

Named Arguments

--mov

Input time-point images (NIfTI or MGZ).

--mov-mask

Optional per-time-point masks. When given, provide one mask per –mov image.

--template

Output template image.

--lta

Optional output LTAs. When given, provide one output path per –mov image.

--mapmov

Optional output paths for mapped per-time-point images in template space, one per –mov image.

--ixforms

Optional input LTAs, one per –mov image. When given, reuse these transforms as the template-space mapping.

--average

Template aggregation mode: mean, median, 0 (=mean), or 1 (=median).

Default: 'median'

--inittp

1-based initial target time point. When omitted, choose a deterministic pseudo-random target from the inputs.

--seed

Seed used for the deterministic pseudo-random initial target selection. 0 recomputes it from the inputs.

Default: 0

--fixtp

Keep the chosen initial target as the output space instead of constructing an unbiased mean space.

Default: False

--cras-center

Center the template geometry at the average CRAS instead of the average mapped centroid.

Default: False

--noit

Stop after the initial mean-space pass instead of iteratively refining the template.

Default: False

--iterate

Maximum number of template-refinement iterations. Defaults to 6 for 3+ time points and 0 for 2 time points.

--template-eps

Stop template refinement when the maximum transform change falls below this threshold.

Default: 0.03

--nmax

Maximum number of outer IRLS iterations per pairwise registration pyramid level.

Default: 5

--sat

Tukey biweight saturation threshold for the pairwise robust registrations.

Default: 6.0

--nosym

Disable symmetric halfway-space pairwise registration.

--init-header

Use header alignment only for the pairwise registrations.

--init-centroid

Initialize the pairwise registrations by aligning intensity centroids in RAS.

--init-center

Initialize the pairwise registrations by aligning geometric image centers in RAS.

--device

Torch device string, e.g. ‘cpu’, ‘cuda’, ‘mps’, or ‘gpu’.

Default: 'gpu'

--keep-dtype

Write –mapmov outputs in each input’s own dtype and the –template output in the initial target time point’s dtype, instead of float32.

Default: False

--verbose

Enable INFO-level logging.

Default: False

--debug

Enable DEBUG-level logging.

Default: False

Python module

Command-line interface for FreeSurfer-style multi-timepoint robust registration.

neuroreg.cli.multireg.main(args=None)[source]

Run the multireg command-line interface.

Parameters:
argssequence of str or None, optional

Explicit argument list. When None, parse arguments from sys.argv.

Returns:
None

This function returns None after writing requested outputs.

Raises:
SystemExit

If argument parsing fails or an input image cannot be loaded.

Return type:

None

coreg

3-D image-to-image registration. Defaults to the MRI_coreg-style Powell path; use –method gd for the legacy PyTorch gradient-descent path.

usage: coreg [-h] --mov FILE --ref FILE --out LTA [--mapmov FILE]
             [--mapmovhdr FILE] [--keep-dtype] [--mov-mask FILE]
             [--ref-mask FILE] [--dof {3,6,9,12}] [--method {powell,gd}]
             [--n_iters N] [--level-iters LEVEL_ITERS] [--lr LR]
             [--min-voxels MIN_VOXELS] [--max-voxels MAX_VOXELS] [--nosym]
             [--init-lta FILE] [--init-header | --init-centroid |
             --init-center] [--isotropic] [--device DEVICE]
             [--powell-brute-limit POWELL_BRUTE_LIMIT]
             [--powell-brute-iters POWELL_BRUTE_ITERS]
             [--powell-brute-samples POWELL_BRUTE_SAMPLES]
             [--powell-maxiter POWELL_MAXITER] [--powell-sep POWELL_SEP]
             [--verbose] [--debug]

Named Arguments

--mov

Moving (source) image (NIfTI or MGZ).

--ref

Reference (target/fixed) image (NIfTI or MGZ).

--out

Output LTA file for the recovered transformation.

--mapmov

Save the mapped moving image resliced into reference geometry.

--mapmovhdr

Save a header-only mapped moving image with no interpolation.

--keep-dtype

Write cubic –mapmov output in the moving-image dtype instead of float32. Equivalent to FreeSurfer mri_vol2vol –keep-precision.

Default: False

--mov-mask

Optional moving/source mask. Voxels outside the mask are ignored during registration.

--ref-mask

Optional reference/target mask. Voxels outside the mask are ignored during registration.

--dof

Possible choices: 3, 6, 9, 12

Degrees of freedom: 3=translation, 6=rigid, 9=rigid+scale, 12=affine.

Default: 6

--method

Possible choices: powell, gd

Registration backend: Powell or legacy gradient descent (‘gd’).

Default: 'powell'

--n_iters

Uniform number of optimisation iterations per pyramid level.

--level-iters

Comma-separated per-level iteration schedule in coarse->fine order. Use 0 to skip a level.

--lr

Optimizer step size used on every executed pyramid level.

--min-voxels

Minimum pyramid level size.

Default: 16

--max-voxels

Largest allowed dimension of the finest pyramid level. Omit to run up to original resolution.

--nosym

Disable symmetric halfway-space registration and run directed registration.

--init-lta

Initialize from an existing LTA transform. When given, other init flags are ignored.

--init-header

Use header alignment only.

--init-centroid

Initialize by aligning intensity centroids in RAS.

--init-center

Initialize by aligning geometric image centers in RAS (FreeSurfer cras0-style).

--isotropic

Enable shared isotropic preprocessing before building the pyramid.

Default: False

--device

Torch device string, e.g. ‘cpu’, ‘cuda’, ‘mps’, or ‘gpu’. The Powell backend currently falls back to CPU.

Default: 'cpu'

--powell-brute-limit

Initial search half-width for the Powell-style brute-force stage.

Default: 30.0

--powell-brute-iters

Number of coarse-to-fine passes in the Powell-style brute-force stage.

Default: 1

--powell-brute-samples

Number of samples per dimension in the Powell-style brute-force stage.

Default: 30

--powell-maxiter

Maximum Powell iterations in the Powell-style refinement stage.

Default: 4

--powell-sep

Sampling spacing for the Powell-style MRI_coreg evaluator.

Default: 4

--verbose

Enable INFO-level logging.

Default: False

--debug

Enable DEBUG-level logging.

Default: False

Python module

Command-line interface for image-based cross-modal registration (coreg).

neuroreg.cli.coreg.main(args=None)[source]

Entry point for the coreg command-line interface.

This wrapper exposes public image-based registration for cross-modal alignment when only images are available. It defaults to the FreeSurfer- style brute-force plus Powell path and keeps the legacy gradient-descent backend available via --method gd. The written output LTA is a voxel-to-voxel transform in public moving -> reference direction.

Parameters:
argslist of str or None, optional

Command-line arguments. When None, arguments are read from sys.argv.

Returns:
None

This function is invoked for its side effects: registration, optional mapped-image export, and writing the output transform.

Raises:
SystemExit

If argument parsing fails or image loading raises an exception.

Return type:

None

bbreg

Boundary-based registration of a moving image to a T1 anatomy using cortical surface meshes. Analogous to FreeSurfer’s bbregister.

Surface input — choose ONE of the following modes:
  1. --subject_dir

    : FreeSurfer / FastSurfer subject directory (surfaces and T1 reference loaded automatically)

  2. –lh_surf / –rh_surf : explicit surface file(s) + –ref

  3. --seg

    : parcellation / aseg file; surfaces are extracted automatically via marching cubes (no pre-built surface files needed)

usage: bbreg [-h] --mov FILE --out LTA [--subject_dir DIR] [--ref FILE]
             [--lh_surf FILE] [--rh_surf FILE] [--lh_thickness FILE]
             [--rh_thickness FILE] [--seg FILE] [--seg_smooth_sigma SIGMA]
             [--seg_mc_level LEVEL] [--seg_smooth_iters N] [--dof {6,9,12}]
             [--contrast {t1,t2}] [--cost {contrast,gradient,both}]
             [--wm_proj_abs MM] [--gm_proj_frac FRAC] [--slope SLOPE]
             [--gradient_weight GRADIENT_WEIGHT] [--n_iters N] [--lr LR]
             [--subsample N] [--init-lta FILE] [--init-header]
             [--no-coreg-ref-mask] [--device DEVICE] [--mapmov FILE]
             [--mapmovhdr FILE] [--keep-dtype] [--verbose] [--debug]

Named Arguments

--mov

Moving image to register (e.g. fMRI or T2, NIfTI or MGZ).

--out

Output LTA file for the recovered transformation.

--dof

Possible choices: 6, 9, 12

Degrees of freedom: 6=rigid, 9=rigid+scale, 12=affine.

Default: 6

--contrast

Possible choices: t1, t2

Tissue contrast: ‘t1’ (WM>GM) or ‘t2’ (GM>WM). Auto-detected from the image when not specified.

--cost

Possible choices: contrast, gradient, both

BBR cost term.

Default: 'contrast'

--wm_proj_abs

Absolute WM projection depth (mm).

Default: 1.4

--gm_proj_frac

GM projection fraction of cortical thickness.

Default: 0.5

--slope

Slope of the BBR sigmoid cost function.

Default: 0.5

--gradient_weight

Weight for gradient cost term when –cost=both.

Default: 0.0

--n_iters

Number of RMSprop optimisation iterations.

Default: 200

--lr

Optimiser learning rate.

Default: 0.005

--subsample

Use every N-th surface vertex (1 = all).

Default: 2

--init-lta

Initialise registration from an existing LTA file (e.g. from a prior robreg run, or a previous bbreg pass).

--init-header

Assume that the geometry information in the cross-modal and anatomical are sufficient to get a close voxel-to-voxel registration. This usually is only the case if they were acquired in the same session.

Default: False

--no-coreg-ref-mask

Do not use aparc+aseg/aseg (or the provided segmentation) as a reference mask for the coarse NMI prealignment stage.

Default: False

--device

Torch device string, e.g. ‘cpu’, ‘cuda’, ‘mps’, or ‘gpu’.

Default: 'cpu'

--mapmov

Save the mapped moving image resliced into target geometry.

--mapmovhdr

Save a header-only mapped moving image with no interpolation.

--keep-dtype

Write cubic –mapmov output in the moving-image dtype instead of float32. Equivalent to FreeSurfer mri_vol2vol –keep-precision.

Default: False

--verbose

Enable INFO-level logging.

Default: False

--debug

Enable DEBUG-level logging.

Default: False

Mode A – FreeSurfer subject directory

--subject_dir

Subject directory containing surf/lh.white, surf/rh.white, and mri/orig.mgz.

Mode B – explicit surface files

--ref

Reference anatomical intensity image. Required for Mode B (explicit surfaces). Optional for Mode C (–seg) to drive coarse NMI prealignment.

--lh_surf

Left-hemisphere white surface (e.g. surf/lh.white).

--rh_surf

Right-hemisphere white surface (e.g. surf/rh.white).

--lh_thickness

Left-hemisphere cortical thickness file.

--rh_thickness

Right-hemisphere cortical thickness file.

Mode C – segmentation (aparc+aseg / aseg)

White surfaces are extracted on-the-fly via marching cubes. No pre-built surface files are needed and the segmentation header provides the target reference geometry.

--seg

Parcellation file (aparc+aseg.mgz, aseg.mgz, or NIfTI).

--seg_smooth_sigma

Gaussian pre-blur sigma (voxels) before marching cubes. Default: 0.5.

Default: 0.5

--seg_mc_level

Marching-cubes iso-level. Default: 0.45.

Default: 0.45

--seg_smooth_iters

Taubin smoothing iterations after marching cubes. Default: 50.

Default: 50

Python module

Command-line interface for boundary-based registration (bbreg).

neuroreg.cli.bbreg.main(args=None)[source]

Entry point for the bbreg command-line interface.

The CLI normalizes the different input modes, optionally runs a coarse NMI prealignment to obtain a moving -> target initialization, and then calls neuroreg.bbreg.register.register_surface() with a consistent public transform direction. When requested, it also exports resliced or header-only mapped versions of the moving image using the same shared mapping helpers as the other registration CLIs.

Parameters:
argslist of str or None, optional

Command-line arguments. When None, arguments are read from sys.argv.

Returns:
None

This function is invoked for its side effects: registration, optional mapped-image export, and writing the output transform.

Raises:
SystemExit

If argument parsing fails, registration raises an exception, or the CLI exits after reporting an error.

Return type:

None

vol2vol

Apply a linear transform to an image, reslice into a target geometry, or update the header only. This is the project-native analogue of FreeSurfer’s mri_vol2vol for linear transforms.

With no –transform and no –ref the image is read and written as-is (no mapping or reslicing); the output format is taken from the –out file extension, so this converts between any formats nibabel supports (e.g. .mgz, .nii, .nii.gz, .img/.hdr). The dtype/scaling flags also apply on the native grid without reslicing. To mask a volume, use ‘mri mask’.

usage: vol2vol [-h] --in FILE [--transform FILE]
               [--transform-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
               [--ref FILE] --out FILE [--interp {linear,cubic,nearest} |
               --trilin | --nearest | --cubic] [--pad MODE|VALUE]
               [--header-only] [--inverse] [--out-dtype DTYPE | --keep-dtype]
               [--scale-mode {clamp,rescale,robust}] [--target-max TARGET_MAX]
               [--robust-low FRAC] [--robust-high FRAC] [--verbose] [--debug]

Named Arguments

--in, --i, --mov

Input (moving) image.

--transform, --lta

Optional linear transform to apply (any format: .lta, .xfm, FSL .mat, …).

--transform-format

Possible choices: lta, xfm, fsl, regdat, itk, antsmat, afni, niftyreg

Override transform format inference for ambiguous files such as .txt or .mat.

--ref, --targ

Optional target/reference image geometry. Overrides geometry stored in the transform.

--out, --o

Output image filename. The extension selects the output format (any nibabel format).

--interp

Possible choices: linear, cubic, nearest

Interpolation mode for resampled output.

Default: 'linear'

--trilin

Trilinear interpolation. Alias for –interp linear.

--nearest

Nearest-neighbour interpolation. Alias for –interp nearest.

--cubic

Cubic interpolation. Alias for –interp cubic.

--pad

Out-of-bounds padding: zero, border, reflection, brightest, or a numeric constant.

Default: zero

--header-only, --no-resample

Apply the transform to the header only and skip interpolation.

Default: False

--inverse, --inv

Apply the inverse of the supplied transform.

Default: False

--out-dtype

Explicit final output dtype, or ‘input’ to preserve the moving-image dtype.

--keep-dtype, --keep-precision

Write output in the moving-image dtype. Equivalent to –out-dtype input.

Default: False

--scale-mode

Possible choices: clamp, rescale, robust

Optional final intensity policy before dtype conversion.

--target-max

Upper target value for zero-anchored rescale or robust-rescale output.

--robust-low

Lower robust quantile used to trim the source intensity distribution.

Default: 0.0

--robust-high

Upper robust quantile used to estimate the source intensity ceiling.

Default: 0.999

--verbose

Enable INFO-level logging.

Default: False

--debug

Enable DEBUG-level logging.

Default: False

Python module

Command-line image mapping and reslicing utility.

neuroreg.cli.vol2vol.main(args=None)[source]

Entry point for the vol2vol command-line interface.

Parameters:
argslist of str or None, optional

Command-line arguments. When None, arguments are read from sys.argv.

Returns:
None

This function is invoked for its side effects: loading images and transforms, mapping the image, and writing the output volume.

Raises:
SystemExit

If argument parsing fails, required geometry is unavailable, or image / transform loading or writing raises an exception.

Return type:

None

segreg

Segmentation-based registration via label centroids. Fits translation-only, rigid, similarity, no-shear anisotropic-scale, or affine transforms from a moving segmentation to a target segmentation, a centroid target file, or a left-right flipped self target.

usage: segreg [-h] --seg FILE (--target-seg FILE | --centroids TARGET |
              --flipped) --lta FILE [--dof {3,6,7,9,12}] [--labels LABELS]
              [--label-set {all_shared,target_centroids,cortex_lr_pairs}]
              [--min-common-labels MIN_COMMON_LABELS] [--midslice MIDSLICE]
              [--verbose] [--debug]

Named Arguments

--seg

Moving segmentation image (NIfTI or MGZ).

--target-seg

Target segmentation image used to derive centroid correspondences and LTA target geometry.

--centroids

Target centroid JSON file or bundled target name (fsaverage, mni_icbm152_t1_tal_nlin_asym_09c).

--flipped

Register to a left-right flipped self target.

Default: False

--lta

Output LTA transform.

--dof

Possible choices: 3, 6, 7, 9, 12

3=translation only, 6=rigid, 7=rigid+global scale, 9=rigid+anisotropic scale (no shear), 12=affine.

Default: 6

--labels

Comma-separated label subset override.

--label-set

Possible choices: all_shared, target_centroids, cortex_lr_pairs

Named label preset. Defaults depend on the chosen target mode.

--min-common-labels

Minimum number of matched labels required.

--midslice

Mid-sagittal x position for –flipped mode.

--verbose

Enable INFO-level logging.

Default: False

--debug

Enable DEBUG-level logging.

Default: False

Python module

Command-line interface for segmentation-based centroid registration.

The CLI fits an LTA from a moving segmentation to either a target segmentation, a centroid target JSON file (or bundled centroid target name), or a left-right flipped self target.

neuroreg.cli.segreg.main(args=None)[source]

Run the segreg command-line entry point.

Return type:

None

mri

Image volume utilities (mask, info, diff, binarize).

usage: mri [-h] COMMAND ...

Positional Arguments

COMMAND

Possible choices: mask, info, diff, binarize

Sub-commands

mask

Apply a binary mask to an image, keeping voxels where the mask value is strictly greater than –threshold and setting the rest to –oval. The mask is resampled with nearest-neighbor interpolation into the input geometry when its grid differs, so a mask given in a different geometry is handled like FreeSurfer’s mri_mask. The input dtype is preserved; the output format follows the out extension.

This is a single-space operation: it does not map between geometries. To mask before/after a transform, compose with vol2vol (mri mask … then vol2vol … = mask-then-map; vol2vol … then mri mask … = map-then-mask).

mri mask [-h] [-T T] [--oval V] in mask out
Positional Arguments
in

Input image to mask.

mask

Binary mask image.

out

Output image filename (format from extension).

Named Arguments
-T, --threshold

Voxels with mask value strictly greater than this are kept (default: 0).

Default: 0.0

--oval

Value assigned to voxels outside the mask (default: 0).

Default: 0.0

info

Print header and geometry information for an image, analogous to FreeSurfer’s mri_info. With no selector flags a full human-readable dump is printed. Selector flags print only the requested value(s), one per line, for scripting.

mri info [-h] [--dim] [--res] [--voxvol] [--type] [--nframes] [--orientation]
         [--cras] [--vox2ras] [--ras2vox] [--vox2ras-tkr] [--stats]
         FILE
Positional Arguments
FILE

Input image.

Named Arguments
--dim

Print dimensions: ‘w h d’.

Default: False

--res

Print voxel sizes: ‘x y z’.

Default: False

--voxvol

Print the voxel volume.

Default: False

--type

Print the data dtype.

Default: False

--nframes

Print the number of frames.

Default: False

--orientation, --ori

Print the orientation string.

Default: False

--cras

Print the volume center RAS: ‘c_r c_a c_s’.

Default: False

--vox2ras

Print the voxel-to-RAS (scanner) matrix.

Default: False

--ras2vox

Print the RAS-to-voxel matrix.

Default: False

--vox2ras-tkr

Print the voxel-to-tkRAS matrix.

Default: False

--stats

Print voxel value stats: ‘min max mean’.

Default: False

diff

Compare two volumes, analogous to FreeSurfer’s mri_diff. Checks are run in order and (unless –no-exit-on-diff) the command exits at the first difference with a FreeSurfer-compatible status code: 0 volumes are the same 1 error (e.g. a file could not be read) 101 dimensions differ (always exits) 102 voxel resolution differs (> –res-thresh) 104 geometry / vox2ras differs (> –geo-thresh) 105 data type (precision) differs 106 voxel values differ (max abs diff > –thresh and count > –count-thresh)

Acquisition-parameter (TR/TE/TI/flip) checks are not performed.

mri diff [-h] [--thresh T] [--res-thresh T] [--geo-thresh T]
         [--count-thresh N] [--count] [--no-exit-on-diff] [--skip-res]
         [--skip-geo] [--skip-prec] [--skip-pix] [--notallow-acq]
         vol1 vol2
Positional Arguments
vol1

First image.

vol2

Second image.

Named Arguments
--thresh

Voxel value difference threshold (default: 0).

Default: 0.0

--res-thresh

Voxel-size difference threshold (default: 0).

Default: 0.0

--geo-thresh

vox2ras element difference threshold (default: 0).

Default: 0.0

--count-thresh

Voxel values count as differing only when more than N voxels differ (default: 0).

Default: 0

--count

Print the number of differing voxels.

Default: False

--no-exit-on-diff

Report all differences instead of exiting at the first one.

Default: True

--skip-res, --notallow-res

Skip the voxel-resolution check.

Default: False

--skip-geo, --notallow-geo

Skip the geometry / vox2ras check.

Default: False

--skip-prec, --notallow-prec

Skip the data-type / precision check.

Default: False

--skip-pix, --notallow-pix

Skip the pixel-value check.

Default: False

--notallow-acq

Accepted for FreeSurfer compatibility; acquisition-parameter checks are not performed.

Default: False

binarize

Binarize an image, analogous to FreeSurfer’s mri_binarize. A voxel is selected when it matches one of –match (exact), or lies in the inclusive range [–min, –max] (either bound may be omitted). Selected voxels are set to –binval, the rest to –binvalnot; –inv swaps that assignment. At least one of –min, –max, or –match is required. Output is int32 by default (–uchar selects uint8).

mri binarize [-h] --i FILE --o FILE [--min MIN] [--max MAX]
             [--match V [V ...]] [--binval V] [--binvalnot V] [--inv] [--abs]
             [--frame N] [--uchar]
Named Arguments
--i, --in

Input image.

--o, --out

Output image.

--min

Inclusive lower intensity bound.

--max

Inclusive upper intensity bound.

--match

Match these values exactly (e.g. label ids).

--binval

Value for selected voxels (default: 1).

Default: 1

--binvalnot

Value for unselected voxels (default: 0).

Default: 0

--inv

Swap the selected/unselected output values.

Default: False

--abs

Take abs value before thresholding.

Default: False

--frame

For 4D input, binarize this frame only.

--uchar

Write uint8 output instead of int32.

Default: False

mri mask

Apply a binary mask to an image, keeping voxels where the mask value is strictly greater than –threshold and setting the rest to –oval. The mask is resampled with nearest-neighbor interpolation into the input geometry when its grid differs, so a mask given in a different geometry is handled like FreeSurfer’s mri_mask. The input dtype is preserved; the output format follows the out extension.

This is a single-space operation: it does not map between geometries. To mask before/after a transform, compose with vol2vol (mri mask … then vol2vol … = mask-then-map; vol2vol … then mri mask … = map-then-mask).

usage: mri mask mask [-h] [-T T] [--oval V] in mask out

Positional Arguments

in

Input image to mask.

mask

Binary mask image.

out

Output image filename (format from extension).

Named Arguments

-T, --threshold

Voxels with mask value strictly greater than this are kept (default: 0).

Default: 0.0

--oval

Value assigned to voxels outside the mask (default: 0).

Default: 0.0

mri info

Print header and geometry information for an image, analogous to FreeSurfer’s mri_info. With no selector flags a full human-readable dump is printed. Selector flags print only the requested value(s), one per line, for scripting.

usage: mri info info [-h] [--dim] [--res] [--voxvol] [--type] [--nframes]
                     [--orientation] [--cras] [--vox2ras] [--ras2vox]
                     [--vox2ras-tkr] [--stats]
                     FILE

Positional Arguments

FILE

Input image.

Named Arguments

--dim

Print dimensions: ‘w h d’.

Default: False

--res

Print voxel sizes: ‘x y z’.

Default: False

--voxvol

Print the voxel volume.

Default: False

--type

Print the data dtype.

Default: False

--nframes

Print the number of frames.

Default: False

--orientation, --ori

Print the orientation string.

Default: False

--cras

Print the volume center RAS: ‘c_r c_a c_s’.

Default: False

--vox2ras

Print the voxel-to-RAS (scanner) matrix.

Default: False

--ras2vox

Print the RAS-to-voxel matrix.

Default: False

--vox2ras-tkr

Print the voxel-to-tkRAS matrix.

Default: False

--stats

Print voxel value stats: ‘min max mean’.

Default: False

mri diff

Compare two volumes, analogous to FreeSurfer’s mri_diff. Checks are run in order and (unless –no-exit-on-diff) the command exits at the first difference with a FreeSurfer-compatible status code: 0 volumes are the same 1 error (e.g. a file could not be read) 101 dimensions differ (always exits) 102 voxel resolution differs (> –res-thresh) 104 geometry / vox2ras differs (> –geo-thresh) 105 data type (precision) differs 106 voxel values differ (max abs diff > –thresh and count > –count-thresh)

Acquisition-parameter (TR/TE/TI/flip) checks are not performed.

usage: mri diff diff [-h] [--thresh T] [--res-thresh T] [--geo-thresh T]
                     [--count-thresh N] [--count] [--no-exit-on-diff]
                     [--skip-res] [--skip-geo] [--skip-prec] [--skip-pix]
                     [--notallow-acq]
                     vol1 vol2

Positional Arguments

vol1

First image.

vol2

Second image.

Named Arguments

--thresh

Voxel value difference threshold (default: 0).

Default: 0.0

--res-thresh

Voxel-size difference threshold (default: 0).

Default: 0.0

--geo-thresh

vox2ras element difference threshold (default: 0).

Default: 0.0

--count-thresh

Voxel values count as differing only when more than N voxels differ (default: 0).

Default: 0

--count

Print the number of differing voxels.

Default: False

--no-exit-on-diff

Report all differences instead of exiting at the first one.

Default: True

--skip-res, --notallow-res

Skip the voxel-resolution check.

Default: False

--skip-geo, --notallow-geo

Skip the geometry / vox2ras check.

Default: False

--skip-prec, --notallow-prec

Skip the data-type / precision check.

Default: False

--skip-pix, --notallow-pix

Skip the pixel-value check.

Default: False

--notallow-acq

Accepted for FreeSurfer compatibility; acquisition-parameter checks are not performed.

Default: False

mri binarize

Binarize an image, analogous to FreeSurfer’s mri_binarize. A voxel is selected when it matches one of –match (exact), or lies in the inclusive range [–min, –max] (either bound may be omitted). Selected voxels are set to –binval, the rest to –binvalnot; –inv swaps that assignment. At least one of –min, –max, or –match is required. Output is int32 by default (–uchar selects uint8).

usage: mri binarize binarize [-h] --i FILE --o FILE [--min MIN] [--max MAX]
                             [--match V [V ...]] [--binval V] [--binvalnot V]
                             [--inv] [--abs] [--frame N] [--uchar]

Named Arguments

--i, --in

Input image.

--o, --out

Output image.

--min

Inclusive lower intensity bound.

--max

Inclusive upper intensity bound.

--match

Match these values exactly (e.g. label ids).

--binval

Value for selected voxels (default: 1).

Default: 1

--binvalnot

Value for unselected voxels (default: 0).

Default: 0

--inv

Swap the selected/unselected output values.

Default: False

--abs

Take abs value before thresholding.

Default: False

--frame

For 4D input, binarize this frame only.

--uchar

Write uint8 output instead of int32.

Default: False

Python module

Unified image-utility CLI.

Small mri_*-style volume utilities grouped under a single command, in the same spirit as the lta transform CLI. Available subcommands are mask (analogous to FreeSurfer’s mri_mask), info (mri_info), diff (mri_diff), and binarize (mri_binarize). Run mri --help or mri <subcommand> --help for the full command syntax.

neuroreg.cli.mri.main(args=None)[source]

Entry point for the mri command.

Parameters:
argslist of str or None, optional

Command-line arguments. When None, arguments are read from sys.argv.

Returns:
None

This function is invoked for its side effects only.

Return type:

None

lta

LTA transform manipulation utilities.

usage: lta [-h] COMMAND ...

Positional Arguments

COMMAND

Possible choices: diff, invert, concat, convert

Sub-commands

diff

Compute distance metrics between two LTA transforms, or between one transform and identity.

All metrics operate on the RAS-to-RAS representation of the stored transforms (vox-to-vox LTAs are converted automatically).

Distance types:
1 Rigid transform distance sqrt(||log R||² + ||T||²)

D = inv(M1) @ M2 (or M1 vs identity) R = upper-left 3×3 rotation block of D T = upper-right 3×1 translation column of D Units: mixed (mm and rad added in quadrature)

2 Affine RMS distance (Jenkinson 1999) [default]

sqrt(r²/5 · Tr(AᵀA) + ‖T‖²), D = M1 − M2 (or M1 − I) A = upper-left 3×3 of D; r = –radius (default 100 mm) T = upper-right 3×1 translation column of D Units: mm (RMS displacement over a sphere of radius r)

3 8-corner mean displacement (mm, image-specific)

One transform: mean‖M1·c − c‖ for each src corner c in RAS. Two transforms: mean‖M1·c − M2·c‖ (same src corners).

4 Max displacement on a sphere of radius r (mm, image-independent)

Md = inv(M1) @ M2 (or M1 vs identity) displacement(p) = ‖Md·p − p‖ over ~1600 sphere samples

5 Determinant det(M1) (or det(M1 @ M2) = det(M1)*det(M2) when M2 given)

Uses matrix concatenation (not the difference); det is order-independent.

7 Polar decomposition of M1 (or M1 @ M2, i.e. concatenation):

prints Rot, RotVec, RotAngle, Shear, Scales, Trans, abs(Trans), det

lta diff [-h] [--dist {1,2,3,4,5,7}] [--radius MM] [--normdiv FLOAT]
         [--invert1] [--invert2]
         LTA1 [LTA2]
Positional Arguments
LTA1

First (or only) LTA transform file.

LTA2

Second LTA file. Omit to compare LTA1 against identity.

Named Arguments
--dist

Possible choices: 1, 2, 3, 4, 5, 7

Distance type (default: 2).

Default: 2

--radius

Sphere / RMS radius in mm (dist 2 and 4, default: 100).

Default: 100.0

--normdiv

Divide the final distance by this value (must be > 0, default: 1).

Default: 1.0

--invert1

Invert the first transform before comparison.

Default: False

--invert2

Invert the second transform before comparison.

Default: False

invert

Invert a FreeSurfer LTA transform.

The output is always stored as LINEAR_RAS_TO_RAS (type 1) with src and dst geometry blocks swapped.

lta invert [-h] INPUT OUTPUT
Positional Arguments
INPUT

Input LTA file.

OUTPUT

Output (inverted) LTA file.

concat

Concatenate two LTA transforms.

LTA1 maps A → B and LTA2 maps B → C. The output maps A → C with matrix M_LTA2 @ M_LTA1. src geometry is taken from LTA1; dst geometry from LTA2.

Equivalent to FreeSurfer’s mri_concatenate_lta.

lta concat [-h] LTA1 LTA2 OUTPUT
Positional Arguments
LTA1

First transform (A → B).

LTA2

Second transform (B → C).

OUTPUT

Output LTA file (A → C).

convert

Convert between FreeSurfer-adjacent linear transform formats.

Supported formats are usually inferred from file suffixes:

.lta FreeSurfer Linear Transform Array .xfm MNI/MINC linear transform .mat/.fslmat FSL FLIRT affine matrix .dat/.reg tkregister volumetric register.dat format .tfm ITK/ANTs 3D affine text transform *GenericAffine.mat experimental ANTs / ITK Matlab affine .aff12.1D experimental AFNI affine text matrix .niftyreg.txt NiftyReg 3D affine text matrix

Use –in-format/–out-format for ambiguous text outputs such as .txt, .1D, or .mat. FSL and register.dat conversion require both –src-img and –dst-img because the stored matrices depend on image geometry rather than being plain scanner-RAS affines. ITK/ANTs text affines, experimental ANTs .mat, experimental AFNI affine text, and NiftyReg affine text matrices are scanner-space transforms and can be read without images, though –src-img/–dst-img still enrich the resulting LTA geometry blocks. ANTs .mat support is currently based on SciPy + ITK Matlab IO semantics and should be considered experimental until validated on real files. AFNI support currently targets affine text matrices in DICOM/LPS coordinates and should likewise be considered experimental. NiftyReg affine text matrices store the inverse target-to-source RAS matrix.

lta convert [-h] [--in-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
            [--out-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
            [--src-img SRC_IMG] [--dst-img DST_IMG]
            [--out-type {ras2ras,vox2vox}] [--subject SUBJECT]
            [--fscale FSCALE] [--float2int {tkregister,round,floor}]
            INPUT OUTPUT
Positional Arguments
INPUT

Input transform file.

OUTPUT

Output transform file.

Named Arguments
--in-format

Possible choices: lta, xfm, fsl, regdat, itk, antsmat, afni, niftyreg

Override input format inference for ambiguous files.

--out-format

Possible choices: lta, xfm, fsl, regdat, itk, antsmat, afni, niftyreg

Override output format inference for ambiguous files.

--src-img

Moving/source image geometry for conversion when needed.

--dst-img

Reference/target image geometry for conversion when needed.

--out-type

Possible choices: ras2ras, vox2vox

Output LTA storage type when OUTPUT ends in .lta (default: preserve the input LTA storage type).

--subject

Subject metadata to store when writing .lta or register.dat.

--fscale

Intensity/fscale metadata to store when writing .lta or register.dat.

--float2int

Possible choices: tkregister, round, floor

Float-to-int footer when writing register.dat (default: round).

Default: 'round'

lta diff

Compute distance metrics between two LTA transforms, or between one transform and identity.

All metrics operate on the RAS-to-RAS representation of the stored transforms (vox-to-vox LTAs are converted automatically).

Distance types:
1 Rigid transform distance sqrt(||log R||² + ||T||²)

D = inv(M1) @ M2 (or M1 vs identity) R = upper-left 3×3 rotation block of D T = upper-right 3×1 translation column of D Units: mixed (mm and rad added in quadrature)

2 Affine RMS distance (Jenkinson 1999) [default]

sqrt(r²/5 · Tr(AᵀA) + ‖T‖²), D = M1 − M2 (or M1 − I) A = upper-left 3×3 of D; r = –radius (default 100 mm) T = upper-right 3×1 translation column of D Units: mm (RMS displacement over a sphere of radius r)

3 8-corner mean displacement (mm, image-specific)

One transform: mean‖M1·c − c‖ for each src corner c in RAS. Two transforms: mean‖M1·c − M2·c‖ (same src corners).

4 Max displacement on a sphere of radius r (mm, image-independent)

Md = inv(M1) @ M2 (or M1 vs identity) displacement(p) = ‖Md·p − p‖ over ~1600 sphere samples

5 Determinant det(M1) (or det(M1 @ M2) = det(M1)*det(M2) when M2 given)

Uses matrix concatenation (not the difference); det is order-independent.

7 Polar decomposition of M1 (or M1 @ M2, i.e. concatenation):

prints Rot, RotVec, RotAngle, Shear, Scales, Trans, abs(Trans), det

usage: lta diff diff [-h] [--dist {1,2,3,4,5,7}] [--radius MM]
                     [--normdiv FLOAT] [--invert1] [--invert2]
                     LTA1 [LTA2]

Positional Arguments

LTA1

First (or only) LTA transform file.

LTA2

Second LTA file. Omit to compare LTA1 against identity.

Named Arguments

--dist

Possible choices: 1, 2, 3, 4, 5, 7

Distance type (default: 2).

Default: 2

--radius

Sphere / RMS radius in mm (dist 2 and 4, default: 100).

Default: 100.0

--normdiv

Divide the final distance by this value (must be > 0, default: 1).

Default: 1.0

--invert1

Invert the first transform before comparison.

Default: False

--invert2

Invert the second transform before comparison.

Default: False

lta invert

Invert a FreeSurfer LTA transform.

The output is always stored as LINEAR_RAS_TO_RAS (type 1) with src and dst geometry blocks swapped.

usage: lta invert invert [-h] INPUT OUTPUT

Positional Arguments

INPUT

Input LTA file.

OUTPUT

Output (inverted) LTA file.

lta concat

Concatenate two LTA transforms.

LTA1 maps A → B and LTA2 maps B → C. The output maps A → C with matrix M_LTA2 @ M_LTA1. src geometry is taken from LTA1; dst geometry from LTA2.

Equivalent to FreeSurfer’s mri_concatenate_lta.

usage: lta concat concat [-h] LTA1 LTA2 OUTPUT

Positional Arguments

LTA1

First transform (A → B).

LTA2

Second transform (B → C).

OUTPUT

Output LTA file (A → C).

lta convert

Convert between FreeSurfer-adjacent linear transform formats.

Supported formats are usually inferred from file suffixes:

.lta FreeSurfer Linear Transform Array .xfm MNI/MINC linear transform .mat/.fslmat FSL FLIRT affine matrix .dat/.reg tkregister volumetric register.dat format .tfm ITK/ANTs 3D affine text transform *GenericAffine.mat experimental ANTs / ITK Matlab affine .aff12.1D experimental AFNI affine text matrix .niftyreg.txt NiftyReg 3D affine text matrix

Use –in-format/–out-format for ambiguous text outputs such as .txt, .1D, or .mat. FSL and register.dat conversion require both –src-img and –dst-img because the stored matrices depend on image geometry rather than being plain scanner-RAS affines. ITK/ANTs text affines, experimental ANTs .mat, experimental AFNI affine text, and NiftyReg affine text matrices are scanner-space transforms and can be read without images, though –src-img/–dst-img still enrich the resulting LTA geometry blocks. ANTs .mat support is currently based on SciPy + ITK Matlab IO semantics and should be considered experimental until validated on real files. AFNI support currently targets affine text matrices in DICOM/LPS coordinates and should likewise be considered experimental. NiftyReg affine text matrices store the inverse target-to-source RAS matrix.

usage: lta convert convert [-h]
                           [--in-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
                           [--out-format {lta,xfm,fsl,regdat,itk,antsmat,afni,niftyreg}]
                           [--src-img SRC_IMG] [--dst-img DST_IMG]
                           [--out-type {ras2ras,vox2vox}] [--subject SUBJECT]
                           [--fscale FSCALE]
                           [--float2int {tkregister,round,floor}]
                           INPUT OUTPUT

Positional Arguments

INPUT

Input transform file.

OUTPUT

Output transform file.

Named Arguments

--in-format

Possible choices: lta, xfm, fsl, regdat, itk, antsmat, afni, niftyreg

Override input format inference for ambiguous files.

--out-format

Possible choices: lta, xfm, fsl, regdat, itk, antsmat, afni, niftyreg

Override output format inference for ambiguous files.

--src-img

Moving/source image geometry for conversion when needed.

--dst-img

Reference/target image geometry for conversion when needed.

--out-type

Possible choices: ras2ras, vox2vox

Output LTA storage type when OUTPUT ends in .lta (default: preserve the input LTA storage type).

--subject

Subject metadata to store when writing .lta or register.dat.

--fscale

Intensity/fscale metadata to store when writing .lta or register.dat.

--float2int

Possible choices: tkregister, round, floor

Float-to-int footer when writing register.dat (default: round).

Default: 'round'

Python module

Unified LTA transform manipulation CLI.

Available subcommands are diff to compare transforms, invert to invert an LTA, concat to chain two LTAs, and convert to translate between LTA, XFM, FSL, ITK/ANTs text affine, experimental ANTs Matlab affine, experimental AFNI affine text, NiftyReg affine text matrices, and tkregister register.dat transforms. Run lta --help or lta <subcommand> --help for the full command syntax.

neuroreg.cli.lta.main(args=None)[source]

Entry point for the lta command.

Return type:

None

neuroreg-sys_info

Display dependency and runtime information for neuroreg.

usage: neuroreg-sys_info [-h] [--developer]

Named Arguments

--developer

Display information for optional dependencies.

Default: False

Python module

neuroreg.cli.sys_info.main(args=None)[source]

Run the neuroreg-sys_info command.

Return type:

None

neuroreg.cli.sys_info.run()[source]

Run the sys_info CLI entrypoint.

Return type:

None