surfa.Mesh#

class surfa.Mesh(vertices, faces=None, space='surf', geometry=None, metadata=None)#

Triangular mesh topology represented by arrays of vertices and faces.

Properties of the mesh graph are automatically recomputed when the vertex and face data is updated.

Parameters

  • vertices ((V, 3) float) – Mesh vertex locations

  • faces ((F, 3) int) – Triangular faces indices.

  • space (Space) – Coordinate space of the point data. Defaults to the ‘surface’ coordinate system.

  • geometry (ImageGeometry) – Geometry mapping the point data to world and image coordinates.

  • metadata (dict) – Dictionary containing arbitrary array metadata.

Attributes

adjacent_faces

Adjacent faces that correspond to each edge in unique_edges.

edge_face

Face index corresponding to each directional edge in the mesh.

edges

All directional edges in the mesh.

face_angles

Face angles (in radians).

face_areas

Face normal (unit) vectors.

face_normals

Face normal (unit) vectors.

faces

Mesh triangle faces defined by a (F, 3) array, where F corresponds to the total number of mesh faces.

geom

Geometry that maps mesh coordinates to image and world spaces.

is_sphere

Whether the mesh is characterized by spherical properties.

kdtree

KD tree of the vertex structure.

metadata

Metadata dictionary.

nfaces

Total number of faces in the mesh.

nvertices

Total number of vertices in the mesh.

space

Coordinate space of the points.

triangles

Triangle coordinate arrary with shape (F, 3, 3).

triangles_cross

Vertex cross-product.

unique_edge_indices

Indices to extract all unique edges from the directional edge list.

unique_edges

Unique bi-directional edges in the mesh.

unique_face_edges

Unique edge indices corresponding to the sides of each face.

vertex_normals

Vertex normal (unit) vectors, with contributing face normals weighted by their angle.

vertices

Mesh 3D point positions defined by a (V, 3) array, where V corresponds to the number of vertices.

Methods

bbox()#

The (min, max) coordinates defining the mesh’s bounding box.

convert(space=None, geometry=None, copy=True)#

Convert mesh vertex positions into a new coordinate space, given a particular image geometry.

Parameters

  • space (Space) – Target coordinate space.

  • geometry (Geometry) – Target image geometry.

  • copy (bool) – Return a copy of the mesh when target space and geometry conditions are already satisfied.s

Returns

Mesh with converted vertex positions.

Return type

Mesh

copy()#

Return a deep copy of the object.

face_to_vertex_overlay(overlay, method='mean')#

Convert a face-specific overlay to a vertex-specific overlay.

Parameters

  • overlay (Overlay) – Face overlay to convert, must have points equal to the number of mesh faces.

  • method ({'mean', 'min', 'max', 'sum'}) – Reduction method to gather face scalars over vertices.

Returns

scalars

Return type

Overlay

find_self_intersecting_faces(knn=50, overlay=False)#

Locate any faces in the mesh topology that are self-intersecting with each other. To fix these intersections, see mesh.remove_self_intersections.

Parameters

  • knn (int) – Number of nearest face neighbors to compute intersections with. The default value should be sufficient for most meshes.

  • overlay (bool) – If this is enabled, the return value will be a face overlay marking intersecting faces.

Returns

intersecting – Returns an integer array listing the indices of intersecting faces, unless overlay is enabled, in which case the function returns a boolean overlay marking the intersecting faces.

Return type

int array or Overlay

nearest_vertex(points, k=1)#

Locate the nearest k vertices from a point or list of points.

Parameters

  • points ((n, 3) float) – Point or list of points to query.

  • k (int, optional) – Number of nearest vertices to search for.

Returns

  • vertices ((n,) int) – Indices of nearest vertices.

  • dists ((n,) float) – Distance to vertex.

remove_self_intersections(smoothing_iters=2, global_iters=50, knn=50, verbose=False)#

Remove self-intersecting faces in the mesh by smoothing the vertex positions of offending triangles.

TODOC: Needs some documentation actually explaining what the removal procedure involves.

Parameters

  • smoothing_iters (int) – Number of smoothing steps in each local removal iteration.

  • global_iters (int) – Max number of intersection-checking and smoothing iterations before giving up.

  • knn (int) – Number of nearest face neighbors to compute intersections with. The default value should be sufficient for most meshes.

  • verbose (bool) – Print intersection information throughout the removal process.

Returns

intersecting – Returns an integer array listing the indices of intersecting faces, unless overlay is enabled, in which case the function returns a boolean overlay marking the intersecting faces.

Return type

int array or Overlay

save(filename, fmt=None, **kwargs)#

Write mesh to file.

Parameters

  • filename (str) – Target filename to write array to.

  • fmt (str) – Optional file format to force.

  • **kwargs – Additional keyword arguments passed to the file format writer.

smooth_overlay(overlay, iters=10, step=0.5, weighted=True, pinned=None)#

Smooth the scalar values of an overlay along the mesh.

Parameters

  • overlay (Overlay) – Overlay to smooth.

  • iters (int) – Number of smoothing iterations.

  • step (float) – The step rate of the smoothing. This controls how much to weight the contribution of the neighboring vertices at each smoothing iteration.

  • weighted (bool) – Whether the contribution of each vertex neighbor is weighted by its inverse distance from the target vertex. Otherwise, all neighbors are weighted equally.

  • pinned (ndarray or Overlay) – Mask of pinned (unchanging) values in the mesh.

Returns

overlay – Smoothed mesh overlay.

Return type

Overlay

sparse_neighborhood(weighted=True)#

Compute a COO sparse matrix representing the immediate neighborhood of vertices around each vertex. Matrix values indicate the weight of each neighbor contribution to the target vertex.

Parameters

weighted (bool) – Whether the contribution of each vertex neighbor is weighted by its inverse distance from the target vertex. Otherwise, all neighbors are weighted equally.

Returns

sparse

Return type

scipy.sparse.coo_matrix

transform(trf, space=None)#

Transform mesh vertex positions. If the provided transform has a target geometry, the returned mesh will adopt that geometry.

Parameters

  • transform (Affine) – Affine transform to apply to the mesh coordinates. Only linear transforms are supported for now.

  • space (Space) – Transformed surface coordinate space.

Returns

Mesh with transformer vertex positions and updated geometry.

Return type

Mesh

vertex_to_face_overlay(overlay, method='mean')#

Convert a vertex-specific overlay to a face-specific overlay.

Parameters

  • overlay (Overlay) – Vertex overlay to convert, must have points equal to the number of mesh vertices.

  • method ({'mean', 'min', 'max', 'sum'}) – Reduction method to gather vertex scalars over faces.

Returns

scalars

Return type

Overlay