registration — image registration

Schema: RegistrationConfig in src/thesis/core/config/validators.py. Drives the standalone registration workflow and the patient → template registration stage inside full_pipeline.

Two distinct “registrations” — don’t confuse them.

• This registration: block configures the patient → template registration (e.g. ANTs/FireANTs SyN to a study template). Its fixed_image is the template.

• The intra-subject DWI → T1 coregistration (plus T2 → T1 and MNI-label warps) inside the preprocess workflow is a separate step, toggled by preprocess.run_coregistration (bool, default True; not by this block). That toggle is defined authoritatively in the preprocessing guide. full_pipeline consumes its DWI→T1 transform to place atlas ROIs on the DWI grid; it is optional — when off, ROIs are regridded instead, which is only valid when T1 and DWI already share a world. (preprocess.run_coregistration was previously named run_registration.)

Top-level fields

Field	Type	Default	Constraints	Description
enabled	bool	True	—	Whether the registration workflow is enabled.
method	str	"ants"	one of ants / fireants / fsl / dipy	Registration backend. ants uses antsRegistration, fireants uses the Python FireANTs package (pip install fireants). fsl and dipy exist in the schema but are not currently wired into the workflow factories.
moving_modality	str	"t1"	one of t1 / t2	Modality selector. Falls back to hcp.t1_image or hcp.t2_image if moving_image is unset.
moving_image	str | None	None	—	Optional explicit moving-image path. When set, overrides the moving_modality fallback.
fixed_image	str	""	—	Path to the template-space fixed image. Required when the workflow runs.
interpolation	str	"Linear"	ANTs interpolation names	Interpolation method applied during resampling.
metric	str	"MI"	—	Similarity metric (MI, CC, MeanSquares, etc. as supported by ANTs).
transform_type	str	"SyN"	one of Rigid / Affine / SyN	Transform family.
use_float	bool	True	—	Use float precision in ANTs.
collapse_output_transforms	bool	True	—	Pass --collapse-output-transforms to antsRegistration.
write_composite_transform	bool	True	—	Pass --write-composite-transform to antsRegistration.
output_subdir	str	"registration"	—	Patient output subdirectory for registration artefacts.
fireants	FireantsRegistrationConfig	(see below)	—	FireANTs backend settings. Used only when method: fireants.
viewer	RegistrationViewerConfig	(see below)	—	Post-registration QC viewer settings.
jobs	List[RegistrationJobConfig]	[]	job names must be unique	Named registration jobs. When empty, the top-level fields above are treated as a single implicit job named patient_to_template. Each job may override the shared defaults and supply a sparse fireants block merged onto registration.fireants.

registration.fireants — FireantsRegistrationConfig

Field	Type	Default	Constraints	Description
device	str	"cuda"	—	Torch device string (e.g. cuda, cuda:0, cpu).
scales	List[int]	[4, 2, 1]	—	Multi-resolution pyramid scales.
affine_iterations	List[int]	[200, 100, 50]	same length as scales	Affine iterations per scale.
deformable_iterations	List[int]	[200, 100, 25]	same length as scales	Deformable iterations per scale.
optimizer	str	"Adam"	one of Adam / SGD	FireANTs optimizer.
affine_lr	float	3e-3	> 0	Affine learning rate.
deformable_lr	float	0.5	> 0	Deformable learning rate.
cc_kernel_size	int	5	≥ 1	Cross-correlation kernel size.
loss_type	str	"cc"	one of cc / mi / mse / fusedcc / fusedmi	Similarity metric for the rigid/affine/deformable stages. cc (local NCC, same-modality), mi (mutual information, robust to contrast differences / cross-dataset), mse, or the GPU-fused variants fusedcc/fusedmi. On a CUDA device cc/mi are auto-upgraded to their fused equivalents; on CPU the fused variants fall back to non-fused.
normalize	bool	True	—	Min-max normalise fixed and moving intensities to [0, 1] before registration. Strongly recommended when the two images come from different sources / intensity ranges (e.g. MNI vs a study template).
deformation_type	str	"compositive"	one of compositive / geodesic	FireANTs deformation model.
dtype	str	"float32"	one of float16 / float32 / bfloat16	Torch dtype.
deformable_max_spacing_mm	float | None	None	> 0 if set	Cap on the deformable-step image spacing. When the template has finer voxels, both images are resampled to this cap before FireANTs runs. None = no cap (best quality, more VRAM).
do_moments	bool	True	—	Run the MomentsRegistration stage (centre-of-mass + principal-axis init). Provides the robust orientation/spacing initialisation that previously required the ANTs hack. Disable only if your moving and template images already share a world.
do_rigid	bool	True	—	Run the RigidRegistration stage before the affine. When off, the moments affine init is used directly.
moments_scale	int	4	≥ 1	Downsampling scale used for the moments init stage. FireANTs recommends 4 (the moments init is robust at low resolution).
moments_moments	int	1	≥ 1	Number of moments used in the moments init. FireANTs recommends 1 (centre-of-mass + first order); 2 adds a second-order principal-axis term prone to 180° flips on near-symmetric brains.
rigid_iterations	List[int]	[200, 100, 25]	same length as scales	Rigid-stage iterations per pyramid scale.
rigid_lr	float	3e-2	> 0	Rigid-stage learning rate.
deform_algo	str	"greedy"	one of greedy / syn	Deformable engine for transform_type: SyN. greedy (GreedyRegistration) yields an analytic inverse warp (save_inverse=True). syn (SyNRegistration) does not support analytic inverse export and raises on the reverse warp — use only for forward-only experiments.
inverse_method	str	"simpleitk"	one of simpleitk / fireants	How the reverse (template→patient) warp is produced for SyN-family transforms. simpleitk numerically inverts the forward displacement field with SimpleITK (ANTs-free, explicit convergence tolerance, works for both greedy and syn); fireants uses FireANTs’ own inverse-consistency solve (greedy only). simpleitk is recommended.
inverse_max_iterations	int	50	≥ 1	Maximum fixed-point iterations for the SimpleITK displacement-field inversion (inverse_method: simpleitk).
inverse_tolerance	float	0.01	> 0	Mean-error tolerance (mm) for the SimpleITK displacement-field inversion. Lower = tighter inverse, more iterations.
driver	str	"inprocess"	one of inprocess / cli	How the staged FireANTs flow is executed. inprocess runs inside the Nipype Function node; cli shells out to a standalone entry point (A/B harness).

