Matrix operators

Connectivity operators

adjacency_matrix(mesh, weights='one')

Computes and returns the adjacency matrix of a mesh, that is a (sparse) matrix M such that

M[i,j] = M[j,i] = weights[i,j] if (i,j) is an edge of the mesh

M[i,j] = 0 otherwise

Parameters:

Name	Type	Description	Default
mesh	Mesh	the input mesh	required
weights	str	How to weight the edges of the matrix. Options are: - "one" : every edge is 1 - "length" : every edge has weight corresponding to its length - a custom dict edge_id:int -> weight:float Defaults to "one".	'one'

Returns:

Type	Description
coo_matrix	scipy.sparse.coo_matrix

vertex_to_edge_operator(mesh, oriented=False)

Vertices to edges operator. Matrix M of size |V|x|E| where:

M[v,e] = 1 if and only if v is one extremity of edge e.

if oriented is set, M[v,e] = -1 if v is the origin of the edge and 1 if it is the arrival.

Parameters:

Name	Type	Description	Default
mesh	Mesh	the input mesh	required
oriented	bool	whether to consider oriented edge and signed values or not. Defaults to False.	False

Returns:

Type	Description
csc_matrix	scipy.sparse.csc_matrix

vertex_to_face_operator(mesh)

Vertices to face operator. Matrix M of size |V| x |F| where:

M[v,f] = 1/len(f) if and only if v is one of the vertices of f

Parameters:

Name	Type	Description	Default
mesh	SurfaceMesh	input surface mesh	required

Returns:

Type	Description
csc_matrix	scipy.sparse.csc_matrix

See also

mouette.attributes.interpolate_vertices_to_faces

Gradient operator

    G = M.operators.gradient(mesh)
    my_fun = mesh.vertices.get_attribute("f").as_array()
    grad = G @ my_fun

Computes the gradient operator, i.e. a |F| x |V| matrix G such that for any scalar function f defined over vertices of a surface mesh, Gf is its gradient inside faces.

Gf maps to each face of the mesh either a vector of \(\mathbb{R}^2\) or a complex number representing the gradient vector inside this face in local base.

See https://github.com/GCoiffier/mouette/blob/main/examples/gradient.py

Parameters:

Name	Type	Description	Default
mesh	SurfaceMesh	The input mesh	required
conn	SurfaceConnectionFaces	Connection objects specifying local bases of faces.	required
as_complex	bool	whether the output is |F| complex values of 2|F| float values	True

Raises:

Type	Description
Exception	Fails if the mesh is not a triangulation

Returns:

Type	Description
csc_matrix	scipy.sparse.csc_matrix: Gradient operator

Laplacian operators

https://en.wikipedia.org/wiki/Discrete_Laplace_operator#Mesh_Laplacians

We refer to this course for a great overview of the Laplacian operator and its use in geometry processing.

For the generalization to volumes, see this pdf

Example

import mouette as M
import numpy as np

mesh = M.mesh.load("path/to/my/mesh/mesh.obj")
W = M.operators.laplacian(mesh,cotan=True)
A = M.operators.area_weight_matrix(mesh, inverse=True)
L = A @ W # discretization of the laplace-beltrami operator is inverted mass matrix times the cotan weight matrix
X = np.random.random(len(mesh.vertices)) # a value in (0,1) per vertex
for _ in range(10):
    X = W.dot(X) # perform 10 steps of diffusion

graph_laplacian(mesh)

Simplest Laplacian defined on a graph. uses uniform weights for connectivity.

Parameters:

Name	Type	Description	Default
mesh	Mesh	the input mesh	required

Returns:

Type	Description
csc_matrix	(scipy.sparse.coo_matrix) : the laplacian operator as a sparse matrix

laplacian(mesh, cotan=True, connection=None, order=4)

Cotan laplacian on vertices.

Parameters:

Name	Type	Description	Default
mesh	SurfaceMesh	input mesh	required
cotan	bool)	whether to compute real cotan values for more precise discretization or only 0/1 values as a graph laplacian. Defaults to True.	True
connection	SurfaceConnectionVertices	For a laplacian on 1-forms, gives the angle in local bases of all adjacent edges. Defaults to None.	None
order	int	Order of the parallel transport (useful when computing frame fields). Does nothing if connection is set to None. Defaults to 4.	4

Returns:

Type	Description
csc_matrix	scipy.sparse.csc_matrix : the Laplacian operator as a sparse matrix

laplacian_triangles(mesh, cotan=True, connection=None, order=4)

Cotan laplacian defined on face connectivity (ie on the dual mesh)

Parameters:

Name	Type	Description	Default
mesh	SurfaceMesh	the supporting mesh	required
cotan	bool	whether to use cotangents as weights. Defaults to True.	True
connection	SurfaceConnectionFaces	The surface connection describing local bases and parallel transport for a Laplacian that acts on vectors in tangent spaces. Defaults to None (scalar Laplacian).	None
order	int	Order of the parallel transport (useful when computing frame fields). Does nothing if connection is set to None. Defaults to 4.	4

Returns:

Type	Description
lil_matrix	scipy.sparse.lil_matrix : the Laplacian operator as a sparse matrix

volume_laplacian(mesh)

Volume laplacian on vertices

This is the 3D extension of the cotan laplacian, ie the discretization of the Laplace-Beltrami operator on 3D manifolds.

Parameters:

Name	Type	Description	Default
mesh	VolumeMesh	the input mesh	required

Returns:

Type	Description
lil_matrix	scipy.sparse.lil_matrix: the Laplacian operator as a sparse matrix

References

[1] https://cseweb.ucsd.edu/~alchern/projects/ConformalVolume/

[2] https://www.cs.cmu.edu/~kmcrane/Projects/Other/nDCotanFormula.pdf

laplacian_tetrahedra(mesh)

Laplacian defined on cell connectivity (ie on the dual volume mesh)

Parameters:

Name	Type	Description	Default
mesh	SurfaceMesh	input mesh	required

Returns:

Type	Description
csc_matrix	scipy.sparse.csc_matrix

cotan_edge_diagonal(mesh, inverse=True)

Builds a diagonal matrix of size |E|x|E| where the coefficients are the cotan weights, i.e.

M[e,e] = 1/abs( cot(a_e) + cot(b_e))

where a_e and b_e are the opposite angles in adjacent triangles of edge e.

Parameters:

Name	Type	Description	Default
mesh	SurfaceMesh	input mesh	required
inverse	bool	whether to compute M or M^-1 (all coefficients on the diagonal inverted)	True

Returns:

Type	Description
csc_matrix	sp.csc_matrix