Skip to main content

Image registration toolbox based on pyTorch

Project description

                                      _     _ 
                                     (_)   | |
  _ __ ___   ___ _ __ _ __ ___   __ _ _  __| |
 | '_ ` _ \ / _ \ '__| '_ ` _ \ / _` | |/ _` |
 | | | | | |  __/ |  | | | | | | (_| | | (_| |
 |_| |_| |_|\___|_|  |_| |_| |_|\__,_|_|\__,_|


Documentation Status Build Status

iMagE Registration via autoMAtIc Differentiation

Mermaid is a registration toolkit making use of automatic differentiation for rapid prototyping. It is written in PyTorch and runs on the CPU and the GPU. Though GPU acceleration only becomes obvious for large images or 3D volumes. It supports registration of 1D (functions), 2D, and 3D images.

The easiest way to install a development version is to clone the repository, create a virtual conda environment and install it in there. This can be done as follows for a development installation:

conda create --name mermaid python=3.7 pip
conda activate mermaid
python develop

Or like this if you want to do a standard installation of mermaid:

conda create --name mermaid python=3.7 pip
conda activate mermaid
python install

There is also a nice documentation which can be built by executing

cd mermaid
cd docs
make html

You can also find the latest version on readthedocs:

In the near future there will also be a conda installer available. This will then allow installations via

conda install -c pytorch -c conda-forge -c anaconda -c uncbiag mermaid

There are already initial OSX/Linux versions available which can be installed via conda, but there are still some issues that need to be ironed out, so they might not be fully functional yet. Stay tuned.

Supported transformation models:

  • affine_map: map-based affine registration
  • diffusion_map: displacement-based diffusion registration
  • curvature_map: displacement-based curvature registration
  • total_variation_map: displacement-based total variation registration
  • svf_map: map-based stationary velocity field
  • svf_image: image-based stationary velocity field
  • svf_scalar_momentum_image: image-based stationary velocity field using the scalar momentum
  • svf_scalar_momentum_map: map-based stationary velocity field using the scalar momentum
  • svf_vector_momentum_image: image-based stationary velocity field using the vector momentum
  • svf_vector_momentum_map: map-based stationary velocity field using the vector momentum
  • lddmm_shooting_map: map-based shooting-based LDDMM using the vector momentum
  • lddmm_shooting_image: image-based shooting-based LDDMM using the vector momentum
  • lddmm_shooting_scalar_momentum_map: map-based shooting-based LDDMM using the scalar momentum
  • lddmm_shooting_scalar_momentum_image: image-based shooting-based LDDMM using the scalar momentum
  • lddmm_adapt_smoother_map: map-based shooting-based Region specific diffemorphic mapping, with a spatio-temporal regularizer
  • svf_adapt_smoother_map: map-based shooting-based vSVF, with a spatio regularizer

Supported similarity measures:

  • ssd: sum of squared differences
  • ncc: normalize cross correlation
  • ncc_positive: positive normalized cross-correlation
  • ncc_negative: negative normalized cross-correlation
  • lncc: localized normalized cross correlation (multi-scale)

Supported solvers:

  • embedded RK4
  • torchdiffeq: explicit_adams, fixed_adams, tsit5, dopri5, euler, midpoint, rk4


  • support single/multi-scale optimizer
  • support SGD, l-BFGS and some limited support for adam


We also wrote a companion python package, easyreg, which allows training deep networks for image registration based on the registration models available in mermaid. I.e., easyreg allows training networks that backpropagate through the mermaid transformation models (SVF, LDDMM, ...). You can have a look at the package here:

Our other registration work

See for an overview of other registration approaches of our group and a short summary of how the approaches relate.

Publishing a release

To publish to conda, just tag a version in the format "major.minor.subminor". do not add a leading v. Travis will automatically push to the conda repository at uncbiag/mermaid. After this is done, to publish to pip, first locally run

pip wheel . -w dist

to build the wheel, then run

twine upload --repository pypi dist/mermaid-<version_number>--py3-none-any.whl

to publish to pypi.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

mermaid-0.3.2-py3-none-any.whl (1.2 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page