API Documentation

Modules and Functions

This section provides the documentation of functions implemented in FastGeodis package. For usage examples, please see: Usage Examples section of this documentation.

FastGeodis.GSF2d(image: Tensor, softmask: Tensor, theta: float, v: float, lamb: float, iter: int)

Computes Geodesic Symmetric Filtering (GSF) using FastGeodis raster scanning. For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU or GPU depending on Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.GSF2d_fastmarch(image: Tensor, seed: Tensor, theta: float, lamb: float)

Computes Geodesic Symmetric Filtering (GSF) using Fast Marching method from:

Sethian, James A. “Fast marching methods.” SIAM review 41.2 (1999): 199-235.

For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.GSF2d_pixelqueue(image: Tensor, seed: Tensor, theta: float, lamb: float)

Computes Geodesic Symmetric Filtering (GSF) using Pixel Queue method from:

Ikonen, L., & Toivanen, P. (2007). “Distance and nearest neighbor transforms on gray-level surfaces.” Pattern Recognition Letters, 28(5), 604-612.

For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.GSF2d_toivanen(image: Tensor, softmask: Tensor, theta: float, v: float, lamb: float, iter: int)

Computes Geodesic Symmetric Filtering (GSF) using Toivanen’s raster scanning method from:

Toivanen, Pekka J. “New geodosic distance transforms for gray-scale images.” Pattern Recognition Letters 17.5 (1996): 437-450.

For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.GSF3d(image: Tensor, softmask: Tensor, theta: float, spacing: List, v: float, lamb: float, iter: int)

Computes Geodesic Symmetric Filtering (GSF) using FastGeodis raster scanning. For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU or GPU depending on Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• spacing – spacing for 3D data

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.GSF3d_fastmarch(image: Tensor, seed: Tensor, theta: float, spacing: List, lamb: float)

Computes Geodesic Symmetric Filtering (GSF) using Fast Marching method from:

Sethian, James A. “Fast marching methods.” SIAM review 41.2 (1999): 199-235.

For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• spacing – spacing for 3D data

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.GSF3d_pixelqueue(image: Tensor, seed: Tensor, theta: float, spacing: List, lamb: float)

Computes Geodesic Symmetric Filtering (GSF) using Pixel Queue method from:

Ikonen, L., & Toivanen, P. (2007). “Distance and nearest neighbor transforms on gray-level surfaces.” Pattern Recognition Letters, 28(5), 604-612.

For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in range {0, 1} with seed information.

• spacing – spacing for 3D data

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.GSF3d_toivanen(image: Tensor, softmask: Tensor, theta: float, spacing: List, v: float, lamb: float, iter: int)

Computes Geodesic Symmetric Filtering (GSF) using Toivanen’s raster scanning method from:

Toivanen, Pekka J. “New geodosic distance transforms for gray-scale images.” Pattern Recognition Letters 17.5 (1996): 437-450.

For more details on GSF, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• spacing – spacing for 3D data

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.generalised_geodesic2d(image: Tensor, softmask: Tensor, v: float, lamb: float, iter: int = 2)

Computes Generalised Geodesic Distance using FastGeodis raster scanning. For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU or GPU depending on Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.generalised_geodesic2d_toivanen(image: Tensor, softmask: Tensor, v: float, lamb: float, iter: int = 2)

Computes Generalised Geodesic Distance using Toivanen’s raster scanning method from:

Toivanen, Pekka J. “New geodosic distance transforms for gray-scale images.” Pattern Recognition Letters 17.5 (1996): 437-450.

For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.generalised_geodesic3d(image: Tensor, softmask: Tensor, spacing: List, v: float, lamb: float, iter: int = 4)

Computes Generalised Geodesic Distance using FastGeodis raster scanning. For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU or GPU depending on Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• spacing – spacing for 3D data

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.generalised_geodesic3d_toivanen(image: Tensor, softmask: Tensor, spacing: List, v: float, lamb: float, iter: int = 4)

Computes Generalised Geodesic Distance using Toivanen’s raster scanning method from:

Toivanen, Pekka J. “New geodosic distance transforms for gray-scale images.” Pattern Recognition Letters 17.5 (1996): 437-450.

For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• spacing – spacing for 3D data

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.geodesic2d_fastmarch(image: Tensor, seed: Tensor, lamb: float)

Computes Geodesic Distance using Fast Marching method from:

Sethian, James A. “Fast marching methods.” SIAM review 41.2 (1999): 199-235.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.geodesic2d_pixelqueue(image: Tensor, seed: Tensor, lamb: float)

Computes Geodesic Distance using Pixel Queue method from:

