Image registration API

neuroreg.imreg.robreg

Public IRLS-backed robust image-registration API.

neuroreg.imreg.robreg.register_irls_pyramid(src, trg, src_mask=None, trg_mask=None, src_affine=None, trg_affine=None, initial_transform=None, init_type='centroid', min_voxels=16, max_voxels=None, nmax=5, sat=6.0, epsit=0.01, max_irls=20, isotropic=True, isotropic_size=None, symmetric=True, adaptive_sat=False, target_outlier_pct=5.0, outliers_name=None, stop_level=0, verbose=False)[source]

Run the tensor-level IRLS pyramid registration pipeline.

This is the high-level multiresolution orchestration used by the public robreg() API. It keeps the solver logic in neuroreg.imreg.irls.register_irls() but owns the product-level concerns: isotropic preprocessing, pyramid scheduling, level-to-level transform propagation, and optional outlier-map writing.

Parameters:
src, trgTensor

Full-resolution source and target image tensors in (D, H, W) order.

src_mask, trg_maskTensor, optional

Optional binary masks in source and target space. Masked-out voxels are excluded from the IRLS system instead of being treated as zero-valued data.

src_affine, trg_affineTensor, optional

Voxel-to-RAS affines. Required when isotropic=True.

initial_transformTensor, optional

Initial voxel-to-voxel transform. If provided, it takes precedence over the requested initialization mode.

init_type{“header”, “centroid”, “image_center”}, default=”centroid”

Explicit initialization mode used when initial_transform is not provided. "image_center" matches FreeSurfer’s cras0-style center start.

min_voxelsint, default=16

Minimum size constraint passed to the shared pyramid builder.

max_voxelsint, optional

Maximum allowed size of the finest pyramid level to process. When None (default), include the original/full-resolution level.

nmaxint, default=5

Maximum number of outer IRLS iterations per pyramid level.

satfloat, default=6.0

Tukey biweight saturation threshold.

epsitfloat, default=0.01

Convergence threshold for the per-level affine update distance.

max_irlsint, default=20

Maximum number of inner IRLS iterations per outer step.

isotropicbool, default=True

If True, resample both images to a shared isotropic grid before registration.

isotropic_sizefloat, optional

Explicit isotropic voxel size in millimeters. When omitted, the shared isotropic size is derived from the source/target voxel sizes as max(min(src_voxsize), min(trg_voxsize)).

symmetricbool, default=True

If True, use symmetric (midspace) mode.

adaptive_satbool, default=False

Whether to adapt the Tukey saturation threshold based on the outlier fraction.

target_outlier_pctfloat, default=5.0

Target outlier fraction used when adaptive_sat is enabled.

outliers_namestr, optional

Output filename for the final outlier map.

stop_levelint, default=0

Finest pyramid level to process. 0 processes all levels including full resolution. 1 skips the finest level; 3 skips the three finest levels. Mirrors FreeSurfer’s stopres parameter in computeMultiresRegistration. Clamped to the available range.

verbosebool, default=False

If True, emit progress logging.

Returns:
TTensor

Final voxel-to-voxel transform in the original image space.

all_infolist of dict

Per-level information dictionaries, finest level last.

Raises:
ValueError

If isotropic registration is requested without both affines, or if no pyramid level satisfies min_voxels.

Parameters:

  • src (Tensor)

  • trg (Tensor)

  • src_mask (Tensor | None)

  • trg_mask (Tensor | None)

  • src_affine (Tensor | None)

  • trg_affine (Tensor | None)

  • initial_transform (Tensor | None)

  • init_type (Literal['header', 'centroid', 'image_center'])

  • min_voxels (int)

  • max_voxels (int | None)

  • nmax (int)

  • sat (float)

  • epsit (float)

  • max_irls (int)

  • isotropic (bool)

  • isotropic_size (float | None)

  • symmetric (bool)

  • adaptive_sat (bool)

  • target_outlier_pct (float)

  • outliers_name (str | None)

  • stop_level (int)

  • verbose (bool)

