Skip to content

Gradient

Example

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

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

AABB(p_min, p_max)

Axis Aligned Bounding Box in n dimensions.

Parameters:

Name Type Description Default
p_min Iterable

minimal values for each dimension

 required
p_max Iterable

maximal values for each dimension

 required

Raises:

Type Description
Exception

fails if p_min and p_max have different sizes (inconsistent dimension)

center: Vec property

Coordinates of the center point

Returns:

Name Type Description
Vec Vec

center point

dim: int property

Dimension of the axis-aligned bounding box

Returns:

Name Type Description
int int

dimension

maxi: Vec property

Maximum coordinates of any point inside the box. The box is an axis-aligned hexahedron which opposite corners are mini and maxi

Returns:

Name Type Description
Vec Vec

maximum coordinates

mini: Vec property

Minimum coordinates of any point inside the box The box is an axis-aligned hexahedron which opposite corners are mini and maxi

Returns:

Name Type Description
Vec Vec

minimum coordinates

span: Vec property

Dimensions of the box

Returns:

Name Type Description
Vec Vec

dimensions of the box

contains_point(pt)

Point - bounding box intersection predicate. If the point is on the boundary of the box, the convention is as follows: inclusive if the point touches the min coordinates, exclusive for the max coordinates

Parameters:

Name Type Description Default
pt Vec

a query position

 required

Raises:

Type Description
IncompatibleDimensionError

fails if the point has a different dimension than the bounding box.

Returns:

Name Type Description
bool bool

whether the point 'pt' is inside the bounding box.

distance(pt, which='l2')

Computes the distance from a point to the bounding box.

Parameters:

Name Type Description Default
pt Vec

coordinates of the point

 required
which str

which distance to consider. Choices are 'l2', 'l1' or 'linf'. Defaults to "l2".

 'l2'

Raises:

Type Description
IncompatibleDimensionError

fails if the point has a different dimension than the bounding box.

Returns:

Name Type Description
float float

the distance from the point to the bounding box

do_intersect(b1, b2) staticmethod

Intersection test between two bounding boxes

Parameters:

Name Type Description Default
b1 AABB

first bounding box

 required
b2 AABB

second bounding box

 required

Raises:

Type Description
IncompatibleDimensionError

fails if b1 and b2 have different dimensions

Returns:

Name Type Description
bool bool

whether the two BB intersect

infinite(dim) classmethod

Computes a bounding box with bounds at infinity, containing the whole space R^n

Parameters:

Name Type Description Default
dim int

dimension of the BB to build

 required

Returns:

Name Type Description
AABB AABB

A bounding box containing all of R^n

intersection(b1, b2) staticmethod

Computes the intersection bounding box of two bounding boxes

Parameters:

Name Type Description Default
b1 AABB

first bounding box

 required
b2 AABB

second bounding box

 required

Raises:

Type Description
IncompatibleDimensionError

fails if b1 and b2 have different dimensions

Returns:

Name Type Description
AABB AABB

a bounding box representing the intersection (may be empty).

is_empty()

Tests if the bounding box encloses an empty domain

Returns:

Name Type Description
bool bool

whether the bounding box is empty

of_mesh(mesh, padding=0.0) classmethod

Computes the 3D bounding box of all vertices of a mesh

Parameters:

Name Type Description Default
mesh Mesh

input mesh. Can be of any type (only the 'vertices' container is accessed)

 required
padding float

slack to be added between the mesh and the box. Defaults to 0 for a tight bounding box.

 0.0

Returns:

Name Type Description
AABB AABB

3D bounding box of the vertices of the mesh

of_points(points, padding=0.0) classmethod

Computes the bounding box of a set of nD points.

Parameters:

Name Type Description Default
points ndarray

input points

 required
padding float

slack to be added between the mesh and the box. Defaults to 0 for a tight bounding box.

 0.0

Returns:

Name Type Description
AABB AABB

nD bounding box of the points

pad(pad)

Enlarges the bounding box by adding pad on each dimension on each side. Does nothing if the padding values are negative.

Parameters:

Name Type Description Default
pad float | iterable

Additional dimensions to be added. If a float is provided, will assume that padding is the same for each dimensions. If an array is provided, its size should match the dimension of the box. Values are clamped to be >=0.

 required

project(pt)

