freesurfer/synthmorph repository overview

⁠SynthMorph

SynthMorph is a deep-learning tool for rigid, affine, and deformable registration of brain MRI without preprocessing such as skull-stripping. The tool registers image volumes of any size, resolution, orientation, and contrast. The moving and the fixed image geometries can differ, and you can change the regularization strength at test time. For details, visit synthmorph.io⁠.

⁠Wrapper script

While FreeSurfer⁠ includes the command-line utility mri_synthmorph, the Docker image serves as a standalone version. We provide the script synthmorph to facilitate setup and use of our containers. The script requires Python 3 and any of the container tools: Docker, Podman, Apptainer, or Singularity.

⁠Initial setup

When you first run synthmorph, it will pull the latest image from the Docker Hub. If you use Apptainer or Singularity, synthmorph will save the image in your current directory. Avoid pulling new containers when you change directory by setting the variable sif_file at the top of the script to an absolute path. Similarly, change version to update to a new image. Change tools to use a particular container tool, if you have several installed.

If your home directory has a low quota, have Apptainer and Singularity cache elsewhere. For example,

d=$(mktemp -d)
export APPTAINER_CACHEDIR="$d"
export APPTAINER_TMPDIR="$d"

Download and run the script with:

curl -Lo synthmorph https://get.synthmorph.io
chmod +x synthmorph
./synthmorph

After setup, synthmorph will pass any arguments on to mri_synthmorph in the container.

⁠File path translation

Reading and writing data on your host system from within the container requires a bind mount. For convenience, synthmorph temporarily mounts the host directory defined by environment variable SUBJECTS_DIR to /mnt in the container, which is also the working directory in the container. If unset, SUBJECTS_DIR defaults to your current directory. This means that synthmorph can read from and write to relative paths under your working directory without your setting SUBJECTS_DIR. In other words, SUBJECTS_DIR sets the working directory of synthmorph, and you can specify paths relative to it.

⁠Examples

Change into or set the working directory of synthmorph to ~/data:

export SUBJECTS_DIR=~/data

Register image ~/data/moving.nii to ~/data/atlas/fixed.nii, saving the moved image ~/data/moved.nii and transform ~/data/trans.nii:

./synthmorph register -o moved.nii -t trans.nii moving.nii atlas/fixed.nii

Apply an existing transform to an image:

./synthmorph apply trans.nii moving.nii out.nii.gz

Apply an existing transform to label (segmentation) map ~/data/labels.nii:

./synthmorph apply -m nearest trans.nii labels.nii out.mgz

⁠Command usage

For detailed instructions, run ./synthmorph -h or visit synthmorph.io⁠.

⁠Changes

• synthmorph:4, synthmorph:latest⁠
  - include functionality for transforming images and label maps
  - add subcommands register and apply
  - apply the same transform to any number of images
  - let users abbreviate subcommands, models, interpolation methods
  - improve compatibility with TensorFlow versions using Keras 3

• synthmorph:3⁠
  - fix -e flag for specifying extent of registration space
  - fix initialization bug affecting inverse warps (#1175⁠)
  - remove need for conversion prior to applying warps with mri_convert -at
  - flexibly load alternative weights from one or several files
  - handle deformable transforms with surfa⁠
  - add option for deformable registration in affine mid-space
  - improve deformable hypernetwork weights
  - relax constraints on initial transform geometries

• synthmorph:2⁠
  - improve deformation field regularity
  - let users choose the regularization strength at registration time
  - predict symmetric transforms with respect to the input image order
  - enable joint affine-deformable registration in one shot
  - change default registration model from deformable to joint
  - change working directory to /mnt to let users specify relative paths
  - switch matrix file format to FreeSurfer LTA to track image geometries
  - let users control the number of integration steps
  - add options to save inverse transforms
  - change user interface

• synthmorph:1⁠
  - release initial image

⁠Contact

Reach out to the FreeSurfer mailing list⁠, start a discussion, or open an issue⁠ on GitHub.