Return type:

tuple[Tensor, list[dict[str, Any]]]

neuroreg.imreg.robreg.robreg(src, trg, *, src_affine=None, trg_affine=None, src_mask=None, trg_mask=None, return_v2v=False, init_type='centroid', init_transform=None, init_lta=None, initial_r2r=None, dof=6, nmax=5, sat=6.0, symmetric=True, isotropic=True, isotropic_size=None, adaptive_sat=False, target_outlier_pct=5.0, outliers_name=None, stop_level=0, verbose=False, device='cpu')[source]

Register two images with the public IRLS robust-registration path.

Parameters are intentionally close to the tensor-level IRLS pyramid implementation, but this wrapper also accepts filenames and nibabel images.

Parameters:
src, trgImageLike

Moving/source and fixed/target images. Each input may be a path, a nibabel-like image object, or a torch.Tensor volume.

src_affine, trg_affineTensor, optional

Explicit voxel-to-RAS affines to use when src or trg are passed as tensors.

src_mask, trg_maskImageLike, optional

Optional source and target masks. Voxels outside these masks are ignored during IRLS fitting.

return_v2vbool, default=False

If True, return the estimated transform in voxel coordinates. If False, return the corresponding RAS-to-RAS transform.

init_type{“header”, “centroid”, “image_center”}, default=”centroid”

Explicit initialization mode used when no explicit transform is supplied. "image_center" matches FreeSurfer’s cras0-style center start.

init_transformInitTransformLike, optional

Unified explicit initialization transform. This may be an LTA filename, an in-memory LTA, or a 4 x 4 RAS-to-RAS matrix stored as a NumPy array or torch tensor. When provided, it overrides init_type.

init_ltastr, optional

Backward-compatible alias for file-based initialization. Prefer init_transform.

initial_r2rTensor or ndarray, optional

Backward-compatible alias for in-memory RAS-to-RAS initialization. Prefer init_transform.

dofint, default=6

Degrees of freedom. The public IRLS path currently supports rigid registration only, so this must remain 6.

nmaxint, default=5

Maximum number of IRLS outer iterations per pyramid level.

satfloat, default=6.0

Tukey biweight saturation threshold.

symmetricbool, default=True

If True, run symmetric halfway-space registration. This is the default/public robreg behavior.

isotropicbool, default=True

If True, resample to isotropic voxels before building the pyramid.

isotropic_sizefloat, optional

Explicit isotropic voxel size in millimeters. When omitted, the public robreg path derives a shared isotropic size from the source and target voxel sizes.

adaptive_satbool, default=False

Whether to adapt the Tukey saturation threshold based on the observed outlier fraction.

target_outlier_pctfloat, default=5.0

Target outlier percentage used when adaptive_sat is enabled.

outliers_namestr, optional

Output filename for the final outlier map.

stop_levelint, default=0

Finest pyramid level to process. 0 processes all levels. Higher values skip the finest levels for faster coarse-only registration. Mirrors FreeSurfer’s stopres in computeMultiresRegistration.

verbosebool, default=False

If True, emit progress logging from the IRLS implementation.

devicestr, default=”cpu”

Torch device on which to place the image tensors before registration.

Returns:
Tensor

Estimated transform matrix. This is voxel-to-voxel when return_v2v=True and RAS-to-RAS otherwise.

Raises:
ValueError

If dof is anything other than 6, or if multiple explicit initialization transforms are provided.