Computes the closest point from point 'pt' in the bounding box in Euclidean distance

Parameters:

Name Type Description Default
pt Vec

the point to project

 required

Raises:

Type Description
IncompatibleDimensionError

fails if the point has a different dimension than the bounding box.

Returns:

Name Type Description
Vec Vec

the projected point

union(b1, b2) staticmethod

Computes the union bounding box of two bounding boxes

Parameters:

Name Type Description Default
b1 AABB

first bounding box

 required
b2 AABB

second bounding box

 required

Raises:

Type Description
IncompatibleDimensionError

fails if b1 and b2 have different dimensions

Returns:

Name Type Description
AABB AABB

a bounding box representing the union

unit_cube(dim, centered=False) classmethod

Computes the unit bounding box [0,1]^n or [-0.5, 0.5]^n

Parameters:

Name Type Description Default
dim int

dimension of the BB to build

 required
centered bool

whether to generate [0,1]^n (False) or [-0.5;0.5]^n (True). Defaults to False.

 False

Returns:

Name Type Description
AABB AABB

a hypercube of side length 1

PointCloud(data=None)

Bases: Mesh

A data structure for representing point clouds

Attributes:

Name Type Description
vertices DataContainer

the container for all vertices
__str__ str

Representation of the object and its elements as a string.

id_vertices property

Shortcut for range(len(self.vertices))

append(x)

Shortcut for self.vertices.append(x), since we can only append elements in the 'vertices' container

PolyLine(data=None)

Bases: Mesh

A data structure for representing polylines.

Attributes:

Name Type Description
vertices DataContainer

the container for all vertices
edges DataContainer

the container for all edges
__str__

Representation of the object and its elements as a string.

id_edges property

Shortcut for range(len(self.edges))

id_vertices property

Shortcut for range(len(self.vertices))

SurfaceMesh(data=None)

Bases: Mesh

A data structure for representing polygonal surfaces.

Attributes:

Name Type Description
vertices DataContainer

the container for all vertices
edges DataContainer

the container for all edges
faces DataContainer

the container for all faces
face_corners DataContainer

the container for all corner of faces
boundary_edges list

list of all edge indices on the boundary
interior_edges list

list of all interior edge indices (all edges \ boundary_edges)
boundary_vertices list

list of all vertex indices on the boundary
interior_vertices list

list of all interior verticex indices (all vertices \ boundary_vertices)
connectivity _SurfaceConnectivity

the connectivity utility class

id_corners property

Shortcut for range(len(self.face_corners))

id_edges property

Shortcut for range(len(self.edges))

id_faces property

Shortcut for range(len(self.faces))

id_vertices property

Shortcut for range(len(self.vertices))

clear_boundary_data()

Clear all boundary data. Next call to a boundary/interior container or method will recompute everything

is_edge_on_border(u, v)

whether edge (u,v) is a boundary edge or not

Parameters:

Name Type Description Default
u int

vertex id

 required
v int

vertex id

 required

Returns:

Name Type Description
bool bool

whether edge (u,v) is a boundary edge or not. Returns False if (u,v) is not a valid edge.

is_quad()

Returns:

Name Type Description
bool bool

True if the mesh is quadrangular (all faces are quad)

is_triangular()

Returns:

Name Type Description
bool bool

True if the mesh is triangular (all faces are triangles)

is_vertex_on_border(u)

whether vertex u is a boundary vertex or not.

Parameters:

Name Type Description Default
u int

vertex id

 required

Returns:

Name Type Description
bool bool

whether vertex u is a boundary vertex or not.

ith_vertex_of_face(fid, i)

helper function to get the i-th vertex of a face, i.e. self.faces[fid][i]

Parameters:

Name Type Description Default
fid int

face id

 required
i int

vertex id in face. Should be 0 <= vid < len(face)

 required

Returns:

Name Type Description
int int

the id of the i-th vertex in face fid (self.faces[fid][i])

pt_of_face(fid)

point coordinates of vertices of face fid

Parameters:

Name Type Description Default
fid int

face id

 required

Returns:

Name Type Description
Iterable

iterator of Vec objects representing point coordinates of vertices

Vec

Bases: ndarray

A simple class to manipulate vectors in mouette. Basically, it inherits from a numpy array and implements some quality of life features for 2D and 3D vectors especially.

