VoxelMorph is a framework for Unsupervised Learning with CNNs for Image Registration.

The repository incorporates several variants, first presented at CVPR2018 (initial unsupervised learning), then MICCAI2018 (probabilistic & diffeomorphic formulation), and several other extensions and analyses.

keywords: machine learning, convolutional neural networks, alignment, mapping, registration

It might be useful to have each folder inside theext folder on your python path.assuming voxelmorph is setup at/path/to/voxelmorph/:

export PYTHONPATH=$PYTHONPATH:/path/to/voxelmorph/ext/neuron/:/path/to/voxelmorph/ext/pynd-lib/:/path/to/voxelmorph/ext/pytools-lib/

If you would like to train/test your own model, you will likely need to write some of the data loading code in 'datagenerator.py' for your own datasets and data formats. There are several hard-coded elements related to data preprocessing and format.

These instructions are for the MICCAI2018 variant usingtrain_miccai2018.py.
If you'd like to run the CVPR version (no diffeomorphism or uncertainty measures, and using CC/MSE as a loss function) usetrain.py

1. Change the top parameters intrain_miccai2018.py to the location of your image files.
2. Runtrain_miccai2018.py with options described in the main function at the bottom of the file. Example:

train_miccai2018.py /my/path/to/data --gpu 0 --model_dir /my/path/to/save/models

In our experiments,/my/path/to/data contains onenpz file for each subject saved in the variablevol_data.

We provide a T1 brain atlas used in our papers atdata/atlas_norm.npz.

1. Put test filenames in data/test_examples.txt, and anatomical labels in data/test_labels.mat.
2. Runpython test_miccai2018.py [gpu-id] [model_dir] [iter-num]

For the CC loss function, we found a reg parameter of 1 to work best. For the MSE loss function, we found 0.01 to work best.

For our data, we foundimage_sigma=0.01 andprior_lambda=25 to work best.

In the original MICCAI code, the parameters were applied after the scaling of the velocity field. With the newest code, this has been "fixed", with different default parameters reflecting the change. We recommend running the updated code. However, if you'd like to run the very original MICCAI2018 mode, please usexy indexing anduse_miccai_int network option, with MICCAI2018 parameters.

• The spatial transform code, found atneuron.layers.SpatialTransform, accepts N-dimensional affine and dense transforms, including linear and nearest neighbor interpolation options. Note that original development of VoxelMorph usedxy indexing, whereas we are now emphasizingij indexing.

• For the MICCAI2018 version, we integrate the velocity field usingneuron.layers.VecInt. By default we integrate using scaling and squaring, which we found efficient.

If you use voxelmorph or some part of the code, please cite:

Unsupervised Learning for Fast Probabilistic Diffeomorphic Registration
Adrian V. Dalca,Guha Balakrishnan,John Guttag,Mert R. Sabuncu
MICCAI 2018.eprint arXiv:1805.04605

An Unsupervised Learning Model for Deformable Medical Image Registration
Guha Balakrishnan,Amy Zhao,Mert R. Sabuncu,John Guttag,Adrian V. Dalca
CVPR 2018.eprint arXiv:1802.02604

2018-11-10: Added support for multi-gpu training
2018-10-12: Significant overhaul of code, especially training scripts and new model files.
2018-09-15: Added MICCAI2018 support and py3 transition
2018-05-14: Initial Repository for CVPR version, py2.7

For and problems or questions please open an issue in github or email us atvoxelmorph@mit.edu