Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/masadcv/fastgeodis
Fast Implementation of Generalised Geodesic Distance Transform for CPU (OpenMP) and GPU (CUDA)
https://github.com/masadcv/fastgeodis
deep-learning gpu pytorch
Last synced: 1 day ago
JSON representation
Fast Implementation of Generalised Geodesic Distance Transform for CPU (OpenMP) and GPU (CUDA)
- Host: GitHub
- URL: https://github.com/masadcv/fastgeodis
- Owner: masadcv
- License: bsd-3-clause
- Created: 2021-06-10T00:43:15.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-02-09T21:59:39.000Z (9 months ago)
- Last Synced: 2024-09-06T12:16:27.530Z (2 months ago)
- Topics: deep-learning, gpu, pytorch
- Language: C++
- Homepage: https://fastgeodis.readthedocs.io
- Size: 25.6 MB
- Stars: 90
- Watchers: 3
- Forks: 14
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# FastGeodis: Fast Generalised Geodesic Distance Transform
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://pepy.tech/project/fastgeodis)
[](https://joss.theoj.org/papers/d0b6e3daa4b22fec471691c6f1c60e2a)
[](https://github.com/masadcv/FastGeodis/actions/workflows/build.yml)
[](https://badge.fury.io/py/FastGeodis)
This repository provides CPU (OpenMP) and GPU (CUDA) implementations of Generalised Geodesic Distance Transform in PyTorch for 2D and 3D input data based on parallelisable raster scan ideas from [1]. It includes methods for computing Geodesic, Euclidean distance transform and mixture of both.
| 2D images, 1 of 4 passes | 3D volumes, 1 of 6 passes |
|-------------------|-------------------------|
| 
| 
|
The above raster scan method can be parallelised for each row/plane on an available device (CPU or GPU). This leads to significant speed up as compared to existing non-parallelised raster scan implementations (e.g. [https://github.com/taigw/GeodisTK](https://github.com/taigw/GeodisTK)). Python interface is provided (using PyTorch) for enabling its use in deep learning and image processing pipelines.
In addition, implementation of generalised version of Geodesic distance transforms along with Geodesic Symmetric Filtering (GSF) is provided for use in interactive segmentation methods, that were originally proposed in [1, 2, 5].
> The raster scan based implementation provides a balance towards speed rather than accuracy of Geodesic distance transform and hence results in efficient hardware utilisation. On the other hand, in case of Euclidean distance transform, exact results can be achieved with other packages (albeit not on necessarilly on GPU) [6, 7, 8]
# Citation
If you use this code in your research, then please consider citing:
[](https://joss.theoj.org/papers/d0b6e3daa4b22fec471691c6f1c60e2a)
***Asad, Muhammad, Reuben Dorent, and Tom Vercauteren. "FastGeodis: Fast Generalised Geodesic Distance Transform." Journal of Open Source Software (JOSS), 2022.*** ([paper link](https://doi.org/10.21105/joss.04532))
Bibtex:
```
@article{asad2022fastgeodis,
doi = {10.21105/joss.04532},
url = {https://doi.org/10.21105/joss.04532},
year = {2022},
publisher = {The Open Journal},
volume = {7},
number = {79},
pages = {4532},
author = {Muhammad Asad and Reuben Dorent and Tom Vercauteren},
title = {FastGeodis: Fast Generalised Geodesic Distance Transform},
journal = {Journal of Open Source Software}
}
```
# Installation instructions
The provided package can be installed using:
`pip install FastGeodis`
or
`pip install git+https://github.com/masadcv/FastGeodis`
or (on conda environments with existing installation of PyTorch with CUDA)
`pip install FastGeodis --no-build-isolation`
# Included methods
## Optimised Fast Implementations for GPU/CPU based on [1]
| Method | Description | Documentation |
|--------|-------------|---------------|
| Fast Generalised Geodesic Distance 2D | Paralellised generalised geodesic distance transform for CPU/GPU [1] | [FastGeodis.generalised_geodesic2d](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.generalised_geodesic2d) |
| Fast Generalised Geodesic Distance 3D | Paralellised generalised geodesic distance transform for CPU/GPU [1] | [FastGeodis.generalised_geodesic3d](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.generalised_geodesic3d) |
| Fast Signed Generalised Geodesic Distance 2D | Paralellised signed generalised geodesic distance transform for CPU/GPU [1] | [FastGeodis.signed_generalised_geodesic2d](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_generalised_geodesic2d) |
| Fast Signed Generalised Geodesic Distance 3D | Paralellised signed generalised geodesic distance transform for CPU/GPU [1] | [FastGeodis.signed_generalised_geodesic3d](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_generalised_geodesic3d) |
| Fast Geodesic Symmetric Filtering 2D | Paralellised geodesic symmetric filtering for CPU/GPU [2] | [FastGeodis.GSF2d](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF2d) |
| Fast Geodesic Symmetric Filtering 3D | Paralellised geodesic symmetric filtering for CPU/GPU [2] | [FastGeodis.GSF3d](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF3d) |
----
## Toivanen's Implementations for CPU based on [9]
| Method | Description | Documentation |
|--------|-------------|---------------|
| Toivanen's Generalised Geodesic Distance 2D | Toivanen's generalised geodesic distance transform for CPU [9] | [FastGeodis.generalised_geodesic2d_toivanen](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.generalised_geodesic2d_toivanen) |
| Toivanen's Generalised Geodesic Distance 3D | Toivanen's generalised geodesic distance transform for CPU [9] | [FastGeodis.generalised_geodesic3d_toivanen](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.generalised_geodesic3d_toivanen) |
| Toivanen's Signed Generalised Geodesic Distance 2D | Toivanen's signed generalised geodesic distance transform for CPU [9] | [FastGeodis.signed_generalised_geodesic2d_toivanen](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_generalised_geodesic2d_toivanen) |
| Toivanen's Signed Generalised Geodesic Distance 3D | Toivanen's signed generalised geodesic distance transform for CPU [9] | [FastGeodis.signed_generalised_geodesic3d_toivanen](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_generalised_geodesic3d_toivanen) |
| Toivanen's Geodesic Symmetric Filtering 2D | Toivanen's geodesic symmetric filtering for CPU [2, 9] | [FastGeodis.GSF2d_toivanen](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF2d_toivanen) |
| Toivanen's Geodesic Symmetric Filtering 3D | Toivanen's geodesic symmetric filtering for CPU [2, 9] | [FastGeodis.GSF3d_toivanen](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF3d_toivanen) |
## Pixel Queue Implementations for CPU based on [11]
| Method | Description | Documentation |
|--------|-------------|---------------|
| Pixel Queue Geodesic Distance 2D | Pixel Queue geodesic distance transform for CPU [11] | [FastGeodis.geodesic2d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.geodesic2d_pixelqueue) |
| Pixel Queue Geodesic Distance 3D | Pixel Queue geodesic distance transform for CPU [11] | [FastGeodis.geodesic3d_pixelqueue](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.geodesic3d_pixelqueue) |
| Pixel Queue Signed Geodesic Distance 2D | Pixel Queue signed geodesic distance transform for CPU [11] | [FastGeodis.signed_geodesic2d_pixelqueue](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_geodesic2d_pixelqueue) |
| Pixel Queue Signed Geodesic Distance 3D | Pixel Queue signed geodesic distance transform for CPU [11] | [FastGeodis.signed_geodesic3d_pixelqueue](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_geodesic3d_pixelqueue) |
| Pixel Queue Geodesic Symmetric Filtering 2D | Pixel Queue geodesic symmetric filtering for CPU [2, 11] | [FastGeodis.GSF2d_pixelqueue](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF2d_pixelqueue) |
| Pixel Queue Geodesic Symmetric Filtering 3D | Pixel Queue geodesic symmetric filtering for CPU [2, 11] | [FastGeodis.GSF3d_pixelqueue](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF3d_pixelqueue) |
## Fast Marching Implementations for CPU based on [4, 10]
| Method | Description | Documentation |
|--------|-------------|---------------|
| Fast Marching Geodesic Distance 2D | Fast Marching geodesic distance transform for CPU [9] | [FastGeodis.geodesic2d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.geodesic2d_fastmarch) |
| Fast Marching Geodesic Distance 3D | Fast Marching geodesic distance transform for CPU [9] | [FastGeodis.geodesic3d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.geodesic3d_fastmarch) |
| Fast Marching Signed Geodesic Distance 2D | Fast Marching signed geodesic distance transform for CPU [9] | [FastGeodis.signed_geodesic2d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_geodesic2d_fastmarch) |
| Fast Marching Signed Geodesic Distance 3D | Fast Marching signed geodesic distance transform for CPU [9] | [FastGeodis.signed_geodesic3d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.signed_geodesic3d_fastmarch) |
| Fast Marching Geodesic Symmetric Filtering 2D | Fast Marching geodesic symmetric filtering for CPU [2, 9] | [FastGeodis.GSF2d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF2d_fastmarch) |
| Fast Marching Geodesic Symmetric Filtering 3D | Fast Marching geodesic symmetric filtering for CPU [2, 9] | [FastGeodis.GSF3d_fastmarch](https://fastgeodis.readthedocs.io/en/latest/api_docs.html#FastGeodis.GSF3d_fastmarch) |
# Example usage
### Fast Geodesic Distance Transform
The following demonstrates a simple example showing FastGeodis usage:
To compute Geodesic Distance Transform:
```python
device = "cuda" if torch.cuda.is_available() else "cpu"
image = np.asarray(Image.open("data/img2d.png"), np.float32)
image_pt = torch.from_numpy(image).unsqueeze_(0).unsqueeze_(0)
image_pt = image_pt.to(device)
mask_pt = torch.ones_like(image_pt)
mask_pt[..., 100, 100] = 0
v = 1e10
# lamb = 0.0 (Euclidean) or 1.0 (Geodesic) or (0.0, 1.0) (mixture)
lamb = 1.0
iterations = 2
geodesic_dist = FastGeodis.generalised_geodesic2d(
image_pt, mask_pt, v, lamb, iterations
)
geodesic_dist = np.squeeze(geodesic_dist.cpu().numpy())
```
To compute Euclidean Distance Transform:
```python
device = "cuda" if torch.cuda.is_available() else "cpu"
image = np.asarray(Image.open("data/img2d.png"), np.float32)
image_pt = torch.from_numpy(image).unsqueeze_(0).unsqueeze_(0)
image_pt = image_pt.to(device)
mask_pt = torch.ones_like(image_pt)
mask_pt[..., 100, 100] = 0
v = 1e10
# lamb = 0.0 (Euclidean) or 1.0 (Geodesic) or (0.0, 1.0) (mixture)
lamb = 0.0
iterations = 2
euclidean_dist = FastGeodis.generalised_geodesic2d(
image_pt, mask_pt, v, lamb, iterations
)
euclidean_dist = np.squeeze(euclidean_dist.cpu().numpy())
```
For more usage examples see:
| Description | Python | Colab link |
|--------------|---------|--------------|
| **Simple 2D Geodesic and Euclidean Distance** | [`samples/simpledemo2d.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/simpledemo2d.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/simpledemo2d.ipynb) |
| **Simple Signed 2D Geodesic and Euclidean Distance** | [`samples/simpledemo2d_signed.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/simpledemo2d_signed.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/simpledemo2d_signed.ipynb) |
| **Simple 3D Geodesic and Euclidean Distance** | [`samples/simpledemo3d.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/simpledemo3d.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/simpledemo3d.ipynb) |
| **Simple Signed 3D Geodesic and Euclidean Distance** | [`samples/simpledemo3d_signed.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/simpledemo3d_signed.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/simpledemo3d_signed.ipynb) |
| **2D Geodesic Distance** | [`samples/demo2d.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/demo2d.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/demo2d.ipynb) |
| **2D Signed Geodesic Distance** | [`samples/demo2d_signed.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/demo2d_signed.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/demo2d_signed.ipynb) |
| **3D Geodesic Distance** | [`samples/demo3d.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/demo3d.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/demo3d.ipynb) |
| **3D Signed Geodesic Distance** | [`samples/demo3d_signed.py`](https://github.com/masadcv/FastGeodis/blob/master/samples/demo3d_signed.py) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/demo3d_signed.ipynb) |
| **2D GSF Segmentation Smoothing** | [`samples/demoGSF2d_SmoothingSegExample.ipynb`](https://github.com/masadcv/FastGeodis/blob/master/samples/demoGSF2d_SmoothingSegExample.ipynb) | [](https://colab.research.google.com/github/masadcv/FastGeodis/blob/master/samples/demoGSF2d_SmoothingSegExample.ipynb) |
# Unit Tests
A number of unittests are provided, which can be run as:
```
pip install -r requirements-dev.txt
python -m unittest
```
# Documentation
Further details of each function implemented in FastGeodis can be accessed at the documentation hosted at: [https://fastgeodis.readthedocs.io](https://fastgeodis.readthedocs.io).
# Contributing to FastGeodis
Spotted a bug or have a feature request to improve the package? We would love to have your input! See our [guidelines for contributing](https://fastgeodis.readthedocs.io/en/latest/contributing.html).
# Comparison of Execution Time and Accuracy
FastGeodis (CPU/GPU) is compared with existing GeodisTK ([https://github.com/taigw/GeodisTK](https://github.com/taigw/GeodisTK)) in terms of execution speed as well as accuracy.
### Execution Time
| 2D images | 3D volumes |
|-------------------|-------------------------|
|
|
|
### Accuracy
2D case
| Qualitative Comparison | Quantitative (joint histogram) |
|-------------------|-------------------------|
|
|
|
3D case
| Qualitative Comparison | Quantitative (joint histogram) |
|-------------------|-------------------------|
| 
| 
|
## References
- [1] Criminisi, Antonio, Toby Sharp, and Khan Siddiqui. "Interactive Geodesic Segmentation of n-Dimensional Medical Images on the Graphics Processor." Radiological Society of North America (RSNA), 2009. [[pdf](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/Criminisi_RSNA09_extendedAbstract1.pdf), [ppt](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/RSNA2009_Segmentation_Criminisi.ppt), [url](https://www.microsoft.com/en-us/research/publication/interactive-geodesic-segmentation-of-n-dimensional-medical-images-on-the-graphics-processor/)]
- [2] Criminisi, Antonio, Toby Sharp, and Andrew Blake. "Geos: Geodesic image segmentation." European Conference on Computer Vision. Springer, Berlin, Heidelberg, 2008. [[doi](https://doi.org/10.1007/978-3-540-88682-2_9)]
- [3] Weber, Ofir, et al. "Parallel algorithms for approximation of distance maps on parametric surfaces." ACM Transactions on Graphics (TOG), (2008). [[doi](https://doi.org/10.1145/1409625.1409626)]
- [4] GeodisTK: [https://github.com/taigw/GeodisTK](https://github.com/taigw/GeodisTK)
- [5] Criminisi, Antonio, Toby Sharp, Carsten Rother, and Patrick Pérez. "Geodesic image and video editing." ACM Trans. Graph. 29, no. 5 (2010): 134-1. [[doi](https://doi.org/10.1145/1857907.1857910)]
- [6] [https://github.com/seung-lab/euclidean-distance-transform-3d](https://github.com/seung-lab/euclidean-distance-transform-3d)
- [7] [https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.distance_transform_edt.html](https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.distance_transform_edt.html)
- [8] [https://www.tensorflow.org/addons/api_docs/python/tfa/image/euclidean_dist_transform](https://www.tensorflow.org/addons/api_docs/python/tfa/image/euclidean_dist_transform)
- [9] Toivanen, Pekka J. "New geodosic distance transforms for gray-scale images." Pattern Recognition Letters 17.5 (1996): 437-450.
- [10] Sethian, James A. "Fast marching methods." SIAM review 41.2 (1999): 199-235.
- [11] Ikonen, L., & Toivanen, P. (2007). Distance and nearest neighbor transforms on gray-level surfaces. Pattern Recognition Letters, 28(5), 604-612. [[doi](https://doi.org/10.1016/j.patrec.2006.10.010)]