x: float property writable

First coordinate of the vector

Returns:

Name Type Description
float float

vec[0]

xy property

First two coordinates of the vector

Returns:

Name Type Description
float

vec[:2]

y property writable

Second coordinate of the vector

Returns:

Name Type Description
float

vec[1]

z property writable

Third coordinate of the vector

Returns:

Name Type Description
float

vec[3]

X() classmethod

The [1,0,0] vector

Returns:

Name Type Description
Vec

[1,0,0]

Y() classmethod

The [0,1,0] vector

Returns:

Name Type Description
Vec

[0,1,0]

Z() classmethod

The [0,0,1] vector

Returns:

Name Type Description
Vec

[0,0,1]

dot(other)

Dot product between two vectors:

$ a \cdot b = \sum_i a[i]b[i]$

Parameters:

Name Type Description Default
other Vec

other vector to dot with

 required

Returns:

Name Type Description
float float

the dot product

from_complex(c) classmethod

2D vector from complex number

Parameters:

Name Type Description Default
c complex
required

Returns:

Name Type Description
Vec

Vec(c.real, c.imag)

norm(which='l2')

Vector norm. Three norms are implemented: the Euclidean l2 norm, the l1 norm or the l-infinite norm:

l2 : $ \sqrt{ \sum_i v[i]^2 } $

l1 : $ \sum_i |v[i]| $

linf : $ \max_i |v[i]| $

Parameters:

Name Type Description Default
which str

which norm to compute. Choices are "l2", "l1" and "linf". Defaults to "l2".

 'l2'

Returns:

Name Type Description
float float

the vector's norm

normalize(which='l2')

Normalizes the vector to have unit norm.

Parameters:

Name Type Description Default
which str

which norm to compute. Choices are "l2", "l1" and "linf". Defaults to "l2".

 'l2'

normalized(vec, which='l2') staticmethod

Computes and returns a normalized vector of the input vector vec.

Parameters:

Name Type Description Default
vec Vec

the input vector

 required
which str

which norm to compute. Choices are "l2", "l1" and "linf". Defaults to "l2".

 'l2'

Returns:

Name Type Description
Vec

the normalized vector

outer(other)

Outer product between two vectors:

\(a \otimes b = c \in \mathbb{R}^{n \times n}\) such that \(c[i,j] = a[i]b[j]\).

Parameters:

Name Type Description Default
other Vec

the second vector

 required

Returns:

Type Description
ndarray

np.array: an array of shape (n,n)

random(n) classmethod

Generates a random vector of size n with coefficients sampled uniformly and independently in [0;1)

Parameters:

Name Type Description Default
n int

size

 required

Returns:

Name Type Description
Vec

zeros(n) classmethod

Generates a vector of size n full of zeros.

Parameters:

Name Type Description Default
n int

size

 required

Returns:

Name Type Description
Vec

VolumeMesh(data=None)

Bases: Mesh

id_cells property

Shortcut for range(len(self.cells))

id_corners property

Shortcut for range(len(self.face_corners))

id_edges property

Shortcut for range(len(self.edges))

id_faces property

Shortcut for range(len(self.faces))

id_vertices property

Shortcut for range(len(self.vertices))

is_edge_on_border(*args)

Simple test to determine if a given edge is on the boundary of the mesh.

Returns:

Name Type Description
bool bool

Returns True if the given edge is on the boundary of the mesh.

is_face_on_border(*args)

Simple test to determine if a given face is on the boundary of the mesh.

Returns:

Name Type Description
bool bool

Returns True is the given face exists and is on the boundary of the mesh

is_tetrahedral()

Returns:

Name Type Description
bool bool

True if the mesh is tetrahedral (all cells are tetrahedra)

angle_2vec2D(V1, V2)

Angle between two 2D vectors

Parameters:

Name Type Description Default
V1 Vec

first vector

 required
V2 Vec

second vector

 required

Returns:

Name Type Description
float float

the angle

angle_2vec3D(V1, V2)

Angle between two 3D vectors

Parameters:

Name Type Description Default
V1 Vec

first vector

 required
V2 Vec

second vector

 required

Returns:

Name Type Description
float float

the angle

angle_3pts(A, B, C)

Angle ABC between three points

Parameters:

Name Type Description Default
A Vec

