Compute geodesic distances
Project description
The tvbgdist module is a Cython interface to a C++ library (https://code.google.com/archive/p/geodesic/) for computing geodesic distance which is the length of shortest line between two vertices on a triangulated mesh in three dimensions, such that the line lies on the surface.
The algorithm is due Mitchell, Mount and Papadimitriou, 1987; the implementation is due to Danil Kirsanov and the Cython interface to Gaurav Malhotra and Stuart Knock (TVB Team).
Original library (published under MIT license): https://code.google.com/archive/p/geodesic/
We added a Python wrapped and made small fixes to the original library, to make it compatible with Cython.
To install this, either run pip install tvbgdist or download sources from GitHub and run python setup.py install in current folder.
You can also use pip to directly install from GitHub: pip install git+https://github.com/thevirtualbrain/tvbgdist.
Basic test could be:
python import gdist
Python 3, Cython, and a C++ compiler are required unless the Pypi whl files are compatible with your system.
APIs
The module exposes 2 APIs.
gdist.compute_gdist(numpy.ndarray[numpy.float64_t, ndim=2] vertices, numpy.ndarray[numpy.int32_t, ndim=2] triangles, numpy.ndarray[numpy.int32_t, ndim=1] source_indices = None, numpy.ndarray[numpy.int32_t, ndim=1] target_indices = None, double max_distance = GEODESIC_INF, bool is_one_indexed = False)
This is the wrapper function for computing geodesic distance between a set of sources and targets on a mesh surface.
 Args:
 vertices (numpy.ndarray[numpy.float64_t, ndim=2]): Defines x,y,z
 coordinates of the mesh’s vertices.
 triangles (numpy.ndarray[numpy.float64_t, ndim=2]): Defines faces of
 the mesh as index triplets into vertices.
 source_indices (numpy.ndarray[numpy.int32_t, ndim=1]): Index of the
 source on the mesh.
 target_indices (numpy.ndarray[numpy.int32_t, ndim=1]): Index of the
 targets on the mesh.
 max_distance (double): Propagation algorithm stops after reaching the
 certain distance from the source.
 is_one_indexed (bool): defines if the index of the triangles data is
 oneindexed.
 Returns:
 numpy.ndarray((len(target_indices), ), dtype=numpy.float64): Specifying
 the shortest distance to the target vertices from the nearest source vertex on the mesh. If no target_indices are provided, all vertices of the mesh are considered as targets, however, in this case, specifying max_distance will limit the targets to those vertices within max_distance of a source. If no source_indices are provided, it defaults to 0.
NOTE: This is the function to use when specifying localised stimuli and parameter variations. For efficiently using the whole mesh as sources, such as is required to represent local connectivity within the cortex, see the local_gdist_matrix() function.
 Basic usage then looks like::
>>> import numpy >>> temp = numpy.loadtxt("data/flat_triangular_mesh.txt", skiprows=1) >>> vertices = temp[0:121].astype(numpy.float64) >>> triangles = temp[121:321].astype(numpy.int32) >>> src = numpy.array([1], dtype=numpy.int32) >>> trg = numpy.array([2], dtype=numpy.int32) >>> import gdist >>> gdist.compute_gdist(vertices, triangles, source_indices=src, target_indices=trg) array([0.2])
gdist.local_gdist_matrix(numpy.ndarray[numpy.float64_t, ndim=2] vertices, numpy.ndarray[numpy.int32_t, ndim=2] triangles, double max_distance = GEODESIC_INF, bool is_one_indexed = False)
This is the wrapper function for computing geodesic distance from every vertex on the surface to all those within a distance max_distance of them.
 Args:
 vertices (numpy.ndarray[numpy.float64_t, ndim=2]): Defines x,y,z
 coordinates of the mesh’s vertices.
 triangles (numpy.ndarray[numpy.float64_t, ndim=2]): Defines faces of
 the mesh as index triplets into vertices.
 max_distance (double): Propagation algorithm stops after reaching the
 certain distance from the source.
 is_one_indexed (bool): defines if the index of the triangles data is
 oneindexed.
 Returns:
 scipy.sparse.csc_matrix((N, N), dtype=numpy.float64): where N is the number of vertices, specifying the shortest distance from all vertices to all the vertices within max_distance.
 Basic usage then looks like::
>>> import numpy >>> temp = numpy.loadtxt("data/flat_triangular_mesh.txt", skiprows=1) >>> import gdist >>> vertices = temp[0:121].astype(numpy.float64) >>> triangles = temp[121:321].astype(numpy.int32) >>> gdist.local_gdist_matrix(vertices, triangles, max_distance=1.0) <121x121 sparse matrix of type '<type 'numpy.float64'>' with 6232 stored elements in Compressed Sparse Column format>Runtime and guesstimated memory usage as a function of max_distance for the reg_13 cortical surface mesh, ie containing 2**13 vertices per hemisphere. :: [[10, 20, 30, 40, 50, 60, 70, 80, 90, 100], # mm [19, 28, 49, 81, 125, 181, 248, 331, 422, 522], # s [ 3, 13, 30, 56, 89, 129, 177, 232, 292, 358]] # MB]
where memory is a minguestimate given by: mem_req = nnz * 8 / 1024 / 1024.
distance_matrix_of_selected_points(numpy.ndarray[numpy.float64_t, ndim=2] vertices, numpy.ndarray[numpy.int32_t, ndim=2] triangles, numpy.ndarray[numpy.int32_t, ndim=1] points, double max_distance = GEODESIC_INF, bool is_one_indexed = False)
Function for calculating pairwise geodesic distance for a set of points within a distance max_distance of them.
 Args:
 vertices (numpy.ndarray[numpy.float64_t, ndim=2]): Defines x,y,z
 coordinates of the mesh’s vertices.
 triangles (numpy.ndarray[numpy.float64_t, ndim=2]): Defines faces of
 the mesh as index triplets into vertices.
 points (numpy.ndarray[numpy.int32_t, ndim=1]): Indices of the points
 among which the pairwise distances are to be calculated.
 max_distance (double): Propagation algorithm stops after reaching the
 certain distance from the source.
 is_one_indexed (bool): defines if the index of the triangles data is
 oneindexed.
 Returns:
 scipy.sparse.csc_matrix((N, N), dtype=numpy.float64): where N
 is the number of vertices, specifying the pairwise distances among the given points.
 Basic usage then looks like::
>>> import numpy >>> temp = numpy.loadtxt("data/flat_triangular_mesh.txt", skiprows=1) >>> vertices = temp[0:121].astype(numpy.float64) >>> triangles = temp[121:321].astype(numpy.int32) >>> points = numpy.array([2, 5, 10], dtype=numpy.int32) >>> import gdist >>> gdist.distance_matrix_of_selected_points( vertices, triangles, points ) <121x121 sparse matrix of type '<class 'numpy.float64'>' with 6 stored elements in Compressed Sparse Column format>
Notes
 The obtained matrix will be almost symmetrical due to floating point imprecision.
 In order for the algorithm to work the mesh must not be numbered incorrectly or disconnected or of somehow degenerate.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for tvb_gdist2.1.0cp38cp38win_amd64.whl
Algorithm  Hash digest  

SHA256  1c5438878e380933251a147fb1c13b038e8592ead56d6a3adaa0872cc1552ce3 

MD5  d69b2c2fe11cf4a435f00eccfb5df0de 

BLAKE2256  ab355195c371628ad28ddec0a9985f5c36876e480db2852a9c46d90339128c27 
Hashes for tvb_gdist2.1.0cp38cp38macosx_10_9_x86_64.whl
Algorithm  Hash digest  

SHA256  69f9977582af08bf54beeb5e46344a93ae40a08ae84a7bafe2ec91527ef79c47 

MD5  62605017b9cef0da23b089dc8aa8f73f 

BLAKE2256  6cd6596cf2f4f5b855e0c4ea62def9a98d453adad41c519ff40eafaa43215770 
Hashes for tvb_gdist2.1.0cp37cp37mwin_amd64.whl
Algorithm  Hash digest  

SHA256  fd71f203a860481dbddb47ce47fdd3b89b174e1129838ab12cb2a681dde9d804 

MD5  904e19834aefcee7e42b9558e112932a 

BLAKE2256  6feb34438973b5b474b738e9388139f142446c534bfcf47d50f51f6dab13cd54 
Hashes for tvb_gdist2.1.0cp36cp36mwin_amd64.whl
Algorithm  Hash digest  

SHA256  5ef104e5330e39433746209dec6826feac3fb82133aa6ebcf68d05df0c68e6a2 

MD5  9339d6370c789463fce2761491d2c830 

BLAKE2256  6f8fc59c1fcaa0a1f024105e4935227047b4f6995b7fc9f0523005cf92248a43 