Ikonen, L., & Toivanen, P. (2007). “Distance and nearest neighbor transforms on gray-level surfaces.” Pattern Recognition Letters, 28(5), 604-612.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.geodesic3d_fastmarch(image: Tensor, seed: Tensor, spacing: List, lamb: float)

Computes Geodesic Distance using Fast Marching method from:

TSethian, James A. “Fast marching methods.” SIAM review 41.2 (1999): 199-235.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• spacing – spacing for 3D data

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.geodesic3d_pixelqueue(image: Tensor, seed: Tensor, spacing: List, lamb: float)

Computes Geodesic Distance using Pixel Queue method from:

Ikonen, L., & Toivanen, P. (2007). “Distance and nearest neighbor transforms on gray-level surfaces.” Pattern Recognition Letters, 28(5), 604-612.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• spacing – spacing for 3D data

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.signed_generalised_geodesic2d(image: Tensor, softmask: Tensor, v: float, lamb: float, iter: int = 2)

Computes Signed Generalised Geodesic Distance using FastGeodis raster scanning. For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU or GPU depending on Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.signed_generalised_geodesic2d_toivanen(image: Tensor, softmask: Tensor, v: float, lamb: float, iter: int = 2)

Computes Signed Generalised Geodesic Distance using Toivanen’s raster scanning method from:

Toivanen, Pekka J. “New geodosic distance transforms for gray-scale images.” Pattern Recognition Letters 17.5 (1996): 437-450.

For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.signed_generalised_geodesic3d(image: Tensor, softmask: Tensor, spacing: List, v: float, lamb: float, iter: int = 4)

Computes Signed Generalised Geodesic Distance using FastGeodis raster scanning. For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU or GPU depending on Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• spacing – spacing for 3D data

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.signed_generalised_geodesic3d_toivanen(image: Tensor, softmask: Tensor, spacing: List, v: float, lamb: float, iter: int = 4)

Computes Signed Generalised Geodesic Distance using Toivanen’s raster scanning method from:

Toivanen, Pekka J. “New geodosic distance transforms for gray-scale images.” Pattern Recognition Letters 17.5 (1996): 437-450.

For more details on generalised geodesic distance, check the following reference:

Criminisi, Antonio, Toby Sharp, and Andrew Blake. “Geos: Geodesic image segmentation.” European Conference on Computer Vision, Berlin, Heidelberg, 2008.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• softmask – softmask in range [0, 1] with seed information.

• spacing – spacing for 3D data

• v – weighting factor for establishing relationship between unary and spatial distances.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.signed_geodesic2d_fastmarch(image: Tensor, seed: Tensor, lamb: float)

Computes Signed Geodesic Distance using Fast Marching method from:

Sethian, James A. “Fast marching methods.” SIAM review 41.2 (1999): 199-235.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.signed_geodesic2d_pixelqueue(image: Tensor, seed: Tensor, lamb: float)

Computes Signed Generalised Geodesic Distance using Pixel Queue method from:

Ikonen, L., & Toivanen, P. (2007). “Distance and nearest neighbor transforms on gray-level surfaces.” Pattern Recognition Letters, 28(5), 604-612.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

Returns:

torch.Tensor with distance transform

FastGeodis.signed_geodesic3d_fastmarch(image: Tensor, seed: Tensor, spacing: List, lamb: float)

Computes Signed Geodesic Distance using Fast Marching method from:

Sethian, James A. “Fast marching methods.” SIAM review 41.2 (1999): 199-235.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• spacing – spacing for 3D data

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

FastGeodis.signed_geodesic3d_pixelqueue(image: Tensor, seed: Tensor, spacing: List, lamb: float)

Computes Signed Geodesic Distance using Pixel Queue method from:

Ikonen, L., & Toivanen, P. (2007). “Distance and nearest neighbor transforms on gray-level surfaces.” Pattern Recognition Letters, 28(5), 604-612.

The function expects input as torch.Tensor, which can be run on CPU only using Tensor’s device location

Parameters:

• image – input image, can be grayscale or multiple channels.

• seed – seed in {0, 1} with seed information.

• spacing – spacing for 3D data

• lamb – weighting factor between 0.0 and 1.0. 0.0 returns euclidean distance, whereas 1.0 returns geodesic distance

• iter – number of passes of the iterative distance transform method

Returns:

torch.Tensor with distance transform

Unittests

FastGeodis contains automated tests for checking correctness and functionality of the package. These are integrated as Github Workflows and are automatically run on multiple platforms anytime a push or pull request is made. These unittests can also be run locally as:

pip install -r requirements-dev.txt
python -m unittest

The test script can be found under the ./tests folder in the FastGeodis repository. For more information on unittest and instructions on how to run test files through the command line see the unittest documentation.