compas_cgal.geodesics

Geodesic distance computation using the heat method.

Classes

HeatGeodesicSolver

HeatGeodesicSolver(mesh: Mesh)

HeatGeodesicSolver(mesh: VerticesFaces)

HeatGeodesicSolver(mesh: MeshInput)

Precomputed heat method solver for repeated geodesic queries.

Use this class when computing geodesic distances from multiple different sources on the same mesh. The expensive precomputation is done once in the constructor, and solve() can be called many times efficiently.

Parameters:

Name	Type	Description	Default
mesh	:attr:`compas_cgal.geodesics.MeshInput`	A triangulated mesh, either a :class:compas.datastructures.Mesh or a :attr:compas_cgal.types.VerticesFaces tuple of vertices and faces.	required

Examples:

>>> from compas.geometry import Sphere
>>> from compas_cgal.geodesics import HeatGeodesicSolver
>>> sphere = Sphere(1.0)
>>> mesh = sphere.to_vertices_and_faces(u=32, v=32, triangulated=True)
>>> solver = HeatGeodesicSolver(mesh)  # precomputation happens here
>>> d0 = solver.solve([0])  # distances from vertex 0
>>> d1 = solver.solve([1])  # distances from vertex 1 (fast, reuses precomputation)

Attributes

num_vertices property

num_vertices: int

Number of vertices in the mesh.

Methods:

solve

solve(sources: list[int]) -> NDArray

Compute geodesic distances from source vertices.

Parameters:

Name	Type	Description	Default
sources	list[int]	Source vertex indices.	required

Returns:

Type	Description
NDArray	Geodesic distances from the nearest source to each vertex. Shape is (n_vertices,).

Functions:

geodesic_isolines

geodesic_isolines(
    mesh: Mesh, sources: list[int], isovalues: list[float]
) -> PolylinesNumpy

geodesic_isolines(
    mesh: VerticesFaces, sources: list[int], isovalues: list[float]
) -> PolylinesNumpy

geodesic_isolines(
    mesh: MeshInput, sources: list[int], isovalues: list[float]
) -> PolylinesNumpy

Extract isoline polylines from geodesic distance field.

Computes geodesic distances and extracts polylines along specified isovalues.

Parameters:

Name	Type	Description	Default
mesh	:attr:`compas_cgal.geodesics.MeshInput`	A triangulated mesh, either a :class:compas.datastructures.Mesh or a :attr:compas_cgal.types.VerticesFaces tuple of vertices and faces.	required
sources	list[int]	Source vertex indices for geodesic distance computation.	required
isovalues	list[float]	Isovalue thresholds for isoline extraction.	required

Returns:

Type	Description
attr:`compas_cgal.types.PolylinesNumpy`	List of polyline segments as Nx3 arrays of points.

geodesic_isolines_split

geodesic_isolines_split(
    mesh: Mesh, sources: list[int], isovalues: list[float]
) -> list[VerticesFacesNumpy]

geodesic_isolines_split(
    mesh: VerticesFaces, sources: list[int], isovalues: list[float]
) -> list[VerticesFacesNumpy]

geodesic_isolines_split(
    mesh: MeshInput, sources: list[int], isovalues: list[float]
) -> list[VerticesFacesNumpy]

Split mesh into components along geodesic isolines.

Computes geodesic distances from sources, refines the mesh along specified isovalue thresholds, and splits into connected components.

Parameters:

Name	Type	Description	Default
mesh	:attr:`compas_cgal.geodesics.MeshInput`	A triangulated mesh, either a :class:compas.datastructures.Mesh or a :attr:compas_cgal.types.VerticesFaces tuple of vertices and faces.	required
sources	list[int]	Source vertex indices for geodesic distance computation.	required
isovalues	list[float]	Isovalue thresholds for splitting. The mesh will be refined along curves where the geodesic distance equals each isovalue, then split into connected components.	required

Returns:

Type	Description
List[:attr:`compas_cgal.types.VerticesFacesNumpy`]	List of mesh components as (vertices, faces) tuples.

Examples:

>>> from compas.geometry import Sphere
>>> from compas_cgal.geodesics import geodesic_isolines_split
>>> sphere = Sphere(1.0)
>>> mesh = sphere.to_vertices_and_faces(u=32, v=32, triangulated=True)
>>> components = geodesic_isolines_split(mesh, [0], [0.5, 1.0, 1.5])
>>> len(components)  # Number of mesh strips

heat_geodesic_distances

heat_geodesic_distances(mesh: Mesh, sources: list[int]) -> NDArray

heat_geodesic_distances(mesh: VerticesFaces, sources: list[int]) -> NDArray

heat_geodesic_distances(mesh: MeshInput, sources: list[int]) -> NDArray

Compute geodesic distances from source vertices using the heat method.

Heat method (Crane et al. 2017) with a Dirichlet-constrained Poisson step: the distance is exactly 0 at every source vertex and remains accurate for multi-vertex source sets (e.g. all boundary vertices of an open mesh).

Parameters:

Name	Type	Description	Default
mesh	:attr:`compas_cgal.geodesics.MeshInput`	A triangulated mesh, either a :class:compas.datastructures.Mesh or a :attr:compas_cgal.types.VerticesFaces tuple of vertices and faces.	required
sources	list[int]	Source vertex indices (at least one; out-of-range indices are ignored).	required

Returns:

Type	Description
NDArray	Geodesic distances from the nearest source to each vertex. Shape is (n_vertices,).

Raises:

Type	Description
ValueError	If no valid source vertex index is given.
RuntimeError	If a connected component of the mesh contains no source vertex.

Examples:

>>> from compas.geometry import Box
>>> from compas_cgal.geodesics import heat_geodesic_distances
>>> box = Box(1)
>>> mesh = box.to_vertices_and_faces(triangulated=True)
>>> distances = heat_geodesic_distances(mesh, [0])  # distances from vertex 0