﻿---
title: Meshes
description: The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
url: https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/
---

# Meshes – Rust API Reference – Deformable v0.4.1

The meshes the tools and the scene take and return: a [`TetrahedralMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#tetrahedralmesh) for each simulated object, a [`TriangleMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#trianglemesh) or a [`PolygonMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#polygonmesh) for cages, and a [`SurfaceMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#surfacemesh) for the surface a host renders. The faces of a tetrahedron come last.

## TetrahedralMesh

**Struct** · `deformable::mesh::TetrahedralMesh`

```rust
pub struct TetrahedralMesh {
    pub positions: Vec<Vector3>,
    pub tetrahedrons: Vec<[u32; 4]>,
}
```

A tetrahedral mesh: shared node positions and four node indices per tetrahedron, positively oriented
(left-handed).

With corners X0 to X3 and `ei = Xi - X0`, a tetrahedron is positive when `-e1 · (e2 × e3)` is above 0, and
swapping two corners turns a right-handed tetrahedron positive.
[`Scene::add_object`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#scene-add_object) asks for more: it refuses a mesh with a
tetrahedron whose value, in simulation units, is not above 1e-9, and [`DegenerateKind`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/mesh-checks/#degeneratekind)
says how such a tetrahedron fails. The tools make positive tetrahedrons, though a thick
[`extrude`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/tools/#extrude) shell can invert some on sharp curvature, and
[`span_layers`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/tools/#span_layers) keeps the flat tetrahedrons of layers that touch.

**Fields**

- `positions` ([`Vec<Vector3>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#vector3)): The node positions.
- `tetrahedrons` (`Vec<[u32; 4]>`): The four node indices of each tetrahedron.

**Implements** `Clone` · `Debug` · `Default` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// One positive tetrahedron: its corners are left-handed.
let single = TetrahedralMesh {
    positions: vec![Vector3::ZERO, Vector3::X, Vector3::Z, Vector3::Y],
    tetrahedrons: vec![[0, 1, 2, 3]],
};
let materials = TetrahedronMaterials::Uniform(material);
scene.add_object(&single, materials, ObjectOptions::default())?;
```

**See also** [Guide: The crate](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/getting-started/#the-crate) · [C `DeformableTetrahedralMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformabletetrahedralmesh) · [C `DeformableTetrahedralMeshView`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformabletetrahedralmeshview) · [Python `TetrahedralMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#tetrahedralmesh)

### TetrahedralMesh::validate

**Method** · `deformable::mesh::TetrahedralMesh::validate`

```rust
pub fn validate(&self) -> Result<(), Error>
```

Checks that the mesh has tetrahedrons, that every node index is in range and that every position is finite,
and returns the first failure in that order.

[`Scene::add_object`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#scene-add_object), [`boundary_faces`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#boundary_faces)
and [`meshes_intersect`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/mesh-checks/#meshes_intersect) run the same checks;
`add_object` checks the material count before them, and runs them on the positions in simulation units. The
orientation of the tetrahedrons is not checked. The checks run in the crate, without calling the library.

**Errors**

- [`EmptyMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-emptymesh): The mesh has no tetrahedron.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-indexoutofrange): A tetrahedron uses a node index past the end of the positions.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonfinitevalue): A position is NaN or infinite.

## TriangleMesh

**Struct** · `deformable::tools::TriangleMesh`

```rust
pub struct TriangleMesh {
    pub positions: Vec<Vector3>,
    pub triangles: Vec<[u32; 3]>,
}
```

A triangle mesh: shared vertex positions and three vertex indices per triangle.

A closed cage, as [`tetrahedralize`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/tools/#tetrahedralize) takes, lists the corners of each triangle
counter-clockwise as seen from outside, so its normals point outward.

**Fields**

- `positions` ([`Vec<Vector3>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#vector3)): The vertex positions.
- `triangles` (`Vec<[u32; 3]>`): The three vertex indices of each triangle.

**Implements** `Clone` · `Debug` · `Default` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// One triangle, counter-clockwise seen from +z, its normal side.
let triangle = TriangleMesh {
    positions: vec![Vector3::ZERO, Vector3::X, Vector3::Y],
    triangles: vec![[0, 1, 2]],
};
let prism = extrude(&triangle, 0.1, ExtrudeDirection::Up)?;
assert_eq!(prism.tetrahedrons.len(), 3);
```

**See also** [Guide: The crate](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/getting-started/#the-crate) · [C `DeformableTriangleMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformabletrianglemesh) · [C `DeformableTriangleMeshView`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformabletrianglemeshview) · [Python `TriangleMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#trianglemesh)

## PolygonMesh

**Struct** · `deformable::mesh::PolygonMesh`

```rust
pub struct PolygonMesh {
    pub positions: Vec<Vector3>,
    pub polygon_sizes: Vec<u32>,
    pub polygon_vertices: Vec<u32>,
}
```

A polygon mesh as a host stores it: shared positions, the corner count of each polygon, and the vertex of every
corner, polygon after polygon.

A closed mesh lists the corners of each polygon counter-clockwise as seen from outside, so its normals point
outward. A polygon with holes lists its outer loop first, then each hole loop, and a
[`FaceHole`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#facehole) names each hole run.

**Fields**

- `positions` ([`Vec<Vector3>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#vector3)): The vertex positions.
- `polygon_sizes` (`Vec<u32>`): The number of corners of each polygon.
- `polygon_vertices` (`Vec<u32>`): The vertex index of each corner, polygon after polygon.

**Implements** `Clone` · `Debug` · `Default` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// The cube's bottom and top faces: the corners of one quad, then
// those of the other.
let faces = PolygonMesh {
    positions: polygons.positions.clone(),
    polygon_sizes: vec![4, 4],
    polygon_vertices: vec![0, 2, 3, 1, 4, 5, 7, 6],
};
assert_eq!(faces.polygons().nth(1), Some(&[4, 5, 7, 6][..]));
```

**See also** [Guide: The crate](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/getting-started/#the-crate) · [C `DeformablePolygonMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformablepolygonmesh) · [C `DeformablePolygonMeshView`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformablepolygonmeshview) · [Python `PolygonMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#polygonmesh)

### PolygonMesh::validate

**Method** · `deformable::mesh::PolygonMesh::validate`

```rust
pub fn validate(&self) -> Result<(), Error>
```

Checks that the polygon sizes add up to the corner count, that every vertex index is in range and that every
position is finite, and returns the first failure in that order.

A mesh with no polygons passes. The polygons' shapes are not checked: a polygon of fewer than 3 corners passes
too. The checks run in the crate, without calling the library.

**Errors**

- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-lengthmismatch): The polygon sizes do not add up to the length of `polygon_vertices`.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-indexoutofrange): A corner names a vertex past the end of the positions.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonfinitevalue): A position is NaN or infinite.

### PolygonMesh::polygons

**Method** · `deformable::mesh::PolygonMesh::polygons`

```rust
pub fn polygons(&self) -> impl Iterator<Item = &[u32]>
```

The corners of each polygon, in polygon order. On a mesh whose sizes add up to more corners than it has, the
polygons end before the first one that runs past the last corner.

## FaceHole

**Struct** · `deformable::tools::FaceHole`

```rust
pub struct FaceHole {
    pub face: u32,
    pub first_corner: u32,
    pub corner_count: u32,
}
```

A run of a polygon's corners that forms one hole loop; the corners before the polygon's first hole form its outer
loop.

[`triangulate`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/tools/#triangulate) and [`verify_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/mesh-checks/#verify_surface) take a list of them, and a
polygon that none of them names has no hole.

**Fields**

- `face` (`u32`): The index of the polygon that holds the hole.
- `first_corner` (`u32`): The run's first corner, counted from the polygon's first corner.
- `corner_count` (`u32`): The number of corners in the run.

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// A 3 by 3 square around a 1 by 1 hole: corners 0 to 3 of polygon 0
// are its outer loop, and corners 4 to 7 its hole loop.
let holes = [FaceHole { face: 0, first_corner: 4, corner_count: 4 }];
let parameters = TriangulateParameters {
    closed_boundary: false,
    ..TriangulateParameters::default()
};
let result = triangulate(&frame, &holes, &parameters, None)?;
```

**See also** [Guide: A polygon with a hole](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/tools/#a-polygon-with-a-hole) · [C `DeformableFaceHole`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformablefacehole) · [Python `FaceHole`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#facehole)

## SurfaceMesh

**Struct** · `deformable::tools::SurfaceMesh`

```rust
pub struct SurfaceMesh {
    pub mesh: PolygonMesh,
    pub normals: Vec<Vector3>,
    pub uv_sets: Vec<Vec<Vector2>>,
    pub colours: Vec<[f64; 4]>,
}
```

A render surface: a polygon mesh with per-corner channels, the normals, UV sets and colours that
[`embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#embed_surface) carries through its clip.

Each channel is empty or holds one entry per corner, in the order of the mesh's `polygon_vertices`. Every UV set
holds one pair per corner: the library reads the sets one after the other, so the crate refuses a set of another
length with [`ErrorKind::LengthMismatch`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-lengthmismatch) before it calls the library. `SurfaceMesh::default()` has no polygons
and no channels.

**Fields**

- `mesh` ([`PolygonMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#polygonmesh)): The positions and polygons.
- `normals` ([`Vec<Vector3>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#vector3)): The normal of each corner, or none.
- `uv_sets` ([`Vec<Vec<Vector2>>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#vector2)): The UV sets, each with one coordinate pair per corner.
- `colours` (`Vec<[f64; 4]>`): The red, green, blue and alpha of each corner, or none.

**Implements** `Clone` · `Debug` · `Default` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// Each quad of the cube mapped onto the unit square in one UV set.
let square = [[0.0, 0.0], [1.0, 0.0], [1.0, 1.0], [0.0, 1.0]];
let surface = SurfaceMesh {
    mesh: polygons,
    uv_sets: vec![square.map(|[u, v]| Vector2::new(u, v)).repeat(6)],
    ..SurfaceMesh::default()
};
surface.validate()?;
```

**See also** [Guide: Describe the render surface](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#describe-the-render-surface) · [C `DeformableSurfaceMeshView`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformablesurfacemeshview) · [Python `SurfaceMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#surfacemesh)

### SurfaceMesh::corner_count

**Method** · `deformable::tools::SurfaceMesh::corner_count`

```rust
pub fn corner_count(&self) -> usize
```

The number of corners, the length of every channel that is not empty.

### SurfaceMesh::validate

**Method** · `deformable::tools::SurfaceMesh::validate`

```rust
pub fn validate(&self) -> Result<(), Error>
```

Checks the polygon sizes against the corners and the channel lengths, then the vertex indices, then that every
value is finite, and returns the first failure in that order. The checks run in the crate, without calling
the library.

**Errors**

- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-lengthmismatch): The polygon sizes do not add up to the corner count, the normals or colours
  are neither empty nor one per corner, a UV set does not hold one pair per corner, or the mesh has more than
  `i32::MAX` polygons.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-indexoutofrange): A corner names a vertex past the end of the positions.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonfinitevalue): A position, normal, UV or colour value is NaN or infinite.

## FACES

**Constant** · `deformable::mesh::FACES`

```rust
pub const FACES: [[usize; 3]; 4] =
    [[1, 2, 3], [0, 3, 2], [0, 1, 3], [0, 2, 1]];
```

The three local corners (0 to 3) of each face of a tetrahedron: `FACES[k]` holds those of face k, the face
opposite corner k.

Seen from outside a positively oriented (left-handed) tetrahedron, the corners of each face run clockwise: with
corners a, b and c in that order, `(b - a) × (c - a)` points into the tetrahedron, toward corner k. The face bits of
[`FaceEvent`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#faceevent) and of [`boundary_faces`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#boundary_faces) number the faces this
way.

**Example**

```rust
// Face 1 is the face opposite corner 1.
assert_eq!(FACES[1], [0, 3, 2]);
```

**See also** [Guide: Tetrahedron faces](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/tools/#tetrahedron-faces) · [C `deformable_face_corners`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformable_face_corners) · [Python `face_corners`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#face_corners)

## boundary_faces

**Function** · `deformable::mesh::boundary_faces`

```rust
pub fn boundary_faces(mesh: &TetrahedralMesh) -> Result<Vec<u8>, Error>
```

The outer faces of each tetrahedron of a mesh, as one mask per tetrahedron: bit k is set when no other
tetrahedron shares face k, the face opposite corner k.

The masks depend only on which tetrahedrons share faces, not on the positions, so a host computes them once from
an object's rest mesh and can set them in its own per-tetrahedron output flags. The exposed faces of a
[`FaceEvent`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#faceevent) include them: clear them from it to keep only the faces a fracture
opened. The orientation of the tetrahedrons is not checked.

**Parameters**

- `mesh` ([`&TetrahedralMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#tetrahedralmesh)): The tetrahedral mesh, such as the rest mesh of an object.

**Returns**

`Vec<u8>`: One mask per tetrahedron, in mesh order: bit k stands for face k, as [`FACES`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#faces) numbers the faces.

**Errors**

- [`EmptyMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-emptymesh): The mesh has no tetrahedron.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-indexoutofrange): A tetrahedron uses a node index past the end
  of the positions.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonfinitevalue): A position is NaN or infinite.
- [`NonManifoldFace`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonmanifoldface): Three or more tetrahedrons share one face.

**Example**

```rust
let masks = boundary_faces(&mesh)?;
// The 12 triangles of the cage are the outer faces of its mesh.
let outer: u32 = masks.iter().map(|mask| mask.count_ones()).sum();
assert_eq!(outer, 12);
```

**See also** [Guide: Tetrahedron faces](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/tools/#tetrahedron-faces) · [C `deformable_boundary_faces`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/meshes/#deformable_boundary_faces) · [Python `boundary_faces`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/meshes/#boundary_faces)
