= EasyReg =

'''''This functionality is available in FreeSurfer 7.4 '''''
<<BR>>
<<BR>>
<<BR>>

''Author: Juan Eugenio Iglesias''
<<BR>>

''E-mail: jiglesiasgonzalez [at] mgh.harvard.edu''
<<BR>>
<<BR>>
''Rather than directly contacting the author, please post your questions on this module to the FreeSurfer mailing list at freesurfer [at] nmr.mgh.harvard.edu''
<<BR>>
<<BR>>
If you use EasyReg in your analysis, please cite:

 * [[https://www.nature.com/articles/s41598-023-33781-0|A ready-to-use machine learning tool for symmetric multi-modality registration of brain MRI]]. JE Iglesias. Scientific Reports, 13, 6657 (2023).

Since EasyReg builds on prior work, please cite this previous paper as well:

 * [[https://ieeexplore.ieee.org/document/9552865|SynthMorph: Learning Contrast-Invariant Registration Without Acquired Images]]. M Hoffmann, B Billot, DN Greve, JE Iglesias, B Fischl, AV Dalca, IEEE TMI, 41(3),  pp 543 - 558 (2021).


<<BR>>


=== Contents ===

 1. General Description
 2. Installation
 3. Usage
 4. Frequently asked questions (FAQ)


<<BR>>



=== 1. General Description ===

EasyReg makes deep learning registration of brain MRI easy to use, while exhibiting the best features of classical and deep learning registration tools:

 * No preprocessing is needed (e.g., skull stripping, bias field correction, affine registration to template).
 * Does affine and nonlinear registration.
 * Registration is diffeomorphic and invertible (forward and backward fields are provided).
 * The method is symmetric: if you switch the order of the inputs, your forward field will be equal to your backward field if you had not switched the order (and vice versa).
 * It handles MRI scans of any orientation (sagittal/coronal/axial), resolution, and modality (T1, T2, FLAIR, etc).
 * Reference and floating images can be of different orientation, resolution, and modality.
 * It has no parameters to tune.
 * It is fast (about one minute on a modern CPU).

<<BR>>

=== 2. Installation ===

The first time you run this module, it may prompt you to install some packages; simply follow the instructions in the screen (please install the CPU version, if given the option).

<<BR>>

=== 3. Usage ===

You can use EasyReg with the following command:

{{{
mri_easyreg --ref <reference_image> --flo <floating_image>  \
            --ref_seg <ref_image_segmentation> --flo_seg <flo_image_segmentation>  \
            --ref_reg [deformed_ref_image] --flo_reg <deformed_flo_image>  \
            --fwd_field [forward_field] --bak_field <backward_field>  \
            --threads <number_of_threads> --affine_only
}}}

where:
 * ''<reference_image>'': (required) the reference image in .nii(.gz) or .mgz format (note that, since the method is symmetric, the choice of reference vs floating is arbitrary).
 * ''<floating_image>'': (required) the floating image.
 * ''<ref_image_segmentation>'': (required) file with the SynthSeg v2 (non-robust) segmentation + parcellation of the reference image. If it does not exist, EasyReg will create it. If it already exists (e.g., from a previous EasyReg run), then EasyReg will read it from disk (which is faster than segmenting).
 * ''<flo_image_segmentation>'': (required) same for floating image.
 * ''<deformed_ref_image>'': (optional) this is the file where the deformed (registered) reference image is written.
 * ''<deformed_flo_image>'': (optional) this is the file where the deformed (registered) floating image is written.
 * ''<forward_field>'': (optional) this is the file where the forward deformation field is written. The deformation includes both the affine and nonlinear components. Must be a nifti (.nii/.nii.gz) or .mgz file; it is encoded as the real world (RAS) coordinates of the target location for each voxel.
 * ''<backward_field>'': (optional) this is the file where the backward deformation field is written. It must also be a nifty or mgz file.
 * ''<threads>'': (optional) Number of threads to use. Set to -1 to use the maximum (i.e., the total number of available cores). Note that the default is 1, which will run much more slowly.
 * ''--affine_only'': (optional) Use this flag to skip the nonlinear registration estimated by the neural network (i.e., do affine  only).

We note that the segmentations are a (often useful) by-product of EasyReg. Also: once the segmentation file has been written, EasyReg can register the corresponding scan to other cases without having to segment it again.

<<BR>>

If you want to apply a deformation field to a different image (e.g., a segmentation, to propagate labels to another space), you can run:

{{{
mri_easywarp --i <input_image> --o <output_image> --field <field> --threads <number_of_threads> --nearest
}}}

where:
 * ''<input_image>'': (required) the image to deform. 
 * ''<output_image>'': (required) the output (deformed) image.
 * ''<field>'': (required) the deformation field produced by mri_easyreg.
 * ''<threads>'': (optional) Number of threads to use (same as for mri_easyreg).
 * ''<nearest>'': (optional) Use this flag for nearest neighbor interpolation (default is trilinear). This is useful when deforming discrete segmentations.

We note that the fields are specified in RAS, and therefore, can be used with images that do not necessarily live in the same voxel grid as those provided to mri_easyreg - but must of course live in the same real-world (RAS) coordinates.



=== 4. Frequently asked questions (FAQ) ===

 * '''Does running this tool require preprocessing of the input scans?'''

No! Because we applied aggressive augmentation during training (see paper), this tool is able to segment both processed and unprocessed data.
So there is no need to apply bias field correction, skull stripping, or intensity normalisation.


 * '''What formats are supported?'''

This tool can be run on Nifti (.nii/.nii.gz) and FreeSurfer (.mgz) scans. Note that the fields are also .nii/.nii.gz/.mgz files. 


<<BR>>