Parameters:

  • src (str | Path | Any | Tensor)

  • trg (str | Path | Any | Tensor)

  • src_affine (Tensor | None)

  • trg_affine (Tensor | None)

  • src_mask (str | Path | Any | Tensor | None)

  • trg_mask (str | Path | Any | Tensor | None)

  • return_v2v (bool)

  • init_type (Literal['header', 'centroid', 'image_center'])

  • init_transform (str | Path | LTA | Tensor | ndarray | None)

  • init_lta (str | None)

  • initial_r2r (Tensor | ndarray | None)

  • dof (int)

  • nmax (int)

  • sat (float)

  • symmetric (bool)

  • isotropic (bool)

  • isotropic_size (float | None)

  • adaptive_sat (bool)

  • target_outlier_pct (float)

  • outliers_name (str | None)

  • stop_level (int)

  • verbose (bool)

  • device (str)

Return type:

Tensor

neuroreg.imreg.coreg

Public dispatcher for image-to-image registration backends.

neuroreg.imreg.coreg.register_gd_pyramid(src, trg, src_mask=None, trg_mask=None, lta_name=None, mapped_name=None, keep_dtype=False, return_v2v=False, init_type='image_center', init_lta=None, symmetric=True, dof=6, n=30, level_iters=None, loss_name='mse', loss_beta=None, loss_bins=32, optimizer='adam', lr=None, translation_weight_scale=1.0, rotation_weight_scale=4.0, scale_weight_scale=1.0, shear_weight_scale=1.0, min_voxels=16, max_voxels=None, isotropic=False, device='cpu', trace_fn=None)[source]

Run the legacy gradient-descent multiresolution registration path.

This is the original PyTorch optimizer-based image-registration backend. It builds matching source/target pyramids, optionally resamples both images to a shared isotropic grid, and then optimizes from coarse to fine while propagating each level’s solution to the next.

Parameters:
src, trgstr or nibabel image

Moving and reference images.

src_mask, trg_maskoptional

Optional moving/source and reference/target masks. Masked-out voxels are excluded from the similarity objective instead of being zero-filled.

lta_name, mapped_namestr or None, optional

Optional output paths for the final LTA and resampled moving image.

keep_dtypebool, default=False

If True, cast the final mapped output back to the source image dtype when mapped_name is requested. When False, mapped output is written as float32.

return_v2vbool, default=False

Return voxel-to-voxel instead of RAS-to-RAS when True.

init_type{“header”, “centroid”, “image_center”}, default=”image_center”

Initialization strategy used on the coarsest level when init_lta is not provided.

init_ltastr, optional

Existing LTA used for initialization. When provided, it overrides the requested init_type.

symmetricbool, default=True

Run symmetric halfway-space registration when True.

dof, n, level_iters, loss_name, loss_beta, loss_bins, optimizer, lr

Registration and optimization settings for the GD path.

*_weight_scalefloat

Relative scaling factors applied to the model parameter blocks.

min_voxels, max_voxelsoptional

Shared pyramid size limits.

isotropicbool, default=False

Resample both inputs to a shared isotropic grid before building the pyramid.

devicestr, default=”cpu”

Torch device string used by the GD optimizer.

trace_fncallable, optional

Optional callback receiving run, level, and iteration events.

Returns:
Tensor

The final transform as RAS-to-RAS by default, or voxel-to-voxel when return_v2v=True.

Raises:
ValueError

If pyramid construction produces no levels for the source or target image.

Parameters:

  • src (str | Nifti1Image)

  • trg (str | Nifti1Image)

  • src_mask (str | SpatialImage | Tensor | None)

  • trg_mask (str | SpatialImage | Tensor | None)

  • lta_name (str | None)

  • mapped_name (str | None)

  • keep_dtype (bool)

  • return_v2v (bool)

  • init_type (Literal['header', 'centroid', 'image_center'])

  • init_lta (str | None)

  • symmetric (bool)

  • dof (int)

  • n (int)

  • level_iters (list[int] | tuple[int, ...] | None)

  • loss_name (str)

  • loss_beta (float | None)

  • loss_bins (int)

  • optimizer (str)

  • lr (float | None)

  • translation_weight_scale (float)

  • rotation_weight_scale (float)

  • scale_weight_scale (float)

  • shear_weight_scale (float)

  • min_voxels (int)

  • max_voxels (int | None)

  • isotropic (bool)

  • device (str)

