Boundary-based registration API

neuroreg.bbreg.register

neuroreg.bbreg.register.register_surface(mov, lh_surf=None, rh_surf=None, lh_thickness=None, rh_thickness=None, ref=None, subject_dir=None, seg=None, lta_name=None, dof=6, contrast=None, init_type='header', init_lta=None, init_ras=None, cost_type='contrast', wm_proj_abs=1.4, gm_proj_frac=0.5, gm_proj_abs=None, lh_cortex_label=None, rh_cortex_label=None, slope=0.5, gradient_weight=0.0, subsample=1, n_iters=200, lr=0.01, early_stop_patience=20, device='cpu', return_model=False)[source]

Register a moving image to cortical surface boundaries using BBR.

This is the main Python API for the boundary-based registration path. The moving image is aligned to a target anatomical space defined either by a FreeSurfer/FastSurfer subject directory, explicit white-matter surface files plus a reference image, or a segmentation from which surfaces are extracted on the fly.

Public transform direction is always moving/source -> target/reference. That convention applies to init_ras, init_lta, the returned tensor, and any written LTA. Internally the BBR model optimizes the inverse transform because that is the natural parameterization for sampling the moving volume at target-surface locations, but that internal detail is hidden at the API boundary.

Parameters:
movstr or nib.Nifti1Image

Moving/source image to align into the target/reference space.

lh_surf, rh_surfstr, optional

Explicit left/right white-matter surface files for surface-input mode.

lh_thickness, rh_thicknessstr, optional

Optional cortical thickness files paired with lh_surf and rh_surf.

refstr or nib.Nifti1Image, optional

Reference anatomical image used with explicit-surface mode.

subject_dirstr, optional

FreeSurfer/FastSurfer subject directory providing surfaces and mri/orig.mgz.

segstr, optional

Segmentation volume used to extract white-matter surfaces on the fly.

lta_namestr, optional

Output path for a written LTA in public moving -> target direction.

dofint, default=6

Transformation degrees of freedom.

contrast{“t1”, “t2”}, optional

Expected image contrast for the BBR intensity model. When None, the model auto-detects the polarity.

init_type{“header”, “lta”}, default=”header”

Initialization source when init_ras is not supplied.

init_ltastr, optional

Existing LTA used for initialization. It must encode a moving/source -> target/reference transform.

init_rasndarray, optional

Initial 4x4 RAS-to-RAS transform in public moving/source -> target/reference direction.

cost_type{“contrast”, “gradient”, “both”}, default=”contrast”

Cost terms included in the BBR objective.

wm_proj_absfloat, default=1.4

White-matter sampling depth in millimetres.

gm_proj_fracfloat, default=0.5

Gray-matter sampling depth as a fraction of cortical thickness.

gm_proj_absfloat, optional

Absolute gray-matter projection depth overriding gm_proj_frac.

lh_cortex_label, rh_cortex_labelstr, optional

Optional cortex label files restricting sampled vertices.

slopefloat, default=0.5

Slope of the sigmoid used in the contrast cost.

gradient_weightfloat, default=0.0

Relative weight of the gradient term when cost_type='both'.

subsampleint, default=1

Use every subsample-th surface vertex during optimization.

n_itersint, default=200

Maximum number of RMSprop iterations.

lrfloat, default=0.01

RMSprop learning rate.

early_stop_patienceint, default=20

Stop after this many non-improving iterations. Set 0 to disable early stopping.

devicestr, default=”cpu”

Torch device on which to run the optimization.

return_modelbool, default=False

If True, also return the fitted BBRModel for debugging or inspection.

Returns:
torch.Tensor or tuple[torch.Tensor, BBRModel]

By default, returns the best-found RAS-to-RAS transform in public moving/source -> target/reference direction. When return_model=True, also returns the fitted BBRModel.

Raises:
ValueError

If the requested input mode is incomplete or unsupported.

RuntimeError

If optimization fails to produce any valid iterate.

Parameters:

  • mov (str | Nifti1Image)

  • lh_surf (str | None)

  • rh_surf (str | None)

  • lh_thickness (str | None)

  • rh_thickness (str | None)

  • ref (str | Nifti1Image | None)

  • subject_dir (str | None)

  • seg (str | None)

  • lta_name (str | None)

  • dof (int)

  • contrast (Literal['t1', 't2'] | None)

  • init_type (Literal['header', 'lta'])

  • init_lta (str | None)

  • init_ras (ndarray | None)

  • cost_type (Literal['contrast', 'gradient', 'both'])

  • wm_proj_abs (float)

  • gm_proj_frac (float)

  • gm_proj_abs (float | None)

  • lh_cortex_label (str | None)

  • rh_cortex_label (str | None)

  • slope (float)

  • gradient_weight (float)

  • subsample (int)

  • n_iters (int)

  • lr (float)

  • early_stop_patience (int)

  • device (str)

  • return_model (bool)

Return type:

Tensor | tuple[Tensor, BBRModel]