geomfum.metric package#

Submodules#

geomfum.metric.mesh module#

Module containing metrics to calculate distances on a TriangleMesh.

class geomfum.metric.mesh.FinitePointSetMetric(shape)[source]#

Bases: Metric, ABC

Metric supporting distance matrices and source-to-all computations on discrete point sets.

abstractmethod dist_from_source(source_point)[source]#

Distances from a source point.

Parameters:

source_point (array-like, shape=[…]) – Index of source point.

Returns:

  • dist (array-like, shape=[…] or list-like[array-like]) – Distance.

  • target_point (array-like, shape=[n_targets] or list-like[array-like]) – Target index.

abstractmethod dist_matrix()[source]#

Distances between all the points of a shape.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.

class geomfum.metric.mesh.GraphShortestPathMetric(shape, cutoff=None)[source]#

Bases: _NxDijkstraMixins, FinitePointSetMetric

Geodesic distance approximation using Dijkstra’s algorithm on mesh edge graph.

Parameters:

  • shape (Shape) – Shape.

  • cutoff (float) – Length (sum of edge weights) at which the search is stopped.

class geomfum.metric.mesh.KClosestGraphShortestPathMetric(shape, k_closest=5)[source]#

Bases: _NxDijkstraMixins, FinitePointSetMetric

K-nearest neighbors geodesic distance using partial Dijkstra search.

Parameters:

  • shape (Shape) – Shape.

  • k_closest (int) – Number of nodes to find distances to (including the source itself).

class geomfum.metric.mesh.ScipyGraphShortestPathMetric(shape, cutoff=None)[source]#

Bases: _ScipyShortestPathMixins, FinitePointSetMetric

Geodesic distance approximation using SciPy’s shortest path algorithm.

Parameters:

  • shape (Shape) – Shape.

  • cutoff (float) – Length (sum of edge weights) at which the search is stopped.

class geomfum.metric.mesh.VertexEuclideanMetric(shape)[source]#

Bases: FinitePointSetMetric

Euclidean distance metric in ambient embedding space.

dist(point_a, point_b)[source]#

Distances between shape vertices.

Parameters:

  • point_a (array-like, shape=[…]) – Index of source point.

  • point_b (array-like, shape=[…]) – Index of target point.

Returns:

dist (array-like, shape=[…]) – Distance.

dist_from_source(source_point)[source]#

Distances from source point.

Parameters:

source_point (array-like, shape=[…]) – Index of source point.

Returns:

  • dist (array-like, shape=[…] or array-like[array-like]) – Distance.

  • target_point (array-like, shape=[n_targets] or array-like[array-like]) – Target index.

dist_matrix()[source]#

Distances between all shape vertices.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.

geomfum.metric.mesh.shortest_path(csgraph, method='auto', directed=True, return_predecessors=False, unweighted=False, overwrite=False, indices=None)#
shortest_path(csgraph, method=’auto’, directed=True, return_predecessors=False,

unweighted=False, overwrite=False, indices=None)

Perform a shortest-path graph search on a positive directed or undirected graph.

Added in version 0.11.0.