first point

 required
B Vec

central point

 required
C Vec

second point

 required

Returns:

Name Type Description
float float

the angle

aspect_ratio(A, B, C)

Computes the aspect ratio of triangle ABC, defined as the ratio between the circumradius to twice the inradius. This ratio equals 1 for equilateral triangle and goes to zero as the triangle gets close to degenerate.

Parameters:

Name Type Description Default
A Vec

first point of the triangle

 required
B Vec

second point of the triangle

 required
C Vec

third point of the triangle

 required

Returns:

Name Type Description
float float

the aspect ratio of triangle ABC
Note

https://stackoverflow.com/a/10290011

axis_rot_from_z(v)

The (smallest) rotation to align the z axis (0,0,1) with the vector v

check_argument(argname, argvalue, expected_type, expected_values=None)

check input sanity on the argument of a function

Parameters:

Name Type Description Default
argname str

Name of the argument (for exhaustivity of error message)

 required
argvalue any

value of the argument

 required
expected_type type

expected type of the argument. If type(argvalue) does not match, will raise an InvalidArgumentTypeError

 required
expected_values list

List of possible values the argument is allowed to take. If argvalue is not in the list, will raise an InvalidArgumentValueError. Defaults to None.

 None

circumcenter(v1, v2, v3)

Circumcenter of the triangle formed by three points in space

Parameters:

Name Type Description Default
v1 Vec

first point

 required
v2 Vec

second point

 required
v3 Vec

third point

 required
Warning

Circumcenter of triangle (v1,v2,v3) may not lay inside the triangle

Returns:

Name Type Description
Vec Vec

coordinates of the circumcenter

cotan(A, B, C)

cotangent of the angle \(\hat{ABC}\) Parameters: A (Vec): point A B (Vec): point B C (Vec): point C

Returns:

Name Type Description
float float

the cotangent

cross(A, B)

Cross product of vectors A and B

Parameters:

Name Type Description Default
A Vec

Size 3 vector

 required
B Vec

Size 3 vector

 required

Returns:

Name Type Description
Vec Vec

cross product AxB

det_2x2(A, B)

Computes a 2x2 determinant

Parameters:

Name Type Description Default
A Union[complex, ndarray]

first column vector. Can also be a complex number

 required
B Union[complex, ndarray]

second column vector. Can also be a complex number

 required

Returns:

Name Type Description
float float

the determinant

det_3x3(*args)

Computes a 3x3 using the rule of Sarrus

Parameters:

Name Type Description Default
args

Either a 3x3 numpy array representing a matrix, or 3 3x1 numpy array representing three column vectors

 ()

Returns:

Name Type Description
float float

the determinant

distance(A, B, which='l2')

Distance between A and B. Three distances are implemented, the Euclidean distance l2, the Manhattan l1 distance of the l-infinity distance:

l2: \(\sqrt{(B-A)^T(B-A)} = \sqrt{\sum_i (A_i - B_i)^2}\)

l1: \(\sum_i |A_i - B_i|\)

linf: \(\max_i |A_i - B_i|\)

Parameters:

Name Type Description Default
A Vec

first point

 required
B Vec

second point

 required
which str

which norm to compute. Choices are "l2", "l1" and "linf". Defaults to "l2".

 'l2'

Returns:

Name Type Description
float float

distance

distance_to_segment2D(P, A, B)

Computes, in the plane, the distance of point P to the segment [A;B]

Parameters:

Name Type Description Default
P Vec

Query point in 2D

 required
A Vec

First segment extremity

 required
B Vec

Second segment extremity

 required

Returns:

Name Type Description
float float

the euclidean distance from P to [A;B]

dot(A, B)

dot product \(A^TB\) between two vectors

Parameters:

Name Type Description Default
A ndarray

first vector

 required
B ndarray

second vector

 required

Returns:

Name Type Description
float float

dot product

face_basis(*f)

Orthonormal basis of face Given three points A,B,C, returns a basis such that the first vector is along direction AB and third vector is normal to the plane ABC

Parameters:

Name Type Description Default
A,B,C

three points (in a list or not)

 required

Returns:

Type Description

Vec,Vec,Vec: an orthonormal 3D basis of the face

gradient(mesh, conn=None, as_complex=True)

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.

Parameters:

