registration

registration

Subworkflow to perform registration between a moving and a fixed image (e.g. T1 -> DWI). It requires as input at least a moving (ch_image) and a reference (ch_ref) image to properly perform registration.

Output transformations curated for images for use with the REGISTRATION_ANTSAPPLYTRANSFORMS module are available under the names forward_image_transform and backward_image_transform. The same lists are also available for tractograms (forward_tractogram_transform and backward_tractogram_transform). However, to use the REGISTRATION_TRACTOGRAM module, you have to use the backward_affine and backward_warp channels provided by this subworkflow.

Registration suites:

• EasyReg (ML): params.run_easyreg = true

  module: REGISTRATION_EASYREG

  Run freesurfer EasyReg any-to-any modality registration.

  NOTE: Outputs a combined warp field only, no affine transformations are available. CANNOT BE LINKED WITH THE BUNDLE_SEG SUBWORKFLOW.

• Synthmorph (ML): params.run_synthmorph = true

  module: REGISTRATION_SYNTHMORPH

  Run SynthMorph any-to-any modality registration. By default, the algorithm is configured to run a chain of affin+deformable transformations, making it suitable for use with most modules and subworkflows like BUNDLE_SEG.

  NOTE: the output affine transformation file is in .lta format and needs to be converted to .mat to be used with ANTs using the REGISTRATION_CONVERT module.

• ANTs (SyN+SyN Quick): params.run_easyreg = false && params.run_synthmorph = false

  module: REGISTRATION_ANTS or REGISTRATION_ANATTODWI

  Run ANTs registration using antsRegistrationSyN.sh (quick version also available).

  NOTE : Transformation to DWI space is available. To trigger it, supply a metric file (ch_metric) in DWI space (e.g. FA map) in addition to the moving (ch_image) and reference (ch_ref) images.

Keywords : Registration, Transformation, DWI, Anatomical

Components : registration/anattodwi, registration/ants, registration/convert, registration/easyreg, registration/synthmorph

---

Inputs

	Type	Description	Mandatory	Pattern
ch_fixed_image	file	The input channel containing the fixed image files. If performing registration to DWI space, this is the reference image (e.g. b0 image). Structure: [ val(meta), path(fixed_image) ]	True	*.{nii,nii.gz}
ch_moving_image	file	Input channel containing the moving image files. If performing registration to DWI space, this is the anatomical image to be registered. Structure: [ val(meta), path(image) ]	True	*.{nii,nii.gz}
ch_metric	file	FOR USE WITH REGISTRATION TO DWI SPACE ONLY. The input channel containing the metric files, typically a FA map. Structure: [ val(meta), path(metric) ]	False	*.{nii,nii.gz}
ch_fixed_mask	file	FOR USE WITH ANTS SYN REGISTRATION ONLY. The input channel containing the mask file in fixed image space. Structure: [ val(meta), path(mask) ]	False	*.{nii,nii.gz}
ch_segmentation	file	FOR USE WITH SYNTHMORPH REGISTRATION ONLY. The input channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in fixed image space (reference in Easyreg naming convention) image.	False	*.{nii,nii.gz}
ch_moving_segmentation	file	FOR USE WITH SYNTHMORPH REGISTRATION ONLY. The input channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in moving image space (floating in Easyreg naming convention) image.	False	*.{nii,nii.gz}

---

Outputs

	Type	Description	Mandatory	Pattern
image_warped	file	Channel containing images warped in fixed space. Structure: [ val(meta), path(image) ]	True	*.{nii,nii.gz}
reference_warped	file	ONLY PROVIDED BY REGISTRATION_EASYREG. Channel containing the reference image warped in moving space. Structure: [ val(meta), path(image) ]	False	*.{nii,nii.gz}
forward_affine	file	Channel containing the affine transformation matrix to fixed space. Structure: [ val(meta), path(forward_affine) ]	False	*__forward*.{lta,mat}
forward_warp	file	Channel containing the deformation field to fixed space. Structure: [ val(meta), path(forward_warp) ]	False	*__forward*.{nii,nii.gz}
backward_warp	file	Channel containing the deformation field to moving space. Structure: [ val(meta), path(backward_warp) ]	False	*__backward*.{nii,nii.gz}
backward_affine	file	Channel containing the affine transformation matrix to moving space. Structure: [ val(meta), path(backward_affine) ]	False	*__backward*.{lta,mat}
forward_image_transform	list	Channel containing the transformation tuples to warp images to fixed space, in the correct order for REGISTRATION_ANTSAPPLYTRANSFORMS. Structure: [ val(meta), [ path(forward_warp), path(forward_affine) ] ].	True	*__forward*.{nii,nii.gz,mat,lta}
backward_image_transform	list	Channel containing the transformation tuples to warp images to moving space, in the correct order for REGISTRATION_ANTSAPPLYTRANSFORMS. Structure: [ val(meta), [ path(backward_affine), path(backward_warp) ] ].	True	*__backward*.{nii,nii.gz,mat,lta}
forward_tractogram_transform	list	Channel containing the transformation tuples to warp tractograms to fixed space, in the correct order for REGISTRATION_TRANSFORMTRACTOGRAM. Structure: [ val(meta), [ path(backward_warp), path(backward_affine) ] ].	True	*__backward*.{nii,nii.gz,mat,lta}
backward_tractogram_transform	list	Channel containing the transformation tuples to warp tractograms to moving space, in the correct order for REGISTRATION_TRANSFORMTRACTOGRAM. Structure: [ val(meta), [ path(forward_warp), path(forward_affine) ] ].	True	*__forward*.{nii,nii.gz,mat,lta}
segmentation	file	ONLY PROVIDED BY REGISTRATION_SYNTHMORPH. Channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in moving space (floating in Easyreg naming convention). Structure: [ val(meta), path(segmentation) ]	False	*.{nii,nii.gz}
reference_segmentation	file	ONLY PROVIDED BY REGISTRATION_SYNTHMORPH. Channel containing the SynthSeg v2 (non-robust) segmentation + parcellation in fixed space (reference in Easyreg naming convention). Structure: [ val(meta), path(reference_segmentation) ]	False	*.{nii,nii.gz}
mqc	file	Channel containing the MultiQC report data for the registration. Structure: [ path(mqc) ]	False	*mqc.*
versions	file	File containing software versions used. Structure: [ path(versions.yml) ]	True	versions.yml

---

Authors

• @gagnonanthony
• @AlexVCaron

---

Last updated : 2025-12-22