compas_cgal.geodesics

Geodesic distance computation using CGAL heat method.

Classes

HeatGeodesicSolver

HeatGeodesicSolver(mesh: VerticesFaces)

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.types.VerticesFaces`	A triangulated mesh as a 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.

Functions

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: VerticesFaces, 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.types.VerticesFaces`	A triangulated mesh as a 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: VerticesFaces, 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.types.VerticesFaces`	A triangulated mesh as a 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: VerticesFaces, sources: list[int]) -> NDArray

Compute geodesic distances from source vertices using CGAL heat method.

Uses CGAL's Heat_method_3 with intrinsic Delaunay triangulation for accurate geodesic distance computation.

Parameters:

Name	Type	Description	Default
mesh	:attr:`compas_cgal.types.VerticesFaces`	A triangulated mesh as a tuple of vertices and faces.	required
sources	list[int]	Source vertex indices.	required

Returns:

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

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