Name Type Description Default
mesh SurfaceMesh

The input mesh

 required
conn SurfaceConnectionFaces

Connection objects specifying local bases of faces. Will be computed if not provided. Defaults to None.

 None
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

intersect_2lines2D(p1, d1, p2, d2)

Computes the intersection of two lines in the plane

Parameters:

Name Type Description Default
p1 Vec

point on the first line

 required
d1 Vec

direction vector of the first line

 required
p2 Vec

point on the second line

 required
d2 Vec

direction vector of the second line

 required

Returns:

Name Type Description
Vec Vec

the intersection point. None if lines are parallel

match_rotation(Ra, Rb, symgroup=Rotation.create_group('O'), threshold=math.pi / 4)

Given two rotation matrices, compute the matching between the two: the minimal rotation going from Ra to s(Rb) with s in some symmetry group (most often the octahedral group for cube symmetries)

Parameters:

Name Type Description Default
symgroup Rotation)

a rotation group (given by the scipy.spatial.transform.Rotation.create_group method). Defaults to the octahedral group (24 direct symmetries of the cube)

 create_group('O')

Returns:

Name Type Description
Rotation

the minimal rotation going from Ra to Rb

norm(x, which='l2')

Vector norm. Three norms are implemented, the Euclidean l2 norm, the l1 norm or the l-infinite norm:

l2: $ \sqrt{ \sum_i v[i]^2 } $

l1: $ \sum_i |v[i]| $

linf: $ \max_i |v[i]| $

Parameters:

Name Type Description Default
x ndarray

vector from which we compute the norm. Will be flattened if it has more than one dimension.

 required
which str

which norm to compute. Choices are "l2", "l1" and "linf". Defaults to "l2".

 'l2'

Returns:

Name Type Description
float float

the vector's norm

project_to_plane(P, N, orig)

Projects vector P onto the plane of normal N and passing through point 'orig'

Parameters:

Name Type Description Default
P Vec

query position to project

 required
N Vec

normal vector of the plane

 required

Returns:

Name Type Description
Vec Vec

P projected onto the plane

quad_area(A, B, C, D)

Area of the quad ABCD

Parameters:

Name Type Description Default
A Vec

first point

 required
B Vec

second point

 required
C Vec

third point

 required
D Vec

fourth point

 required

Returns:

Name Type Description
float float

area

rotate_2d(v, angle)

Rotates a 2D vector in the plane

Parameters:

Name Type Description Default
v Vec

the vector to rotate

 required
angle float

angle of rotation in radiants

 required

Returns:

Name Type Description
Vec Vec

the rotated vector

sign(x)

\[\text{sign}(x)=\begin{cases} 0 \text{ if } x=0 \\ 1 \text{ if } x>0 \\ -1 \text{ if } x<0 \end{cases}\]

Parameters:

Name Type Description Default
x float

input number

 required

Returns:

Name Type Description
float

x/|x| and 0 for x=0

sign0(x)

\[\text{sign0}(x)=\begin{cases} 1 \text{ if } x\geqslant0 \\ -1 \text{ if } x<0 \end{cases}\]

Parameters:

Name Type Description Default
x float

input number

 required

Returns:

Name Type Description
float

the sign of x

signed_angle_2vec3D(V1, V2, N)

Signed angle between two vectors with orientation given by normal N

Parameters:

Name Type Description Default
V1 Vec

First vector

 required
V2 Vec

Second vector

 required
N Vec

reference normal direction

 required

Returns:

Name Type Description
float float

the angle

signed_angle_3pts(A, B, C, N)

Signed angle between three points ABC with orientation givne by normal N

Parameters:

Name Type Description Default
A Vec

first point

 required
B Vec

central point

 required
C Vec

second point

 required
N Vec

reference normal direction

 required

Returns:

Name Type Description
float float

the angle

triangle_area(A, B, C)

Area of 3D triangle ABC

Parameters:

Name Type Description Default
A Vec

first point

 required
B Vec

second point

 required
C Vec

third point

 required

Returns:

Name Type Description
float float

area

triangle_area_2D(A, B, C)

Area of 2D triangle ABC

Parameters:

Name Type Description Default
A Vec

first point

 required
B Vec

second point

 required
C Vec

third point

 required

Returns:

Name Type Description
float float

area