The LDDMM algorithm, introduced in Faisal Beg et al. (2005), has been a centerpiece of establishing diffeomorphic registration. It expands the large deformation model based on the model of viscous fluids (Christensen, Rabbitt, and Miller 1996) by proposing a gradient-descent based optimization algorithm based on the derivation of the Euler-Lagrange equation for the variational minimization of vector fields.
While many open source implementations of the algorithm exist, most of them are either implemented in hard to understand languages (most notable C++, as in this example), or not commented at all (such as this python implementation).
This implementation aims at making the algorithm accessible for learning. It stays true to the original paper "Computing Large Deformation Metric Mappings via Geodesic Flows of Diffeomorphisms" by Faisal Beg et al. (2005), and avoids further complications. The code contains explanetory comments, frequently references steps and equations of the paper, and keeps variable names consistent with the paper. An additional (less mathematical, more algorithmical) description is given in the additional documentation PDF.
This implementation is not focused at performance, or even at obtaining best registration results. While small speedups can be achieved even with minor changes to the algorithm, this implementation closely follows the LDDMM algorithm as explained in the paper. In an effort to make the code easily understandable, only the registration of 2d images is supported. Volumentric images are not supported.
The provided software runs on python3. All required dependencies can easily be instaled with pip:
pip3 install -r requirements.txt
Two example images are provided. A circle translation, and morphing a circle to a square. An example is shown at the top of this README.
The examples can be executed with:
python3 -m examples.translation_example
python3 -m examples.circle_to_square_expample
Output files are written into the directory example_images.
The algorithm is explained in the original paper. An additional (less mathematical, more algorithmical) description is given in the additional documentation PDF. The commented code is in the file pyLDDMM/LDDMM.py.