Package: hf-deepali
deepaliAnopen sourceresearch library for image, point set, and surface registration inPyTorch, which is developed and maintained by theHeartFlow-Imperial College Londonresearch lab at theBiomedical Image Analysis Group.Deepaliis 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 bytorch.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.OverviewAt a granular level,deepaliis a library that consists of the following components:ComponentDescriptiondeepali.coreCommon types, coordinate spaces, and tensor functions.deepali.dataPyTorch tensor subclasses, data loader utilities, and datasets.deepali.lossesLoss terms and evaluation metrics for image, point set, and surface registration.deepali.modulesPyTorch modules without optimizable parameters built on core functions.deepali.networksCommon 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 alongsidetorch.nnand other deep learning libraries (e.g.MONAI) to define these custom models.deepali.spatialSpatial transformation models whose parameters are either optimized directly as in traditional registration, or inferred by a machine learning model.deepali.utilsOptional auxiliaries for interfacing with external libraries and tools.DependenciesThe following lists the main dependencies of this project. For a complete list, please open filesetup.py.PyTorch: The automatic differentiation and deep learning framework powering this project.SimpleITK(optional): Used bydeepali.datato read and write images in file formats supported by ITK.nibabel(optional): Used bydeepali.datato read and write images in NIfTI file formats if available.NumPy(optional): Used bydeepali.utils. Other components use pure PyTorch.VTK(optional): May be used to read and write point sets and surface meshes.InstallationThis library is available asPython package on PyPIand can be installed withpip:pip install hf-deepaliThe latest development version can be installed directly from the GitHub repository, i.e.,pip install git+https://github.com/BioMedIA/deepali.gitAlternatively, it can be installed from a previously cloned local Git repository usinggit clone https://github.com/BioMedIA/deepali.git && pip install ./deepaliThis will install missing dependencies in the current Python environment fromPyPI. To usecondafor installing the required dependencies (recommended), create a conda environment with pre-installed dependenciesbeforerunningpip install. For further information on how to create and manage project dependencies using conda, seeconda/README.md.Additional optional dependencies of thedeepali.utilslibrary can be installed with the command:pip install hf-deepali[utils]
# or pip install git+https://github.com/BioMedIA/deepali.git#egg=deepali[utils]CitationSchuh, A., Qiu, H., and HeartFlow Research.deepali: Image, point set, and surface registration in PyTorch(2023).doi:10.5281/zenodo.8170161ContributingWe 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 theCONTRIBUTINGnotes. The participation in this open source project is subject to theCode 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 usinggit clone https://github.com/BioMedIA/deepali.git
make -C deepali/conda env EDITABLE=1
conda activate deepaliThis will link the source tree of the package in the Python environment.Related projectsBelow we list a few projects which are either similar todeepalior 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 inMONAIwith registration components provided bydeepali.AIRLab: A non-learning based medical image registration framework that took advantage ofPyTorch's automatic differentiation and optimizers.DeepReg: A recent and actively developed framework for deep learning based medical image registration built onTensorFlow. Due to its YAML based configuration of different models and training settings within the scope of this framework, it should in particular attract users who are less interested in writing their own code, but train registration models provided by DeepReg on their data. As a community-supported open-source toolkit for research and education, you may also consider contributing your models to the framework. DeepReg also forms the basis for a benchmarking environment that will allow comparison of different deep learning models.Mermaid: ThisPyTorchbased toolkit facilitates both traditional and learning based registration with a particular focus on diffeomorphic transformation models based on either static or time-dependent velocity fields, including scalar and vector momentum fields. It should be especially of interested to those familiar with the mathematical framework ofLarge Deformation Metric MappingforComputational Anatomy.MONAI: This excellent framework for deep learning in healthcare imaging is well maintained and part of thePyTorch Ecosystem. It is not specific to medical image registration. In particular, MONAI omits spatial transformation models for use in a registration method, whether optimized directly or integrated in a deep learning model, but contains advanced modules for sampling an image at deformed spatial locations. Common spatial transformations used for data augmentation and general neural network architectures for various tasks are also available in this framework.Neurite: A neural networks toolbox with a focus on medical image analysis inTensorFlow. Parts of it have been used inVoxelMorph, for example.NITorch: A library written by post-docs in John Ashburner's group which is conceptually related to SPM and has a great overlap withdeepali. Some low-level functionality for applying spatial transformations has more recently been contributed to MONAI as well.TorchIO: A library in thePyTorch Ecosystemfor efficient loading, preprocessing, augmentation, and patch-based sampling of 3D medical images.