﻿---
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/latest/api-references/python/meshes/
---

# Meshes – Python API Reference – Deformable

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

The mesh classes hold their arrays in whatever form they were given; meshes the library returns hold lists of [`Vector3`](https://help.tangerina.io/deformable/latest/api-references/python/math/#vector3) ([`Vector2`](https://help.tangerina.io/deformable/latest/api-references/python/math/#vector2) for UV sets), index tuples for grouped indices such as triangles, and plain int lists for flat ones such as polygon sizes. Any object with the same attributes can stand in for a mesh class.

Array inputs, the type aliases [`Vector3Array`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector3array), [`Vector2Array`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector2array), [`IndexArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#indexarray), [`IndexGroupArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#indexgrouparray), [`ColourArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#colourarray) and [`PixelArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#pixelarray), take any of these forms:

- a sequence of groups, such as a list of (x, y, z) tuples or of [`Vector3`](https://help.tangerina.io/deformable/latest/api-references/python/math/#vector3);
- a flat sequence of numbers, group after group;
- any buffer: `array.array`, memoryview, bytes, or another object with the buffer protocol, flat or with one row per group. A contiguous buffer that already holds the C element type is copied as it is; any other is read number by number, so `array.array("f")` vertex data from Blender's `foreach_get` works as well.

A length that is not a whole number of groups raises ValueError, and so does an index or a byte out of its range; a string raises TypeError.

## TetrahedralMesh

**Data class** · `deformable.TetrahedralMesh`

```python
@dataclasses.dataclass
class TetrahedralMesh:
    positions: Vector3Array
    tetrahedrons: IndexGroupArray
```

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/latest/api-references/python/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 the `DEGENERATE_TETRAHEDRON` statuses say how such a tetrahedron fails. The tools make positive tetrahedrons, though a thick [`extrude`](https://help.tangerina.io/deformable/latest/api-references/python/tools/#extrude) shell can invert some on sharp curvature, and [`span_layers`](https://help.tangerina.io/deformable/latest/api-references/python/tools/#span_layers) keeps the flat tetrahedrons of layers that touch.

**Fields**

- `positions` ([`Vector3Array`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector3array)): The node positions.
- `tetrahedrons` ([`IndexGroupArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#indexgrouparray)): The four node indices of each tetrahedron.

**Example**

```python
# One positive tetrahedron: its corners are left-handed.
single = deformable.TetrahedralMesh(
    [(0, 0, 0), (1, 0, 0), (0, 0, 1), (0, 1, 0)], [(0, 1, 2, 3)]
)
scene.add_object(single, material)
# 1
```

**See also** [Guide: Mesh classes](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#mesh-classes) · [C `DeformableTetrahedralMesh`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformabletetrahedralmesh) · [C `DeformableTetrahedralMeshView`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformabletetrahedralmeshview) · [Rust `TetrahedralMesh`](https://help.tangerina.io/deformable/latest/api-references/rust/meshes/#tetrahedralmesh)

## TriangleMesh

**Data class** · `deformable.TriangleMesh`

```python
@dataclasses.dataclass
class TriangleMesh:
    positions: Vector3Array
    triangles: IndexGroupArray
```

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

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

**Fields**

- `positions` ([`Vector3Array`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector3array)): The vertex positions.
- `triangles` ([`IndexGroupArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#indexgrouparray)): The three vertex indices of each triangle.

**Example**

```python
# One triangle, counter-clockwise seen from +z, its normal side.
triangle = deformable.TriangleMesh(
    [(0, 0, 0), (1, 0, 0), (0, 1, 0)], [(0, 1, 2)]
)
prism = deformable.extrude(triangle, 0.1)
len(prism.tetrahedrons)
# 3
```

**See also** [Guide: Mesh classes](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#mesh-classes) · [C `DeformableTriangleMesh`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformabletrianglemesh) · [C `DeformableTriangleMeshView`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformabletrianglemeshview) · [Rust `TriangleMesh`](https://help.tangerina.io/deformable/latest/api-references/rust/meshes/#trianglemesh)

## PolygonMesh

**Data class** · `deformable.PolygonMesh`

```python
@dataclasses.dataclass
class PolygonMesh:
    positions: Vector3Array
    polygon_sizes: IndexArray
    polygon_vertices: IndexArray
```

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/latest/api-references/python/meshes/#facehole) names each hole run.

**Fields**

- `positions` ([`Vector3Array`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector3array)): The vertex positions.
- `polygon_sizes` ([`IndexArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#indexarray)): The number of corners of each polygon.
- `polygon_vertices` ([`IndexArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#indexarray)): The vertex index of each corner, polygon after polygon.

**Example**

```python
# The cube's bottom and top faces: the corners of one quad, then
# those of the other.
faces = deformable.PolygonMesh(
    polygons.positions, [4, 4], [0, 2, 3, 1, 4, 5, 7, 6]
)
parameters = deformable.TriangulateParameters.default(
    closed_boundary=False
)
result = deformable.triangulate(faces, parameters=parameters)
```

**See also** [Guide: Mesh classes](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#mesh-classes) · [C `DeformablePolygonMesh`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformablepolygonmesh) · [C `DeformablePolygonMeshView`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformablepolygonmeshview) · [Rust `PolygonMesh`](https://help.tangerina.io/deformable/latest/api-references/rust/meshes/#polygonmesh)

## FaceHole

**Named tuple** · `deformable.FaceHole`

```python
class FaceHole(NamedTuple):
    face: int
    first_corner: int
    corner_count: int
```

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/latest/api-references/python/tools/#triangulate) and [`verify_surface`](https://help.tangerina.io/deformable/latest/api-references/python/mesh-checks/#verify_surface) take a list of them, and a polygon that none of them names has no hole.

**Fields**

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

**Example**

```python
# 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.
outline = [(0, 0, 0), (3, 0, 0), (3, 3, 0), (0, 3, 0)]
hole = [(1, 1, 0), (1, 2, 0), (2, 2, 0), (2, 1, 0)]
frame = deformable.PolygonMesh(outline + hole, [8], range(8))
holes = [deformable.FaceHole(face=0, first_corner=4, corner_count=4)]
parameters = deformable.TriangulateParameters.default(
    closed_boundary=False
)
result = deformable.triangulate(frame, holes, parameters)
```

**See also** [Guide: Triangulate a polygon mesh](https://help.tangerina.io/deformable/latest/user-guides/python/tools/#triangulate-a-polygon-mesh) · [C `DeformableFaceHole`](https://help.tangerina.io/deformable/latest/api-references/c/meshes/#deformablefacehole) · [Rust `FaceHole`](https://help.tangerina.io/deformable/latest/api-references/rust/meshes/#facehole)

## SurfaceMesh

**Data class** · `deformable.SurfaceMesh`

```python
@dataclasses.dataclass
class SurfaceMesh:
    mesh: PolygonMesh
    normals: Vector3Array = ()
    uv_sets: Sequence[Vector2Array] = ()
    colours: ColourArray = ()
```

A render surface: a polygon mesh with per-corner channels, the normals, UV sets and colours that [`embed_surface`](https://help.tangerina.io/deformable/latest/api-references/python/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 package raises ValueError for a set of another length before it calls the library.

**Fields**

- `mesh` ([`PolygonMesh`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#polygonmesh)): The positions and polygons.
- `normals` ([`Vector3Array`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector3array)): The normal of each corner, or none. Default `()`.
- `uv_sets` ([`Sequence[Vector2Array]`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#vector2array)): The UV sets, each with one coordinate pair per corner. Default `()`.
- `colours` ([`ColourArray`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#colourarray)): The red, green, blue and alpha of each corner, or none. Default `()`.

**Example**

```python
# Each quad of the cube mapped onto the unit square in one UV set.
square = [(0, 0), (1, 0), (1, 1), (0, 1)]
surface = deformable.SurfaceMesh(polygons, uv_sets=[square * 6])
deformable.verify_surface(surface)
# []
```

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

## Vector3Array

**Type alias** · `deformable.Vector3Array`

```python
Vector3Array = Union[Sequence[Sequence[float]], Sequence[float], Buffer]
```

Points or vectors of three floats, x, y and z: [`Vector3`](https://help.tangerina.io/deformable/latest/api-references/python/math/#vector3) values or other groups of three, a flat sequence of numbers, or a buffer, read as doubles.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## Vector2Array

**Type alias** · `deformable.Vector2Array`

```python
Vector2Array = Union[Sequence[Sequence[float]], Sequence[float], Buffer]
```

Pairs of floats, such as the UV coordinates of the corners: [`Vector2`](https://help.tangerina.io/deformable/latest/api-references/python/math/#vector2) values or other pairs, a flat sequence of numbers, or a buffer, read as doubles.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## IndexArray

**Type alias** · `deformable.IndexArray`

```python
IndexArray = Union[Sequence[int], Buffer]
```

Unsigned 32-bit integers, such as vertex indices or counts: a flat sequence or a buffer. Each must be 0 or more and fit in 32 bits.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## IndexGroupArray

**Type alias** · `deformable.IndexGroupArray`

```python
IndexGroupArray = Union[Sequence[Sequence[int]], Sequence[int], Buffer]
```

Groups of unsigned 32-bit indices, as many per group as the attribute says, such as 4 per tetrahedron or 3 per triangle: tuples of indices, a flat sequence, or a buffer. Each must be 0 or more and fit in 32 bits.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## ColourArray

**Type alias** · `deformable.ColourArray`

```python
ColourArray = Union[Sequence[Sequence[float]], Sequence[float], Buffer]
```

Colours of four floats, red, green, blue and alpha: (red, green, blue, alpha) tuples, a flat sequence of numbers, or a buffer, read as doubles.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## PixelArray

**Type alias** · `deformable.PixelArray`

```python
PixelArray = Union[Sequence[Sequence[int]], Sequence[int], Buffer]
```

Pixels of three bytes, red, green and blue, each from 0 to 255: (red, green, blue) triples, a flat sequence such as bytes, or a buffer.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## Buffer

**Type alias** · `deformable.Buffer`

```python
Buffer = Any
```

Any object with the buffer protocol, such as `array.array`, memoryview, bytes or a NumPy array. Python 3.9 has no type for it, so a type checker takes any value here.

**See also** [Guide: Array forms](https://help.tangerina.io/deformable/latest/user-guides/python/types-and-errors/#array-forms)

## face_corners

**Function** · `deformable.face_corners`

```python
def face_corners(face: int) -> tuple[int, int, int]
```

The three local corners (0 to 3) of one face of a tetrahedron: the face opposite corner `face`.

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 `face`. The face bits of [`FaceEvent`](https://help.tangerina.io/deformable/latest/api-references/python/scene/#faceevent) and of [`boundary_faces`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#boundary_faces) number the faces this way.

**Parameters**

- `face` (`int`): The face, 0 to 3: the face opposite that corner.

**Returns**

`tuple[int, int, int]`: The three corners of the face, in the order above.

**Raises**

[`DeformableError`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#deformableerror) with one of these statuses:

- [`INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-index_out_of_range): `face` is above 3.

`ValueError` when `face` is negative or does not fit in 32 bits.

**Example**

```python
# Face 1 is the face opposite corner 1.
deformable.face_corners(1)
# (0, 3, 2)
```

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

## boundary_faces

**Function** · `deformable.boundary_faces`

```python
def boundary_faces(mesh: TetrahedralMesh) -> list[int]
```

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/latest/api-references/python/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/latest/api-references/python/meshes/#tetrahedralmesh)): The tetrahedral mesh, such as the rest mesh of an object.

**Returns**

`list[int]`: One mask per tetrahedron, in mesh order: bit k stands for face k, as [`face_corners`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#face_corners) numbers the faces.

**Raises**

[`DeformableError`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#deformableerror) with one of these statuses:

- [`EMPTY_MESH`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-empty_mesh): The mesh has no tetrahedron.
- [`INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-index_out_of_range): A tetrahedron uses a node index past the end of the positions.
- [`NON_FINITE_VALUE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-non_finite_value): A position is NaN or infinite.
- [`NON_MANIFOLD_FACE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-non_manifold_face): Three or more tetrahedrons share one face.

`ValueError` when the positions or tetrahedrons of `mesh` do not form whole groups of three and four numbers, or a node index is negative or does not fit in 32 bits.

**Example**

```python
masks = deformable.boundary_faces(mesh)
# The 12 triangles of the cage are the outer faces of its mesh.
sum(bin(mask).count("1") for mask in masks)
# 12
```

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