An open source research library for image, point set, and surface registration in PyTorch, which is developed and maintained by the HeartFlow-Imperial College London research lab at the Biomedical Image Analysis Group.
Deepali is a Hindu/Sanskrit Indian given name, which means "joy" as in the gratification one may feel working with code built on a modern tensor library with support for automatic differentiation, and "chain of lamps" alluding to the application of the chain rule by torch.autograd, the concatenation of spatial coordinate transformations, and furthermore the (sequential) composition of PyTorch modules. In addition, the English words "deep" and "ali(-gnment)" partially contained in this name should highlight that this project is not only suitable for traditional non-learning based registration, but in particular facilitates deep learning based approaches to image alignment.
At a granular level, deepali is a library that consists of the following components:
Component | Description |
---|---|
deepali.core | Common types, coordinate spaces, and tensor functions. |
deepali.data | PyTorch tensor subclasses, data loader utilities, and datasets. |
deepali.losses | Loss terms and evaluation metrics for image, point set, and surface registration. |
deepali.modules | PyTorch modules without optimizable parameters built on core functions. |
deepali.networks | Common building blocks of machine learning based registration models. We expect that most users may want to develop their own task-specific models. For this, the neural network components defined here may be used alongside torch.nn and other deep learning libraries (e.g. MONAI) to define these custom models. |
deepali.spatial | Spatial transformation models whose parameters are either optimized directly as in traditional registration, or inferred by a machine learning model. |
deepali.utils | Optional auxiliaries for interfacing with external libraries and tools. |
The following lists the main dependencies of this project. For a complete list, please open file setup.py.
This library is available as Python package on PyPI and can be installed with pip:
pip install hf-deepali
The latest development version can be installed directly from the GitHub repository, i.e.,
pip install git+https://github.com/BioMedIA/deepali.git
Alternatively, it can be installed from a previously cloned local Git repository using
git clone https://github.com/BioMedIA/deepali.git && pip install ./deepali
This will install missing dependencies in the current Python environment from PyPI. To use conda for installing the required dependencies (recommended), create a conda environment with pre-installed dependencies before running pip install
. For further information on how to create and manage project dependencies using conda, see conda/README.md.
Additional optional dependencies of the deepali.utils library can be installed with the command:
pip install hf-deepali[utils]
# or pip install git+https://github.com/BioMedIA/deepali.git#egg=deepali[utils]
Schuh, A., Qiu, H., and HeartFlow Research. deepali: Image, point set, and surface registration in PyTorch (2023). doi:10.5281/zenodo.8170161
We appreciate all contributions. If you are planning to contribute bug-fixes, please do so without any further discussion. If you plan to contribute new features, utility functions or extensions, we would appreciate if you first open an issue and discuss the feature with us. Please also read the CONTRIBUTING notes. The participation in this open source project is subject to the Code of Conduct.
By submitting a pull request to this project, you agree to license your contribution under the Apache license version 2.0 to this project.
Contributors to this project may want to install this package in development mode using
git clone https://github.com/BioMedIA/deepali.git
make -C deepali/conda env EDITABLE=1
conda activate deepali
This will link the source tree of the package in the Python environment.
Below we list a few projects which are either similar to deepali or complement its functionality. We encourage everyone interested in image registration to also explore these projects. You may especially be interested in combining the more general functionality available in MONAI with registration components provided by deepali.