# deepali
[](https://doi.org/10.5281/zenodo.8170161) [](https://pypi.org/project/hf-deepali/) [](https://pypistats.org/packages/hf-deepali) [](https://github.com/BioMedIA/deepali/actions/workflows/docs.yml) [](https://github.com/BioMedIA/deepali/actions/workflows/tests.yml) [](https://github.com/BioMedIA/deepali/actions/workflows/release.yml)
An [open source](https://github.com/BioMedIA/deepali/tree/main/LICENSE) 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](https://en.wikipedia.org/wiki/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.
[HeartFlow-Imperial College London]: https://www.heartflow.com/newsroom/heartflow-announces-collaborative-research-agreement-with-imperial-college-london/
[Biomedical Image Analysis Group]: https://biomedia.doc.ic.ac.uk/
## Overview
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. |
[deepali.core]: https://biomedia.github.io/deepali/reference/core/index.html
[deepali.data]: https://biomedia.github.io/deepali/reference/data/index.html
[deepali.losses]: https://biomedia.github.io/deepali/reference/losses/index.html
[deepali.modules]: https://biomedia.github.io/deepali/reference/modules/index.html
[deepali.networks]: https://biomedia.github.io/deepali/reference/networks/index.html
[deepali.spatial]: https://biomedia.github.io/deepali/reference/spatial/index.html
[deepali.utils]: https://biomedia.github.io/deepali/reference/utils/index.html
## Dependencies
The following lists the main dependencies of this project. For a complete list, please open file [setup.py](setup.py).
- [PyTorch]: The automatic differentiation and deep learning framework powering this project.
- [SimpleITK] (optional): Used by [deepali.data] to read and write images in file formats supported by ITK.
- [nibabel] (optional): Used by [deepali.data] to read and write images in NIfTI file formats if available.
- [NumPy] (optional): Used by [deepali.utils]. Other components use pure PyTorch.
- [VTK] (optional): May be used to read and write point sets and surface meshes.
## Installation
This library is available as [Python package on PyPI](https://pypi.org/project/hf-deepali/) 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](https://github.com/BioMedIA/deepali/tree/main/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]
```
[conda]: https://docs.conda.io/en/latest/
[pip]: https://pip.pypa.io/en/stable/
[PyPI]: https://pypi.org/
[Miniconda]: https://docs.conda.io/en/latest/miniconda.html
## Citation
Schuh, A., Qiu, H., and HeartFlow Research. *deepali: Image, point set, and surface registration in PyTorch* (2023). [doi:10.5281/zenodo.8170161](https://doi.org/10.5281/zenodo.8170161)
## Contributing
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](https://github.com/BioMedIA/deepali/tree/main/CONTRIBUTING.md) notes. The participation in this open source project is subject to the [Code of Conduct](https://github.com/BioMedIA/deepali/tree/main/CODE_OF_CONDUCT.md).
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.
## Related projects
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*.
- **[AIRLab]**: A non-learning based medical image registration framework that took advantage of [PyTorch]'s automatic differentiation and optimizers.
- **[DeepReg]**: A recent and actively developed framework for deep learning based medical image registration built on [TensorFlow]. 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]**: This [PyTorch] based 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 of [Large Deformation Metric Mapping] for [Computational Anatomy].
- **[MONAI]**: This excellent framework for deep learning in healthcare imaging is well maintained and part of the [PyTorch 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 in [TensorFlow]. Parts of it have been used in [VoxelMorph], 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 with *deepali*. Some low-level functionality for applying spatial transformations has more recently been contributed to MONAI as well.
- **[TorchIO]**: A library in the [PyTorch Ecosystem] for efficient loading, preprocessing, augmentation, and patch-based sampling of 3D medical images.
[AIRLab]: https://github.com/airlab-unibas/airlab
[DeepReg]: https://github.com/DeepRegNet/DeepReg
[Mermaid]: https://github.com/uncbiag/mermaid
[MONAI]: https://github.com/Project-MONAI/MONAI
[Neurite]: https://github.com/adalca/neurite
[nibabel]: https://nipy.org/nibabel/
[NITorch]: https://github.com/balbasty/nitorch
[NumPy]: https://numpy.org/
[PyTorch]: https://pytorch.org/
[PyTorch Ecosystem]: https://pytorch.org/ecosystem/
[SimpleITK]: https://simpleitk.org/
[TensorFlow]: https://www.tensorflow.org/
[TorchIO]: https://torchio.readthedocs.io/
[VoxelMorph]: https://github.com/voxelmorph/voxelmorph
[VTK]: https://vtk.org/
[Computational Anatomy]: https://en.wikipedia.org/wiki/Computational_anatomy
[Large Deformation Metric Mapping]: https://en.wikipedia.org/wiki/Large_deformation_diffeomorphic_metric_mapping
Raw data
{
"_id": null,
"home_page": "",
"name": "hf-deepali",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Andreas Schuh <andreas.schuh@imperial.ac.uk>",
"keywords": "medical-imaging,image-registration,spatial-transformer-networks",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/53/cf/1ae254f2be0371cd767c5a1f6212938911cd53dbebfcd3b2ae49207ab8c2/hf-deepali-0.6.2.tar.gz",
"platform": null,
"description": "# deepali\n\n[](https://doi.org/10.5281/zenodo.8170161) [](https://pypi.org/project/hf-deepali/) [](https://pypistats.org/packages/hf-deepali) [](https://github.com/BioMedIA/deepali/actions/workflows/docs.yml) [](https://github.com/BioMedIA/deepali/actions/workflows/tests.yml) [](https://github.com/BioMedIA/deepali/actions/workflows/release.yml)\n\nAn [open source](https://github.com/BioMedIA/deepali/tree/main/LICENSE) 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].\n\n*[Deepali](https://en.wikipedia.org/wiki/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.\n\n[HeartFlow-Imperial College London]: https://www.heartflow.com/newsroom/heartflow-announces-collaborative-research-agreement-with-imperial-college-london/\n[Biomedical Image Analysis Group]: https://biomedia.doc.ic.ac.uk/\n\n\n## Overview\n\nAt a granular level, *deepali* is a library that consists of the following components:\n\n| **Component** | **Description** |\n| -------------- | --------------- |\n| [deepali.core] | Common types, coordinate spaces, and tensor functions. |\n| [deepali.data] | PyTorch tensor subclasses, data loader utilities, and datasets. |\n| [deepali.losses] | Loss terms and evaluation metrics for image, point set, and surface registration. |\n| [deepali.modules] | PyTorch modules without optimizable parameters built on core functions. |\n| [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. |\n| [deepali.spatial] | Spatial transformation models whose parameters are either optimized directly as in traditional registration, or inferred by a machine learning model. |\n| [deepali.utils] | Optional auxiliaries for interfacing with external libraries and tools. |\n\n\n[deepali.core]: https://biomedia.github.io/deepali/reference/core/index.html\n[deepali.data]: https://biomedia.github.io/deepali/reference/data/index.html\n[deepali.losses]: https://biomedia.github.io/deepali/reference/losses/index.html\n[deepali.modules]: https://biomedia.github.io/deepali/reference/modules/index.html\n[deepali.networks]: https://biomedia.github.io/deepali/reference/networks/index.html\n[deepali.spatial]: https://biomedia.github.io/deepali/reference/spatial/index.html\n[deepali.utils]: https://biomedia.github.io/deepali/reference/utils/index.html\n\n\n## Dependencies\n\nThe following lists the main dependencies of this project. For a complete list, please open file [setup.py](setup.py).\n\n- [PyTorch]: The automatic differentiation and deep learning framework powering this project.\n- [SimpleITK] (optional): Used by [deepali.data] to read and write images in file formats supported by ITK.\n- [nibabel] (optional): Used by [deepali.data] to read and write images in NIfTI file formats if available.\n- [NumPy] (optional): Used by [deepali.utils]. Other components use pure PyTorch.\n- [VTK] (optional): May be used to read and write point sets and surface meshes.\n\n## Installation\n\nThis library is available as [Python package on PyPI](https://pypi.org/project/hf-deepali/) and can be installed with [pip]:\n\n```\npip install hf-deepali\n```\n\nThe latest development version can be installed directly from the GitHub repository, i.e.,\n\n```\npip install git+https://github.com/BioMedIA/deepali.git\n```\n\nAlternatively, it can be installed from a previously cloned local Git repository using\n\n```\ngit clone https://github.com/BioMedIA/deepali.git && pip install ./deepali\n```\n\nThis 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](https://github.com/BioMedIA/deepali/tree/main/conda/README.md).\n\nAdditional optional dependencies of the [deepali.utils] library can be installed with the command:\n\n```\npip install hf-deepali[utils]\n# or pip install git+https://github.com/BioMedIA/deepali.git#egg=deepali[utils]\n```\n\n\n[conda]: https://docs.conda.io/en/latest/\n[pip]: https://pip.pypa.io/en/stable/\n[PyPI]: https://pypi.org/\n[Miniconda]: https://docs.conda.io/en/latest/miniconda.html\n\n## Citation\n\nSchuh, A., Qiu, H., and HeartFlow Research. *deepali: Image, point set, and surface registration in PyTorch* (2023). [doi:10.5281/zenodo.8170161](https://doi.org/10.5281/zenodo.8170161)\n\n## Contributing\n\nWe 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](https://github.com/BioMedIA/deepali/tree/main/CONTRIBUTING.md) notes. The participation in this open source project is subject to the [Code of Conduct](https://github.com/BioMedIA/deepali/tree/main/CODE_OF_CONDUCT.md).\n\nBy submitting a pull request to this project, you agree to license your contribution under the Apache license version 2.0 to this project.\n\nContributors to this project may want to install this package in development mode using\n\n```\ngit clone https://github.com/BioMedIA/deepali.git\nmake -C deepali/conda env EDITABLE=1\nconda activate deepali\n```\n\nThis will link the source tree of the package in the Python environment.\n\n## Related projects\n\nBelow 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*.\n\n- **[AIRLab]**: A non-learning based medical image registration framework that took advantage of [PyTorch]'s automatic differentiation and optimizers.\n- **[DeepReg]**: A recent and actively developed framework for deep learning based medical image registration built on [TensorFlow]. 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.\n- **[Mermaid]**: This [PyTorch] based 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 of [Large Deformation Metric Mapping] for [Computational Anatomy].\n- **[MONAI]**: This excellent framework for deep learning in healthcare imaging is well maintained and part of the [PyTorch 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.\n- **[Neurite]**: A neural networks toolbox with a focus on medical image analysis in [TensorFlow]. Parts of it have been used in [VoxelMorph], for example.\n- **[NITorch]**: A library written by post-docs in John Ashburner's group which is conceptually related to SPM and has a great overlap with *deepali*. Some low-level functionality for applying spatial transformations has more recently been contributed to MONAI as well.\n- **[TorchIO]**: A library in the [PyTorch Ecosystem] for efficient loading, preprocessing, augmentation, and patch-based sampling of 3D medical images.\n\n\n[AIRLab]: https://github.com/airlab-unibas/airlab\n[DeepReg]: https://github.com/DeepRegNet/DeepReg\n[Mermaid]: https://github.com/uncbiag/mermaid\n[MONAI]: https://github.com/Project-MONAI/MONAI\n[Neurite]: https://github.com/adalca/neurite\n[nibabel]: https://nipy.org/nibabel/\n[NITorch]: https://github.com/balbasty/nitorch\n[NumPy]: https://numpy.org/\n[PyTorch]: https://pytorch.org/\n[PyTorch Ecosystem]: https://pytorch.org/ecosystem/\n[SimpleITK]: https://simpleitk.org/\n[TensorFlow]: https://www.tensorflow.org/\n[TorchIO]: https://torchio.readthedocs.io/\n[VoxelMorph]: https://github.com/voxelmorph/voxelmorph\n[VTK]: https://vtk.org/\n\n[Computational Anatomy]: https://en.wikipedia.org/wiki/Computational_anatomy\n[Large Deformation Metric Mapping]: https://en.wikipedia.org/wiki/Large_deformation_diffeomorphic_metric_mapping\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Image, point set, and surface registration library for PyTorch.",
"version": "0.6.2",
"project_urls": {
"Bug Tracker": "https://github.com/BioMedIA/deepali/issues",
"Homepage": "https://biomedia.github.io/deepali",
"Repository": "https://github.com/BioMedIA/deepali.git"
},
"split_keywords": [
"medical-imaging",
"image-registration",
"spatial-transformer-networks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15c87f20a1b4e2583df05da9e495a080221a157d2e9b372e6b2d8b9ed16b0091",
"md5": "42def5542496ea7ef769660f17aa1fb7",
"sha256": "4310714a6f67f4dd64fe8682cd3e0d23c6235f1068733e35f30c63c2e9f9f5d9"
},
"downloads": -1,
"filename": "hf_deepali-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42def5542496ea7ef769660f17aa1fb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 305555,
"upload_time": "2024-02-02T21:13:55",
"upload_time_iso_8601": "2024-02-02T21:13:55.838656Z",
"url": "https://files.pythonhosted.org/packages/15/c8/7f20a1b4e2583df05da9e495a080221a157d2e9b372e6b2d8b9ed16b0091/hf_deepali-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53cf1ae254f2be0371cd767c5a1f6212938911cd53dbebfcd3b2ae49207ab8c2",
"md5": "f6ad29ce5e3c2375e44d995b11035f0b",
"sha256": "a04130a8642722a5dfb1bda0d13f226c7688646fa837d4f4d25ef74dd57f5a1a"
},
"downloads": -1,
"filename": "hf-deepali-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "f6ad29ce5e3c2375e44d995b11035f0b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 814253,
"upload_time": "2024-02-02T21:13:57",
"upload_time_iso_8601": "2024-02-02T21:13:57.809486Z",
"url": "https://files.pythonhosted.org/packages/53/cf/1ae254f2be0371cd767c5a1f6212938911cd53dbebfcd3b2ae49207ab8c2/hf-deepali-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 21:13:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BioMedIA",
"github_project": "deepali",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hf-deepali"
}
JSON