Return type:

Tensor

neuroreg.imreg.coreg.coreg(src, trg, src_mask=None, trg_mask=None, lta_name=None, mapped_name=None, keep_dtype=False, return_v2v=False, init_type='image_center', init_lta=None, method='powell', symmetric=True, dof=6, n=30, level_iters=None, loss_name='mse', loss_beta=None, loss_bins=32, optimizer='adam', lr=None, translation_weight_scale=1.0, rotation_weight_scale=4.0, scale_weight_scale=1.0, shear_weight_scale=1.0, min_voxels=16, max_voxels=None, isotropic=False, device='cpu', powell_brute_force_limit=30.0, powell_brute_force_iters=1, powell_brute_force_samples=30, powell_maxiter=4, powell_sep=4, trace_fn=None)[source]

Run public image-to-image registration.

Parameters:
src, trgstr or nibabel image

Moving and reference images.

src_mask, trg_maskoptional

Optional masks in moving/source and reference/target space. Voxels outside these masks are excluded from the similarity objective.

lta_name, mapped_namestr or None, optional

Optional output paths for the final transform and mapped moving image.

keep_dtypebool, default=False

If True, cast the final mapped moving image back to the source image dtype when mapped_name is requested. When False, mapped output is written as float32.

return_v2vbool, default=False

Return the final transform in voxel coordinates instead of RAS.

init_type{“header”, “centroid”, “image_center”}, default=”image_center”

Initialization strategy for the selected backend when init_lta is not provided.

init_ltastr, optional

Existing LTA used for initialization. When provided, it overrides the requested init_type.

method{“powell”, “gd”}, default=”powell”

Registration backend. "powell" uses the MRI_coreg-style brute-force plus Powell path; "gd" runs the legacy PyTorch gradient-descent pyramid.

symmetric, dof, n, level_iters, loss_name, loss_beta, loss_bins, optimizer, lr

Gradient-descent backend options.

*_weight_scalefloat

Parameter-block scaling forwarded to the GD registration model.

min_voxels, max_voxels, isotropic, device

Pyramid and device settings.

powell_brute_force_limit, powell_brute_force_iters, powell_brute_force_samples

Coarse search settings for the Powell backend.

powell_maxiterint, default=4

Maximum Powell refinement iterations.

powell_sepint, default=4

Sampling spacing for the Powell evaluator.

trace_fncallable, optional

Optional callback receiving backend-specific progress events.

Returns:
Tensor

Final RAS-to-RAS transform by default, or voxel-to-voxel when return_v2v=True.

Raises:
ValueError

If method is not "powell" or "gd".

Parameters:

  • src (str | Nifti1Image)

  • trg (str | Nifti1Image)

  • src_mask (str | SpatialImage | Tensor | None)

  • trg_mask (str | SpatialImage | Tensor | None)

  • lta_name (str | None)

  • mapped_name (str | None)

  • keep_dtype (bool)

  • return_v2v (bool)

  • init_type (Literal['header', 'centroid', 'image_center'])

  • init_lta (str | None)

  • method (str)

  • symmetric (bool)

  • dof (int)

  • n (int)

  • level_iters (list[int] | tuple[int, ...] | None)

  • loss_name (str)

  • loss_beta (float | None)

  • loss_bins (int)

  • optimizer (str)

  • lr (float | None)

  • translation_weight_scale (float)

  • rotation_weight_scale (float)

  • scale_weight_scale (float)

  • shear_weight_scale (float)

  • min_voxels (int)

  • max_voxels (int | None)

  • isotropic (bool)

  • device (str)

  • powell_brute_force_limit (float)

  • powell_brute_force_iters (int)

  • powell_brute_force_samples (int)

  • powell_maxiter (int)

  • powell_sep (int)

Return type:

Tensor