Parameters:

  • csgraph (array_like, or sparse array or matrix, 2 dimensions) – The N x N array of distances representing the input graph.

  • method (string [‘auto’|’FW’|’D’], optional) –

    Algorithm to use for shortest paths. Options are:

    ‘auto’ – (default) select the best among ‘FW’, ‘D’, ‘BF’, or ‘J’

    based on the input data.

    ‘FW’ – Floyd-Warshall algorithm.

    Computational cost is approximately O[N^3]. The input csgraph will be converted to a dense representation.

    ‘D’ – Dijkstra’s algorithm with priority queue.

    Computational cost is approximately O[I * (E + N) * log(N)], where E is the number of edges in the graph, and I = len(indices) if indices is passed. Otherwise, I = N. The input csgraph will be converted to a csr representation.

    ‘BF’ – Bellman-Ford algorithm.

    This algorithm can be used when weights are negative. If a negative cycle is encountered, an error will be raised. Computational cost is approximately O[N(N^2 k)], where k is the average number of connected edges per node. The input csgraph will be converted to a csr representation.

    ‘J’ – Johnson’s algorithm.

    Like the Bellman-Ford algorithm, Johnson’s algorithm is designed for use when the weights are negative. It combines the Bellman-Ford algorithm with Dijkstra’s algorithm for faster computation.

  • directed (bool, optional) – If True (default), then find the shortest path on a directed graph: only move from point i to point j along paths csgraph[i, j]. If False, then find the shortest path on an undirected graph: the algorithm can progress from point i to j along csgraph[i, j] or csgraph[j, i]

  • return_predecessors (bool, optional) – If True, return the size (N, N) predecessor matrix.

  • unweighted (bool, optional) – If True, then find unweighted distances. That is, rather than finding the path between each point such that the sum of weights is minimized, find the path such that the number of edges is minimized.

  • overwrite (bool, optional) – If True, overwrite csgraph with the result. This applies only if method == ‘FW’ and csgraph is a dense, c-ordered array with dtype=float64.

  • indices (array_like or int, optional) – If specified, only compute the paths from the points at the given indices. Incompatible with method == ‘FW’.

Returns:

  • dist_matrix (ndarray) – The N x N matrix of distances between graph nodes. dist_matrix[i,j] gives the shortest distance from point i to point j along the graph.

  • predecessors (ndarray, shape (n_indices, n_nodes,)) – Returned only if return_predecessors == True. If indices is None then n_indices = n_nodes and the shape of the matrix becomes (n_nodes, n_nodes). The matrix of predecessors, which can be used to reconstruct the shortest paths. Row i of the predecessor matrix contains information on the shortest paths from point i: each entry predecessors[i, j] gives the index of the previous node in the path from point i to point j. If no path exists between point i and j, then predecessors[i, j] = -9999

Raises:

NegativeCycleError: – if there are negative cycles in the graph

See also

word-ladders-example

An illustratation of the shortest_path API with a meaninful example. It also reconstructs the shortest path by using predecessors matrix returned by this function.

Notes

As currently implemented, Dijkstra’s algorithm and Johnson’s algorithm do not work for graphs with direction-dependent distances when directed == False. i.e., if csgraph[i,j] and csgraph[j,i] are non-equal edges, method=’D’ may yield an incorrect result.

If multiple valid solutions are possible, output may vary with SciPy and Python version.

Examples

>>> from scipy.sparse import csr_array
>>> from scipy.sparse.csgraph import shortest_path

>>> graph = [
... [0, 0, 7, 0],
... [0, 0, 8, 5],
... [7, 8, 0, 0],
... [0, 5, 0, 0]
... ]
>>> graph = csr_array(graph)
>>> print(graph)
<Compressed Sparse Row sparse array of dtype 'int64'
    with 6 stored elements and shape (4, 4)>
    Coords  Values
    (0, 2)  7
    (1, 2)  8
    (1, 3)  5
    (2, 0)  7
    (2, 1)  8
    (3, 1)  5

>>> sources = [0, 2]
>>> dist_matrix, predecessors = shortest_path(csgraph=graph, directed=False, indices=sources, return_predecessors=True)
>>> dist_matrix
array([[ 0., 15.,  7., 20.],
       [ 7.,  8.,  0., 13.]])
>>> predecessors
array([[-9999,     2,     0,     1],
       [    2,     2, -9999,     1]], dtype=int32)

Reconstructing shortest paths from sources to all the nodes of the graph.

>>> shortest_paths = {}
>>> for idx in range(len(sources)):
...     for node in range(4):
...         curr_node = node # start from the destination node
...         path = []
...         while curr_node != -9999: # no previous node available, exit the loop
...             path = [curr_node] + path # prefix the previous node obtained from the last iteration
...             curr_node = int(predecessors[idx][curr_node]) # set current node to previous node
...         shortest_paths[(sources[idx], node)] = path
...

Computing the length of the shortest path from node 0 to node 3 of the graph. It can be observed that computed length and the dist_matrix value are exactly same.

