<img src='docs/_static/imgs/example.png' width="1000px"/>
# Digital Diffeomorphism: Non-diffeomorphic volume and Non-diffeomorphic area
This is an implementation of the **non-diffeomorphic volume** and
**non-diffeomorphic area** computation we introduced in our paper:
<a href="https://arxiv.org/abs/2212.06060">Liu, Yihao, et al. "On Finite Difference Jacobian Computation in Deformable Image Registration." arXiv preprint arXiv:2212.06060 (2022).</a>
## Motivation
The Jacobian determinant $|J|$ of spatial transformations is a widely used measure in
deformable image registration, but the details of its computation are often overlooked.
Contrary to what one might expect, when approximated using the central difference,
the number of pixels/voxels with negative $|J|$ does not reflect if the transformation is diffeomorphic or not.
<p align="center">
<img src='docs/_static/imgs/checkerboard_problem.png' align="center" width="200px"/>
</p>
The example above demonstrate a failure case of the central difference based $|J|$.
The center pixel has central difference based $|J|=1$ but it is not diffeomorphic.
In fact, the transformation at the center pixel has no effect on the computation of central
difference based $|J|$, even if it moves outside the field of view.
We proposed the definition of digital diffeomorphism that solves several errors that inherent in
the central difference based $|J|$. We further propose to use non-diffeomorphic
volume (NDV) and non-diffeomorphic area (NDA) to measure the irregularity of 3D/2D transformations.
The proposed NDV and NDA also measures the **severity** of the irregularity whereas the central difference approximated $|J|$
is only a binary indicator.
<p align="center">
<img src='docs/_static/imgs/nda_demonstration.png' align="center" width="600px"/>
</p>
The center pixel in all three cases shown above would be considered diffeomorphic
because of the checkerboard problem. The forward difference based $|J|$ is able to identiy that
(b) and (c) exhibit folding, but only NDA can provide the observation that the non-diffeomorphic space
caused by the transformation shown in (c) is larger than (b).
The transformation shown in (b) is obviously more favorable than the one shown in (c)
in terms of regularity. As such it is important for us to be able to draw distinctions between
there two senarios.
## Getting Started
### Installation
The easiest way to install the package is through the following command:
```
pip install digital-diffeomorphism
```
To install from the source:
```bash
git clone https://github.com/yihao6/digital_diffeomorphism.git
cd digital_diffeomorphism
python setup.py install
```
### Usage
To evaluate a 3D sampling grid with dimension $H\times W\times D\times 3$
```bash
ndv grid_3d.nii.gz
```
This will calculate
1. non-diffeomorphic volume; and
2. non-diffeomorphic voxels computed by the central difference.
If the transformation is stored as a displacement field:
```bash
ndv disp_3d.nii.gz --disp
```
To evaluate a 2D sampling grid with dimension $H\times W\times 2$
```bash
nda grid_2d.nii.gz
```
This will calculate
1. non-diffeomorphic area; and
2. non-diffeomorphic pixels computed by the central difference.
If the transformation is stored as a displacement field:
```bash
ndv disp_2d.nii.gz --disp
```
Example inputs can be found at https://iacl.ece.jhu.edu/index.php?title=Digital_diffeomorphism
### Potential Pitfalls
1. Several packages implement spatial transformations using a normalized sampling grid.
For example, <a href="https://arxiv.org/abs/2212.06060">torch.nn.functional.grid_sample</a>.
In this package, we use un-normalized coordinates to represent transformations.
Therefore, the input sampling grid or displacement field should be in voxel or pixel units.
In case the input is normalized, it must be unnormalized prior to using this package.
### Citation
If you use this code, please cite our paper.
```
@article{liu2022finite,
title={On Finite Difference Jacobian Computation in Deformable Image Registration},
author={Liu, Yihao and Chen, Junyu and Wei, Shuwen and Carass, Aaron and Prince, Jerry},
journal={arXiv preprint arXiv:2212.06060},
year={2022}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/yihao6/digital_diffeomorphism",
"name": "digital-diffeomorphism",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "registration,medical images,digital diffeomorphism",
"author": "Yihao Liu",
"author_email": "yliu236@jhu.edu",
"download_url": "https://files.pythonhosted.org/packages/83/e8/74d5eb66b5ad4746e0b816143ca13294183c873ecc14676f4b0b956f165c/digital_diffeomorphism-1.0.1.tar.gz",
"platform": null,
"description": "<img src='docs/_static/imgs/example.png' width=\"1000px\"/>\n\n# Digital Diffeomorphism: Non-diffeomorphic volume and Non-diffeomorphic area\nThis is an implementation of the **non-diffeomorphic volume** and\n**non-diffeomorphic area** computation we introduced in our paper:\n\n<a href=\"https://arxiv.org/abs/2212.06060\">Liu, Yihao, et al. \"On Finite Difference Jacobian Computation in Deformable Image Registration.\" arXiv preprint arXiv:2212.06060 (2022).</a>\n\n## Motivation\nThe Jacobian determinant $|J|$ of spatial transformations is a widely used measure in\ndeformable image registration, but the details of its computation are often overlooked.\nContrary to what one might expect, when approximated using the central difference,\nthe number of pixels/voxels with negative $|J|$ does not reflect if the transformation is diffeomorphic or not.\n<p align=\"center\">\n <img src='docs/_static/imgs/checkerboard_problem.png' align=\"center\" width=\"200px\"/>\n</p>\nThe example above demonstrate a failure case of the central difference based $|J|$.\nThe center pixel has central difference based $|J|=1$ but it is not diffeomorphic.\nIn fact, the transformation at the center pixel has no effect on the computation of central\ndifference based $|J|$, even if it moves outside the field of view.\n\nWe proposed the definition of digital diffeomorphism that solves several errors that inherent in\nthe central difference based $|J|$. We further propose to use non-diffeomorphic\nvolume (NDV) and non-diffeomorphic area (NDA) to measure the irregularity of 3D/2D transformations.\nThe proposed NDV and NDA also measures the **severity** of the irregularity whereas the central difference approximated $|J|$\nis only a binary indicator.\n<p align=\"center\">\n <img src='docs/_static/imgs/nda_demonstration.png' align=\"center\" width=\"600px\"/>\n</p>\nThe center pixel in all three cases shown above would be considered diffeomorphic\nbecause of the checkerboard problem. The forward difference based $|J|$ is able to identiy that\n(b) and (c) exhibit folding, but only NDA can provide the observation that the non-diffeomorphic space\ncaused by the transformation shown in (c) is larger than (b).\nThe transformation shown in (b) is obviously more favorable than the one shown in (c)\nin terms of regularity. As such it is important for us to be able to draw distinctions between\nthere two senarios.\n\n## Getting Started\n\n### Installation\nThe easiest way to install the package is through the following command:\n```\npip install digital-diffeomorphism\n```\n\nTo install from the source:\n```bash\ngit clone https://github.com/yihao6/digital_diffeomorphism.git\n\ncd digital_diffeomorphism\n\npython setup.py install\n```\n\n### Usage\nTo evaluate a 3D sampling grid with dimension $H\\times W\\times D\\times 3$\n```bash\nndv grid_3d.nii.gz\n```\nThis will calculate\n1. non-diffeomorphic volume; and\n2. non-diffeomorphic voxels computed by the central difference.\n\nIf the transformation is stored as a displacement field:\n```bash\nndv disp_3d.nii.gz --disp\n```\n\nTo evaluate a 2D sampling grid with dimension $H\\times W\\times 2$\n```bash\nnda grid_2d.nii.gz\n```\nThis will calculate\n1. non-diffeomorphic area; and\n2. non-diffeomorphic pixels computed by the central difference.\n\nIf the transformation is stored as a displacement field:\n```bash\nndv disp_2d.nii.gz --disp\n```\n\nExample inputs can be found at https://iacl.ece.jhu.edu/index.php?title=Digital_diffeomorphism\n\n### Potential Pitfalls\n1. Several packages implement spatial transformations using a normalized sampling grid.\nFor example, <a href=\"https://arxiv.org/abs/2212.06060\">torch.nn.functional.grid_sample</a>.\nIn this package, we use un-normalized coordinates to represent transformations.\nTherefore, the input sampling grid or displacement field should be in voxel or pixel units.\nIn case the input is normalized, it must be unnormalized prior to using this package.\n\n### Citation\nIf you use this code, please cite our paper.\n```\n@article{liu2022finite,\n title={On Finite Difference Jacobian Computation in Deformable Image Registration},\n author={Liu, Yihao and Chen, Junyu and Wei, Shuwen and Carass, Aaron and Prince, Jerry},\n journal={arXiv preprint arXiv:2212.06060},\n year={2022}\n}\n```\n",
"bugtrack_url": null,
"license": "GNU General Public License v3",
"summary": "Digital diffeomorphism: Non-diffeomorphic volume and non-diffeomorphic area computation",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/yihao6/digital_diffeomorphism/issues",
"Homepage": "https://github.com/yihao6/digital_diffeomorphism"
},
"split_keywords": [
"registration",
"medical images",
"digital diffeomorphism"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86a021216fed37f9fbb93ea724ee8ccd59d2b0b00642b80637ba4e45366bdc10",
"md5": "62339cd035bb808e0a228351a4ac1ff2",
"sha256": "3034be0034ef939bb0296bdfe70f2003b8cdb44ad3ded833471c6363992b46be"
},
"downloads": -1,
"filename": "digital_diffeomorphism-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62339cd035bb808e0a228351a4ac1ff2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10423,
"upload_time": "2023-11-27T19:54:48",
"upload_time_iso_8601": "2023-11-27T19:54:48.594542Z",
"url": "https://files.pythonhosted.org/packages/86/a0/21216fed37f9fbb93ea724ee8ccd59d2b0b00642b80637ba4e45366bdc10/digital_diffeomorphism-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "83e874d5eb66b5ad4746e0b816143ca13294183c873ecc14676f4b0b956f165c",
"md5": "6d445d0adeacbaf40dcd933fe80462d3",
"sha256": "1c962235326196959a222696984585dfe8ffe2fc621a087fb3a8ccb24edb5b02"
},
"downloads": -1,
"filename": "digital_diffeomorphism-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6d445d0adeacbaf40dcd933fe80462d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11083,
"upload_time": "2023-11-27T19:54:50",
"upload_time_iso_8601": "2023-11-27T19:54:50.413548Z",
"url": "https://files.pythonhosted.org/packages/83/e8/74d5eb66b5ad4746e0b816143ca13294183c873ecc14676f4b0b956f165c/digital_diffeomorphism-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-27 19:54:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yihao6",
"github_project": "digital_diffeomorphism",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "nibabel",
"specs": [
[
"==",
"4.0.2"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.23.4"
]
]
},
{
"name": "torch",
"specs": [
[
">=",
"1.8"
]
]
}
],
"lcname": "digital-diffeomorphism"
}
JSON
