FastGeodis: Fast Generalised Geodesic Distance Transform

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 | |-------------------|-------------------------| | <img src="https://raw.githubusercontent.com/masadcv/FastGeodis/master/figures/FastGeodis2D.png?raw=true" width="300" /> | <img src="https://raw.githubusercontent.com/masadcv/FastGeodis/master/figures/FastGeodis3D.png?raw=true" width="300" /> |

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). 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:

Asad, Muhammad, Reuben Dorent, and Tom Vercauteren. "FastGeodis: Fast Generalised Geodesic Distance Transform." Journal of Open Source Software (JOSS), 2022. (paper link)

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

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 | | Fast Generalised Geodesic Distance 3D | Paralellised generalised geodesic distance transform for CPU/GPU [1] | FastGeodis.generalised_geodesic3d | | Fast Signed Generalised Geodesic Distance 2D | Paralellised signed generalised geodesic distance transform for CPU/GPU [1] | FastGeodis.signed_generalised_geodesic2d | | Fast Signed Generalised Geodesic Distance 3D | Paralellised signed generalised geodesic distance transform for CPU/GPU [1] | FastGeodis.signed_generalised_geodesic3d | | Fast Geodesic Symmetric Filtering 2D | Paralellised geodesic symmetric filtering for CPU/GPU [2] | FastGeodis.GSF2d | | Fast Geodesic Symmetric Filtering 3D | Paralellised geodesic symmetric filtering for CPU/GPU [2] | 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 | | Toivanen's Generalised Geodesic Distance 3D | Toivanen's generalised geodesic distance transform for CPU [9] | 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 | | Toivanen's Signed Generalised Geodesic Distance 3D | Toivanen's signed generalised geodesic distance transform for CPU [9] | FastGeodis.signed_generalised_geodesic3d_toivanen | | Toivanen's Geodesic Symmetric Filtering 2D | Toivanen's geodesic symmetric filtering for CPU [2, 9] | FastGeodis.GSF2d_toivanen | | Toivanen's Geodesic Symmetric Filtering 3D | Toivanen's geodesic symmetric filtering for CPU [2, 9] | 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 | | Pixel Queue Geodesic Distance 3D | Pixel Queue geodesic distance transform for CPU [11] | FastGeodis.geodesic3d_pixelqueue | | Pixel Queue Signed Geodesic Distance 2D | Pixel Queue signed geodesic distance transform for CPU [11] | FastGeodis.signed_geodesic2d_pixelqueue | | Pixel Queue Signed Geodesic Distance 3D | Pixel Queue signed geodesic distance transform for CPU [11] | FastGeodis.signed_geodesic3d_pixelqueue | | Pixel Queue Geodesic Symmetric Filtering 2D | Pixel Queue geodesic symmetric filtering for CPU [2, 11] | FastGeodis.GSF2d_pixelqueue | | Pixel Queue Geodesic Symmetric Filtering 3D | Pixel Queue geodesic symmetric filtering for CPU [2, 11] | 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 | | Fast Marching Geodesic Distance 3D | Fast Marching geodesic distance transform for CPU [9] | 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_geodesic

FastGeodis

Install / Use

README