>>> shortest_paths[(0, 3)]
[0, 2, 1, 3]
>>> path03 = shortest_paths[(0, 3)]
>>> sum([graph[path03[0], path03[1]], graph[path03[1], path03[2]], graph[path03[2], path03[3]]])
np.int64(20)
>>> dist_matrix[0][3]
np.float64(20.0)

Another example of computing shortest path length from node 2 to node 3. Here, dist_matrix[1][3] is used to get the length of the path returned by shortest_path. This is because node 2 is the second source, so the lengths of the path from it to other nodes in the graph will be at index 1 in dist_matrix.

>>> shortest_paths[(2, 3)]
[2, 1, 3]
>>> path23 = shortest_paths[(2, 3)]
>>> sum([graph[path23[0], path23[1]], graph[path23[1], path23[2]]])
np.int64(13)
>>> dist_matrix[1][3]
np.float64(13.0)
geomfum.metric.mesh.single_source_partial_dijkstra_path_length(graph, source, k, weight='weight')[source]#

Compute shortest-path distances from a source node to the k closest nodes.

Based on cumulative path cost, using an early-stopped Dijkstra’s algorithm.

The search terminates once k nodes (including the source itself) have been reached.

Parameters:

  • graph (networkx.Graph) – The input graph. Can be directed or undirected. Edge weights must be non-negative.

  • source (node) – The starting node for paths.

  • k (int) – Number of nodes to find distances to (including the source itself).

Returns:

length (dict) – Dict keyed by node to shortest path length from source.

geomfum.metric.mesh.to_nx_edge_graph(shape)[source]#

Convert a shape to a networkx graph.

Parameters:

shape (Shape) – Shape.

Returns:

graph (networkx.Graph) – Graph.

geomfum.metric.point_cloud module#

Module containing metrics to calculate distances on a PointCloud. For the moment, only Euclidean distances are supported, which are for general shapes.

Module contents#

Metrics Module. This module contains various metrics for computing distances on shapes.

class geomfum.metric.FinitePointSetMetric(shape)[source]#

Bases: Metric, ABC

Metric supporting distance matrices and source-to-all computations on discrete point sets.

abstractmethod dist_from_source(source_point)[source]#

Distances from a source point.

Parameters:

source_point (array-like, shape=[…]) – Index of source point.

Returns:

  • dist (array-like, shape=[…] or list-like[array-like]) – Distance.

  • target_point (array-like, shape=[n_targets] or list-like[array-like]) – Target index.

abstractmethod dist_matrix()[source]#

Distances between all the points of a shape.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.

class geomfum.metric.HeatDistanceMetric(*args, **kwargs)[source]#

Bases: MeshWhichRegistryMixins

Geodesic distance approximation using the heat method.

References

[CWW2017]

Crane, K., Weischedel, C., Wardetzky, M., 2017. The heat method for distance computation. Commun. ACM 60, 90–99. https://doi.org/10.1145/3131280

class geomfum.metric.Metric(shape)[source]#

Bases: ABC

Abstract base class for distance metrics on shapes.

Parameters:

shape (Shape) – Considered as a manifold.

abstractmethod dist(point_a, point_b)[source]#

Distance between points.

Parameters:

  • point_a (array-like, shape=[…]) – Index Point.

  • point_b (array-like, shape=[…]) – Index Point.

Returns:

dist (array-like, shape=[…,]) – Distance.

class geomfum.metric.VertexEuclideanMetric(shape)[source]#

Bases: FinitePointSetMetric

Euclidean distance metric in ambient embedding space.

dist(point_a, point_b)[source]#

Distances between shape vertices.

Parameters:

  • point_a (array-like, shape=[…]) – Index of source point.

  • point_b (array-like, shape=[…]) – Index of target point.

Returns:

dist (array-like, shape=[…]) – Distance.

dist_from_source(source_point)[source]#

Distances from source point.

Parameters:

source_point (array-like, shape=[…]) – Index of source point.

Returns:

  • dist (array-like, shape=[…] or array-like[array-like]) – Distance.

  • target_point (array-like, shape=[n_targets] or array-like[array-like]) – Target index.

dist_matrix()[source]#

Distances between all shape vertices.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.