affine_backend removed. Earlier versions exposed an affine_backend: ants \| fireants knob that shelled out to antsRegistrationSyNQuick.sh for the affine step. The FireANTs backend now runs a native staged flow (MomentsRegistration → RigidRegistration → AffineRegistration → GreedyRegistration); the moments stage provides the robust orientation init the ANTs hack was substituting for. affine_backend is no longer a field — configs that still set it fail validation (extra="forbid"). Remove it.

A model_validator enforces that affine_iterations, deformable_iterations, and rigid_iterations all have the same length as scales. The moments stage is always run in float32 (it rejects fp16/bf16); when dtype is float16/bfloat16 a separate float32 image pair is loaded just for moments while the rigid/affine/deformable stages use the configured dtype.

registration.viewer — RegistrationViewerConfig

Field	Type	Default	Constraints	Description
enabled	bool	True	—	Whether viewer support is enabled.
backend	str	"fsleyes"	one of fsleyes / html	Viewer backend. Only fsleyes is implemented; html is reserved.
auto_open	bool	False	—	Launch the viewer automatically after registration completes.
overlay_opacity	float	0.5	0.0 ≤ x ≤ 1.0	Opacity of the warped patient image overlay.

Example

registration:
  enabled: true
  method: fireants
  moving_modality: t1
  fixed_image: data/templates/template_T1w.nii.gz
  transform_type: SyN
  interpolation: Linear
  metric: MI
  output_subdir: registration

  fireants:
    device: cuda
    scales: [4, 2, 1]
    affine_iterations: [200, 100, 50]
    deformable_iterations: [200, 100, 25]
    optimizer: Adam
    affine_lr: 0.003
    deformable_lr: 0.5
    cc_kernel_size: 5
    loss_type: cc                    # cc | mi | mse | fusedcc | fusedmi
    normalize: true                  # min-max to [0,1] before registration
    deformation_type: compositive
    dtype: float32
    deformable_max_spacing_mm: 1.0   # cap resolution to keep GPU happy
    # ---- native staged affine-init knobs (replaces the old affine_backend hack) ----
    do_moments: true
    do_rigid: true
    moments_scale: 4
    moments_moments: 1
    rigid_iterations: [200, 100, 25]  # must match len(scales)
    rigid_lr: 0.03
    deform_algo: greedy              # greedy | syn (syn disables analytic inverse)
    inverse_method: simpleitk        # simpleitk | fireants
    driver: inprocess                # inprocess | cli

  viewer:
    enabled: true
    backend: fsleyes
    auto_open: false
    overlay_opacity: 0.5

registration.jobs — named multi-job registration

By default the block above describes a single registration synthesised into one implicit job named patient_to_template (legacy-flat on-disk layout under registration/transforms/). No jobs: entry is required for the common case.

To run several registrations in one pass, list them under registration.jobs. Each entry is a RegistrationJobConfig: a required name plus optional per-job overrides for any of method, moving_modality, moving_image, fixed_image, interpolation, metric, transform_type, use_float, and a sparse fireants dict (merged onto and re-validated against the shared registration.fireants). Unset fields inherit the shared top-level values. Job names must be unique.

Explicit (non-default) jobs write to a nested layout (registration/<job>/transforms/<pid>_<job>_*); the implicit default job keeps the legacy-flat paths so existing on-disk caches stay valid. Downstream transform jobs reference a registration job by name via transforms.jobs[*].from_registration (see the transforms guide).

registration:
  method: fireants
  fixed_image: data/templates/template_T1w.nii.gz
  transform_type: SyN
  # ... shared fields inherited by every job below ...
  jobs:
    - name: patient_to_template      # legacy-flat layout; inherits all shared fields
      transform_type: SyN
    - name: t2_affine                # nested layout: registration/t2_affine/transforms/
      moving_modality: t2
      transform_type: Affine
      fireants:                      # sparse override, re-validated on merge
        deform_algo: greedy

Notes

• FireANTs deformable runs export affine + composed warp as ANTs-compatible 5-D NIfTI (intent_code=1007). The transform list contains only the warp file; no separate affine is emitted.

• Install FireANTs separately when using that backend: pip install fireants.

• The CLI does not expose registration-specific flags; configure via YAML.