﻿---
title: Render surfaces
description: Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
url: https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/
---

# Render surfaces – Python API Reference – Deformable

A render surface is the mesh a host draws. [`embed_surface`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#embed_surface) prepares it once against the rest mesh of an object, and the [`SurfaceEmbedding`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#surfaceembedding) it returns deforms it with the simulated nodes every frame. A breakable surface gets inner faces, which lie on tetrahedron faces inside the object and stay hidden until a crack exposes them. With a splinter cage it takes the splinter path instead: it is cut into bricks, one per cell of the cage, and caps close the cuts.

## ClipMode

**Enum** · `deformable.ClipMode`

```python
class ClipMode(enum.IntEnum):
    ASSIGN_ONLY = 0
    CLIP_WITH_INNER_FACES = 2
    TETRAHEDRAL_MESH_BOUNDARY = 3
```

How [`embed_surface`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#embed_surface) prepares a render surface against the rest mesh: whether it cuts the surface along the tetrahedron faces, and which inner faces it adds.

An inner face lies on a tetrahedron face inside the object, hidden until a crack exposes it. With a splinter cage ([`PreparationParameters.splinter_cage`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#preparationparameters)), the two modes other than `ASSIGN_ONLY` take the splinter path instead. The values are the library's codes.

**Values**

- `ASSIGN_ONLY` (`0`): Each vertex follows the tetrahedron it lies in, or the nearest one by its weights when it lies outside the mesh; nothing is cut and no inner face is made. For objects that bend but never break.
- `CLIP_WITH_INNER_FACES` (`2`): Breakable: the surface is cut along the tetrahedron faces, and the part of each interior tetrahedron face inside the surface becomes an inner face. A polygon wholly outside the mesh is kept whole on the nearest tetrahedron by its weights.
- `TETRAHEDRAL_MESH_BOUNDARY` (`3`): The tetrahedral mesh is the surface: each polygon follows the tetrahedron its centre lies in, uncut, and every interior tetrahedron face becomes an inner face. For showing the tetrahedrons themselves.

**See also** [Guide: Choose how to prepare it](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#choose-how-to-prepare-it) · [C `DeformableClipMode`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformableclipmode) · [Rust `ClipMode`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#clipmode)

## PreparationParameters

**Data class** · `deformable.PreparationParameters`

```python
@dataclasses.dataclass(frozen=True)
class PreparationParameters:
    clip_mode: ClipMode | int
    uv_scale: float
    splinter_cage: PolygonMesh | None = None
```

The settings of [`embed_surface`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#embed_surface): how it cuts the surface, the scale of the planar UVs it makes, and an optional splinter cage.

**Fields**

- `clip_mode` ([`ClipMode`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#clipmode) or `int`): How the surface is cut, and which inner faces it gets. An int that is no member's value makes [`embed_surface`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#embed_surface) raise [`DeformableError`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#deformableerror) with the status [`INVALID_ARGUMENT`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-invalid_argument), and one that does not fit in 32 bits ValueError.
- `uv_scale` (`float`): Scale of the planar UVs of inner and cap faces; the random offsets of inner faces are not scaled. 1 is a good start.
- `splinter_cage` ([`PolygonMesh`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#polygonmesh) or `None`): The splinter cage in the surface's space, already moved by the host's splinter transform, or None. With vertices and a clip mode other than [`ASSIGN_ONLY`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#clipmode-assign_only), the surface takes the splinter path: it is cut into one brick per cage cell, and the cuts are capped. When no cell holds a part of the surface, the surface is prepared as without a cage. [`ASSIGN_ONLY`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#clipmode-assign_only) ignores the cage, but its polygons are still checked. Default `None`.

**Example**

```python
# A surface that bends with the object but never breaks.
parameters = deformable.PreparationParameters(
    deformable.ClipMode.ASSIGN_ONLY, uv_scale=1.0
)
surface = deformable.SurfaceMesh(polygons)
with deformable.embed_surface(mesh, surface, parameters) as embedding:
    len(embedding.arrays().surface.mesh.positions)
# 8
```

**See also** [Guide: Choose how to prepare it](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#choose-how-to-prepare-it) · [C `DeformablePreparationParameters`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformablepreparationparameters) · [Rust `PreparationParameters`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#preparationparameters)

## SkinningOptions

**Data class** · `deformable.SkinningOptions`

```python
@dataclasses.dataclass(frozen=True)
class SkinningOptions:
    show_inner_faces: bool = False
    start_splintered: bool = False
```

The per-frame skinning options: which hidden faces [`SurfaceEmbedding.deform`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#surfaceembedding-deform) shows. `SkinningOptions()` turns both off, as deform does when it gets None.

**Fields**

- `show_inner_faces` (`bool`): Shows every inner face and cap, exposed or not, so no face is hidden: useful to inspect the preparation. Default `False`.
- `start_splintered` (`bool`): With splinter data, shows the caps from the start instead of once a tetrahedron of theirs is flagged, as for an object that starts out split. Default `False`.

**Example**

```python
clip = deformable.ClipMode.CLIP_WITH_INNER_FACES
parameters = deformable.PreparationParameters(clip, uv_scale=1.0)
surface = deformable.SurfaceMesh(polygons)
embedding = deformable.embed_surface(mesh, surface, parameters)
states = scene.tetrahedron_states(object)
# Every inner face shown, to inspect the preparation.
options = deformable.SkinningOptions(show_inner_faces=True)
deformed = embedding.deform(states, deformable.IDENTITY, options)
sum(deformed.hidden_faces)
# 0
```

**See also** [Guide: Skin it every frame](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#skin-it-every-frame) · [C `DeformableSkinningOptions`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformableskinningoptions) · [Rust `SkinningOptions`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#skinningoptions)

## DeformedSurface

**Data class** · `deformable.DeformedSurface`

```python
@dataclasses.dataclass(frozen=True)
class DeformedSurface:
    positions: array.array
    normals: array.array
    hidden_faces: array.array
```

A skinned surface in the object space of the host's shape: 32-bit float positions per output vertex, unit 32-bit float normals per corner (empty when the surface has none) and the faces to hide.

[`SurfaceEmbedding.deform`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#surfaceembedding-deform) returns a new one every call. Its fields are flat arrays a host hands to its mesh API as they are: Blender's `foreach_set` takes them without a per-item conversion.

**Fields**

- `positions` (`array.array`): x, y and z of the deformed position of each output vertex, mapped by the inverse world transform, flat 32-bit floats (`array("f")`).
- `normals` (`array.array`): x, y and z of the deformed normal of each corner, `embed(p + n) - embed(p)` mapped by the linear part of the inverse world transform and made unit length, a zero vector left zero, flat 32-bit floats (`array("f")`); empty when the surface has no normals.
- `hidden_faces` (`array.array`): 1 for each face the host hides (an inner face or cap not shown yet), 0 for the others (`array("b")`).

**See also** [Guide: Skin it every frame](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#skin-it-every-frame) · [C `DeformableDeformedSurface`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformabledeformedsurface) · [C `DeformableDeformedSurfaceView`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformabledeformedsurfaceview) · [Rust `DeformedSurface`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#deformedsurface)

## SurfaceEmbedding

**Class** · `deformable.SurfaceEmbedding`

```python
class SurfaceEmbedding
```

A prepared surface in rest space, made by [`embed_surface`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#embed_surface): the output surface, the tetrahedron and barycentric weights each output vertex follows, the flag word of each corner, the weights of the corner normals, and on the splinter path each vertex's cell tetrahedron.

An input vertex becomes one output vertex for each flag word and tetrahedron among its corners, so the surface can open along the cracks. A vertex outside the rest mesh follows the nearest tetrahedron by its weights (the one whose smallest barycentric weight is largest), with weights that extrapolate. Reading and skinning never change the embedding, so several threads may use one embedding at the same time.

It works as a context manager: a `with` block calls `close()` when it ends.

**See also** [Guide: Read the prepared surface](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#read-the-prepared-surface) · [C `DeformableSurfaceEmbedding`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformablesurfaceembedding) · [Rust `SurfaceEmbedding`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#surfaceembedding)

### SurfaceEmbedding.arrays

**Method** · `deformable.SurfaceEmbedding.arrays`

```python
def arrays(self) -> SurfaceEmbeddingArrays
```

A copy of the embedding's arrays: the prepared surface in rest space, the flag word of each corner, the source face of each face, and the tetrahedron and weights each vertex follows. Later calls leave the copy as it is.

**Raises**

`ValueError` when the embedding is closed.

**See also** [C `deformable_surface_embedding_view`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformable_surface_embedding_view)

### SurfaceEmbedding.deform

**Method** · `deformable.SurfaceEmbedding.deform`

```python
def deform(
    self,
    states: Sequence[TetrahedronState],
    world_transform: AffineTransform,
    options: SkinningOptions | None = None,
) -> DeformedSurface
```

Skins the surface on the current tetrahedron states, in the object space of the host's shape: positions and unit normals in 32-bit floats, mapped by the inverse of `world_transform`, and the faces to hide.

Each output vertex follows its tetrahedron by its weights. On the splinter path it switches to its cell tetrahedron once its cell has broken loose: once that tetrahedron or its own has a state flag word other than 0, or the two sit in different islands. Each corner normal is mapped by the linear part of the inverse, then made unit length; a zero one stays zero. A face is hidden while it is an inner face whose tetrahedron face no fracture has exposed, or a cap whose brick tetrahedron and the own tetrahedron of its first corner both still have a state flag word of 0, unless `options` say to show it. The states are not checked: a NaN or infinite corner gives NaN or infinite positions. Skinning never changes the embedding, so several threads may skin one embedding at the same time.

**Parameters**

- `states` ([`Sequence[TetrahedronState]`](https://help.tangerina.io/deformable/latest/api-references/python/scene/#tetrahedronstate)): The object's tetrahedron states this frame, one per rest tetrahedron, as [`Scene.tetrahedron_states`](https://help.tangerina.io/deformable/latest/api-references/python/scene/#scene-tetrahedron_states) gives them.
- `world_transform` ([`AffineTransform`](https://help.tangerina.io/deformable/latest/api-references/python/math/#affinetransform)): The world matrix of the host's shape; [`IDENTITY`](https://help.tangerina.io/deformable/latest/api-references/python/math/#identity) when the surface is in world space.
- `options` ([`SkinningOptions`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#skinningoptions) or `None`): Which hidden faces to show; None takes [`SkinningOptions()`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#skinningoptions), which shows none.

**Returns**

[`DeformedSurface`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#deformedsurface): The skinned surface, as new arrays.

**Raises**

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

- [`LENGTH_MISMATCH`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-length_mismatch): `states` does not hold one state per tetrahedron of the rest mesh.
- [`NON_FINITE_VALUE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-non_finite_value): An entry of `world_transform` is NaN or infinite.
- [`SINGULAR_TRANSFORM`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-singular_transform): `world_transform` has no inverse: the determinant of its linear part is 0, or the inverse overflows.

`ValueError` when the embedding is closed, the linear part of `world_transform` does not hold three rows of three numbers, or its translation or a corner of a state does not hold three numbers.

**Example**

```python
clip = deformable.ClipMode.ASSIGN_ONLY
parameters = deformable.PreparationParameters(clip, uv_scale=1.0)
surface = deformable.SurfaceMesh(polygons)
embedding = deformable.embed_surface(mesh, surface, parameters)
# Every frame, after the step:
states = scene.tetrahedron_states(object)
deformed = embedding.deform(states, deformable.IDENTITY)
len(deformed.positions) // 3, len(deformed.hidden_faces)
# (8, 6)
```

**See also** [Guide: Skin it every frame](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#skin-it-every-frame) · [C `deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformable_surface_embedding_deform) · [Rust `SurfaceEmbedding::deform`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#surfaceembedding-deform)

### SurfaceEmbedding.closed

**Property** · `deformable.SurfaceEmbedding.closed`

```python
@property
def closed(self) -> bool
```

True once the handle has been destroyed.

### SurfaceEmbedding.close

**Method** · `deformable.SurfaceEmbedding.close`

```python
def close(self) -> None
```

Destroys the handle once the calls in flight on it end; later calls on the object raise ValueError. Closing twice does nothing.

**See also** [C `deformable_surface_embedding_destroy`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformable_surface_embedding_destroy)

## SurfaceEmbeddingArrays

**Data class** · `deformable.SurfaceEmbeddingArrays`

```python
@dataclasses.dataclass(frozen=True)
class SurfaceEmbeddingArrays:
    surface: SurfaceMesh
    corner_flags: list[int]
    source_faces: list[int]
    vertex_tetrahedrons: list[int]
    vertex_weights: list[tuple[float, float, float, float]]
    normal_weights: list[tuple[float, float, float, float]]
    brick_tetrahedrons: list[int]
    vertex_cell_tetrahedrons: list[int]
```

A copy of the arrays of a surface embedding, as [`SurfaceEmbedding.arrays`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#surfaceembedding-arrays) gives it.

**Fields**

- `surface` ([`SurfaceMesh`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#surfacemesh)): The prepared surface in rest space: output vertices, polygons and per-corner channels. It can have more vertices than the input, as a vertex is split where a crack can open; with [`ClipMode.ASSIGN_ONLY`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#clipmode-assign_only) it keeps one vertex per input vertex a polygon uses. Build the render mesh from it once.
- `corner_flags` (`list[int]`): The flag word of each corner of `surface`, in corner order: bits 0 to 28 the controlling tetrahedron, bits 29 and 30 the tetrahedron face of an inner face, bit 31 set on the corners of inner faces. On the splinter path, the tetrahedron is that of the corner's brick, the face bits are not set, and bit 31 marks the corners of caps.
- `source_faces` (`list[int]`): The input face each output face was cut from, in face order; -1 for inner faces and caps.
- `vertex_tetrahedrons` (`list[int]`): The controlling tetrahedron of each output vertex, the one it follows.
- `vertex_weights` (`list[tuple[float, float, float, float]]`): The barycentric weights of each output vertex in its tetrahedron; some are negative for a vertex outside it.
- `normal_weights` (`list[tuple[float, float, float, float]]`): The barycentric weights of `p + n` for each corner, the tip of its normal `n` at its position `p`, in its vertex's tetrahedron; empty when the surface has no normals.
- `brick_tetrahedrons` (`list[int]`): The controlling tetrahedron of each brick of the splinter path, one brick per cage cell that holds a part of the surface; empty without splinter data.
- `vertex_cell_tetrahedrons` (`list[int]`): The cell tetrahedron of each output vertex on the splinter path, the one it follows once its cell has broken loose; empty without splinter data.

**See also** [Guide: Read the prepared surface](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#read-the-prepared-surface) · [C `DeformableSurfaceEmbeddingView`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformablesurfaceembeddingview)

## embed_surface

**Function** · `deformable.embed_surface`

```python
def embed_surface(
    rest: TetrahedralMesh,
    surface: SurfaceMesh,
    parameters: PreparationParameters,
) -> SurfaceEmbedding
```

Prepares a render surface against the rest mesh of an object: cuts it as the clip mode says, adds inner faces with random planar UVs times `uv_scale`, takes the splinter path when a splinter cage is given, then embeds each output vertex in a tetrahedron by barycentric weights.

The prepared surface keeps every channel the input has, with opaque white as the colour of inner faces. With [`ClipMode.CLIP_WITH_INNER_FACES`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#clipmode-clip_with_inner_faces) and on the splinter path, a polygon of fewer than 3 corners is left out. The random stream that turns and offsets the UVs of inner faces has a fixed seed, so equal input gives equal UVs.

**Parameters**

- `rest` ([`TetrahedralMesh`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#tetrahedralmesh)): The object's tetrahedral mesh at rest, in the space of `surface`: the mesh given to [`Scene.add_object`](https://help.tangerina.io/deformable/latest/api-references/python/scene/#scene-add_object), or that mesh before the host moved it to world space, with the same tetrahedrons in the same order.
- `surface` ([`SurfaceMesh`](https://help.tangerina.io/deformable/latest/api-references/python/meshes/#surfacemesh)): The render surface: its polygons, and per-corner normals, UV sets and colours where it has them.
- `parameters` ([`PreparationParameters`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#preparationparameters)): How the surface is cut, the scale of the UVs the call makes, and an optional splinter cage.

**Returns**

[`SurfaceEmbedding`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#surfaceembedding): The prepared surface with its embedding, to skin every frame with [`SurfaceEmbedding.deform`](https://help.tangerina.io/deformable/latest/api-references/python/render-surfaces/#surfaceembedding-deform).

**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): `rest` has no tetrahedrons.
- [`INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-index_out_of_range): A tetrahedron of `rest` names a node past the end of its positions, `rest` has more tetrahedrons than a corner flag word addresses (2 to the power 29), or a corner of `surface` or of the splinter cage names a vertex past the end of its positions.
- [`LENGTH_MISMATCH`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-length_mismatch): The polygon sizes of `surface` or of the splinter cage do not add up to its corner count, the normals or the colours of `surface` hold neither 0 entries nor one per corner, or `surface` has more than 2,147,483,647 polygons.
- [`NON_FINITE_VALUE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-non_finite_value): A position of `rest`, `surface` or the splinter cage, a normal, UV or colour of `surface`, or `uv_scale` 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 of `rest` share a face.
- [`INVALID_SPLINTER_CAGE`](https://help.tangerina.io/deformable/latest/api-references/python/errors/#status-invalid_splinter_cage): A polygon of the splinter cage has fewer than 3 vertices, or on the splinter path, a brick has 3 faces or fewer.

`ValueError` when the positions of `rest`, `surface` or the splinter cage, or the normals of `surface`, do not form whole groups of three numbers, the tetrahedrons of `rest` whole groups of four, a UV set does not hold one coordinate pair per corner, the colours do not form whole groups of four numbers, an index or polygon size is negative or does not fit in 32 bits, or `clip_mode` does not fit in 32 bits.

`TypeError` when `clip_mode` is not an int.

**Example**

```python
clip = deformable.ClipMode.CLIP_WITH_INNER_FACES
parameters = deformable.PreparationParameters(clip, uv_scale=1.0)
surface = deformable.SurfaceMesh(polygons)
with deformable.embed_surface(mesh, surface, parameters) as embedding:
    arrays = embedding.arrays()
-1 in arrays.source_faces  # inner faces
# True
```

**See also** [Guide: Choose how to prepare it](https://help.tangerina.io/deformable/latest/user-guides/python/render-surfaces/#choose-how-to-prepare-it) · [C `deformable_embed_surface`](https://help.tangerina.io/deformable/latest/api-references/c/render-surfaces/#deformable_embed_surface) · [Rust `embed_surface`](https://help.tangerina.io/deformable/latest/api-references/rust/render-surfaces/#embed_surface)
