• EasyReg

EasyReg and EasyAtlas

EasyReg became available in FreeSurfer 7.4

EasyAtlas is available in development versions from November 2025 and can also be downloaded independently (see first item in FAQ below)

Author: Juan Eugenio Iglesias

E-mail: jiglesiasgonzalez [at] mgh.harvard.edu

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

If you use EasyReg or EasyAtlas in your analysis, please cite:

• 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:

• 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).

Contents

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

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).

EasyAtlas uses EasyReg to iteratively build brain a template from a set of brain MRI scan, and inherits all of EasyReg's advantages. Just throw all the scans into a directory, and press the button! On a powerful CPU, it takes about 1 min per scan in total (including segmentation, affine alignment, and iterative nonlinear alignment).

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).

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.

You can use EasyAtlas with the following command:

mri_easyatlas --i <input_directory> --o <output_directory> --threads <number_of_threads> --use_reliability_maps

where:

• <input_directory>: (required) a directory with a bunch of unpreprocessed brain MRI scans, in .nii(.gz) or .mgz format (you can mix'n'match).

• <output_directory>: (required) the directory where files will be written.

• <threads>: (optional) Number of threads to use. Set to -1 to use the maximum (i.e., the total number of available cores). The default is -1.

• --use_reliability_maps: (optional) Use this flag to apply a weighting to each voxel, depending on how 'interpolated' they are. This is recommended when biulding atlases from scans with large slice spacing.

EasyAtlas will write in the output directory:

• An affine atlas
• The progressively refined iterations of the nonlinear atlas

• Segmentations of the input scans, computed with SynthSeg.

• In the last iteration, the registration files from the original images to the atlas.

If you want to apply a deformation field from EasyReg or EasyAtlas 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 / mri_easyatlas - but must of course live in the same real-world (RAS) coordinates.

4. Frequently asked questions (FAQ)

• I have FreeSurfer 7.4 or above with EasyReg and want to try EasyAtlas, but I do not want to download a whole FreeSurfer only for that

No problem! You can download the python script from here (mri_easyatlas.py), source your existing FreeSurfer, and run the command:

fspython /path/to/mri_easyatlas.py --i <input_directory> --o <output_directory> --threads <number_of_threads> --use_reliability_maps

• 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.