NeuroReg

NeuroReg is a package for the robust registration of 3D neuroimaging data (e.g. MRI). It supports both image-to-image (within and cross modal) as well as image to landmark (WM-surface) or segmentation-based registration, with a focus on high accuracy and speed.

The main user-facing tools are:

• robreg – Highly accurate and robust same modality image-to-image registration (IRLS based, analogous to FreeSurfer's mri_robust_register)
• coreg – Image-to-image cross-modal registration (Powell-based by default, analogous to FreeSurfer/SPM mri_coreg)
• bbreg – boundary-based registration using cortical WM surfaces or segmentations (extending FreeSurfer's bbregister)
• segreg – segmentation-based registration via label centroids (rigid/affine, including atlas-centroid and upright/self-flip modes)
• lta – transform comparison / inversion / concatenation utilities

This project is a work-in-progress in an early development stage. It is developed by the creator of FreeSurfer's mri_robust_register as an efficient pure Python replacement (with GPU support) and cross-modal extensions to support all your medical imaging registration needs. If you find it useful for a publication, please cite the relevant papers (see References).

pip install neuroreg

Registers a moving image to a reference image using a multi-resolution IRLS-based robust registration path with Tukey weighting.

This path is currently intended for same-contrast or very similar-contrast image pairs. On Apple MPS, the current public IRLS path falls back to CPU with a warning due to lack of double precision support on MPS.

robreg --mov <moving.nii.gz> --ref <reference.nii.gz> --out <output.lta> [options]

Run robreg -h for a full argument summary with defaults.

Required arguments

Options

Example

robreg --mov T1_repeat.nii.gz --ref T1_baseline.mgz --out T1_repeat_to_T1_baseline.lta --verbose

This is the package's image-to-image registration path for cross-sequence / cross-modal alignment when no surfaces or segmentation are available. By default it runs a Powell-based MRI_coreg-style pipeline (coarse brute-force search plus Powell refinement), similar in spirit to FreeSurfer/SPM mri_coreg; the older PyTorch gradient-descent path remains available via --method gd.

coreg --mov <moving.nii.gz> --ref <reference.nii.gz> --out <output.lta> [options]

Options

Example

coreg --mov T2.nii.gz --ref T1.mgz --out T2_to_T1.lta --dof 6 --verbose

Registers a moving image to a T1 anatomy using cortical surface meshes (white matter / grey matter boundary). The tissue contrast direction (T1-like: WM > GM, or T2-like: GM > WM) is auto-detected from the image when not specified.

Surface input can be provided in three ways:

Mode A — FreeSurfer / FastSurfer subject directory (recommended)

bbreg --mov <moving.nii.gz> --subject_dir <subject_dir> --out <output.lta> [options]

The subject directory must contain surf/lh.white, surf/rh.white, and mri/orig.mgz (standard FreeSurfer / FastSurfer output layout).

Mode B — explicit surface files

bbreg --mov <moving.nii.gz> --lh_surf <lh.white> --rh_surf <rh.white> \
      --ref <T1.mgz> --out <output.lta> [options]

Mode C — segmentation file (no pre-built surfaces needed)

bbreg --mov <moving.nii.gz> --seg <aparc+aseg.mgz> --out <output.lta> [options]

The WM/GM boundary surface is extracted on-the-fly from a parcellation or aseg file (e.g. aparc+aseg.mgz, aseg.mgz, or NIfTI) via marching cubes. The segmentation header provides the reference geometry for the BBR stage. An optional --ref can still be supplied in this mode to drive the coarse Powell-based image NMI prealignment step.

Required arguments

Options

Examples

# Mode A: register fMRI to T1 using a FastSurfer subject directory
bbreg --mov fMRI.nii.gz --subject_dir /data/subjects/sub-01 --out fMRI_to_T1.lta

# Mode B: register T2 to T1 with explicit surfaces and thickness files
bbreg --mov T2.nii.gz \
      --lh_surf /data/subjects/sub-01/surf/lh.white \
      --rh_surf /data/subjects/sub-01/surf/rh.white \
      --lh_thickness /data/subjects/sub-01/surf/lh.thickness \
      --rh_thickness /data/subjects/sub-01/surf/rh.thickness \
      --ref /data/subjects/sub-01/mri/orig.mgz \
      --out T2_to_T1.lta --contrast t2

# Mode C: register fMRI using a segmentation (no surface files required)
bbreg --mov fMRI.nii.gz --seg /data/subjects/sub-01/mri/aparc+aseg.mgz \
      --out fMRI_to_T1.lta

Run bbreg -h for a full argument summary with defaults.

Registers a moving segmentation by aligning label centroids to another segmentation, to bundled atlas centroids such as fsaverage, or to a left-right flipped self target for upright/midspace workflows.

segreg can also write mapped outputs while the package does not yet have a separate transform-application CLI. If --movimg is provided, --mapmov and --mapmovhdr map that intensity image with the recovered transform; otherwise those outputs map the moving segmentation itself.

segreg --mov <moving_seg.mgz> (--ref <ref_seg.mgz> | --ref-centroids <centroids.json> | --atlas fsaverage | --flipped) [options]

Common outputs

• --lta FILE writes the recovered transform as an LTA.
• --movimg FILE provides a separate intensity image for --mapmov or --mapmovhdr.
• --mapmov FILE writes a resliced mapped output. It maps --movimg when provided; otherwise it reslices the moving segmentation itself.
• --mapmovhdr FILE writes a header-only mapped output. It maps --movimg when provided; otherwise it remaps the moving segmentation itself.

Examples

# Register a subject segmentation to another segmentation
segreg --mov sub-01/aparc+aseg.mgz --ref sub-02/aparc+aseg.mgz \
       --lta sub01_to_sub02.lta

# Register a segmentation, then map a separate intensity image with the same transform
segreg --mov subj/mri/aparc+aseg.mgz --movimg subj/mri/orig.mgz --atlas fsaverage \
       --lta subj_to_fsaverage.lta --mapmov orig_in_fsaverage_space.mgz

# If --movimg is omitted, --mapmov maps the segmentation itself
segreg --mov subj/mri/aparc+aseg.mgz --atlas fsaverage \
       --mapmov aparc_aseg_in_fsaverage_space.mgz

# Export centroid JSON only
segreg --mov subj/mri/aparc+aseg.mgz --atlas fsaverage \
       --write-mov-centroids subj_centroids.json --write-ref-centroids fsaverage_centroids.json

Run segreg -h for a full argument summary with defaults.

Unified command for manipulating FreeSurfer LTA transform files with three subcommands: diff, invert, and concat.

lta diff    LTA1 [LTA2] [options]     # Compare transforms
lta invert  INPUT OUTPUT              # Invert a transform
lta concat  LTA1 LTA2 OUTPUT          # Concatenate two transforms

Computes distance metrics between two LTA transforms, or between a single transform and identity. Replicates the functionality of FreeSurfer's lta_diff.

Usage

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

Distance types

Options

Examples

# Affine RMS distance between two registrations (default metric)
lta diff myreg.lta ref.lta

# Rigid distance
lta diff myreg.lta ref.lta --dist 1

# Polar decomposition of a single transform
lta diff myreg.lta --dist 7

Inverts an LTA transform and writes the result to a new file. The output is always stored as LINEAR_RAS_TO_RAS with src and dst geometry swapped.

Usage

lta invert INPUT OUTPUT

Examples

# Invert a registration
lta invert T1_to_MNI.lta MNI_to_T1.lta

# Invert twice to verify round-trip
lta invert fwd.lta inv.lta
lta invert inv.lta fwd_again.lta

Concatenates two LTA transforms. If LTA1 maps A→B and LTA2 maps B→C, the output maps A→C. Equivalent to FreeSurfer's mri_concatenate_lta.

Usage

lta concat LTA1 LTA2 OUTPUT

Examples

# Concatenate fMRI→T1 and T1→MNI to get fMRI→MNI
lta concat fMRI_to_T1.lta T1_to_MNI.lta fMRI_to_MNI.lta

# Chain multiple registrations
lta concat moving_to_intermediate.lta intermediate_to_fixed.lta moving_to_fixed.lta

Notes

• All metrics are numerically matched to FreeSurfer's lta_diff (except for a known bug in the C++ single-transform corner metric, which is fixed here).
• When only one LTA is supplied to diff, the transform is compared against identity.
• Run lta --help or lta <subcommand> --help for detailed usage.

import nibabel as nib

from neuroreg import bbreg, coreg, robreg

# Public robust image-to-image registration (IRLS-backed).
# Intended for same-/similar-contrast pairs; symmetric mode is the default.
# On Apple MPS, this path currently warns and falls back to CPU.
transform_robreg = robreg("T1_repeat.nii.gz", "T1_baseline.mgz")

# The same public robreg path with pre-loaded nibabel images.
mov_img = nib.load("T1_repeat.nii.gz")
ref_img = nib.load("T1_baseline.mgz")
transform_robreg_loaded = robreg(mov_img, ref_img)

# Image-based cross-modal registration path for cases where no
# white-matter surface or segmentation is available. By default this
# uses the Powell-based MRI_coreg-style path.
transform_coreg = coreg("T2.nii.gz", "T1.mgz")

# Surface-based (BBR) registration — Mode A: subject directory
transform_bbreg = bbreg(
    mov="fMRI.nii.gz",
    subject_dir="/data/subjects/sub-01",
    lta_name="fMRI_to_T1.lta",
    dof=6,
)

# Surface-based (BBR) registration — Mode B: explicit surface files
transform_bbreg = bbreg(
    mov="T2.nii.gz",
    lh_surf="/data/subjects/sub-01/surf/lh.white",
    rh_surf="/data/subjects/sub-01/surf/rh.white",
    lh_thickness="/data/subjects/sub-01/surf/lh.thickness",
    rh_thickness="/data/subjects/sub-01/surf/rh.thickness",
    ref="/data/subjects/sub-01/mri/orig.mgz",
    lta_name="T2_to_T1.lta",
    contrast="t2",
)

# Surface-based (BBR) registration — Mode C: segmentation (no surface files needed)
transform_bbreg = bbreg(
    mov="fMRI.nii.gz",
    seg="/data/subjects/sub-01/mri/aparc+aseg.mgz",
    lta_name="fMRI_to_T1.lta",
)

# For debugging or inspection, request the fitted model explicitly.
transform_bbreg, model_bbreg = bbreg(
    mov="fMRI.nii.gz",
    subject_dir="/data/subjects/sub-01",
    return_model=True,
)

Current DOF support is:

The public robreg path is intentionally rigid-only for now because it tracks the current IRLS implementation.

Also note that the current public robreg path is aimed at same-/similar-contrast registration. For cross-sequence alignment such as T2→T1, the current options are coreg (Powell-based by default, with legacy GD still available via method="gd") or bbreg when a segmentation or surfaces are available.

The API Documentation can be found at https://deep-mi.org/neuroreg.

If you use this software for a publication please cite:

• Reuter, Rosas, Fischl (2010). Highly accurate inverse consistent registration: a robust approach. NeuroImage 53(4):1181-1196. https://doi.org/10.1016/j.neuroimage.2010.07.040

• Reuter, Schmansky, Rosas, Fischl (2012). Within-subject template estimation for unbiased longitudinal image analysis. NeuroImage 61(4):1402-1418. https://doi.org/10.1016/j.neuroimage.2012.02.084

• Reuter, Fischl (2011). Avoiding asymmetry-induced bias in longitudinal image processing. NeuroImage 57(1):19-21. https://doi.org/10.1016/j.neuroimage.2011.02.076

If you use bbreg specifically, please also cite:

• Greve, Fischl (2009). Accurate and robust brain image alignment using boundary-based registration. NeuroImage 48(1):63-72. https://doi.org/10.1016/j.neuroimage.2009.06.060

We invite you to check out our lab webpage at https://deep-mi.org