﻿---
title: Render surfaces
description: Embed a render mesh in an object's rest tetrahedral mesh, then skin it on the simulated object every frame, cracks and splinters included.
url: https://help.tangerina.io/deformable/v0.8.0/user-guides/python/render-surfaces/
---

# Render surfaces – Python SDK – Deformable v0.8.0

`embed_surface` prepares a render surface, the artist's polygon mesh with its normals, UVs and colours, against the
object's rest tetrahedral mesh once. Then, every frame, `SurfaceEmbedding.deform` moves it with the tetrahedrons. What a
render surface keeps, the clip modes, and how inner faces and splinters show where an object breaks are on
[Render surfaces](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/render-surfaces/) in the Engine guide; this page shows the calls.

Every name on this page is in the `deformable` module. For every field of these types, see the
[render surfaces reference](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/).

The examples on this page build on each other. Run them in order in one Python session, starting with the first.

## The flow

1. Build the object's tetrahedral mesh with the [tools](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/tools/).
2. Call `embed_surface(rest, surface, parameters)` with the rest mesh and the render surface. Keep the returned
   `SurfaceEmbedding` for the life of the object.
3. Read the prepared surface once with `embedding.arrays()`. Build your render mesh from it: its polygons and
   per-corner channels never change.
4. After each `Scene.step`, call `embedding.deform(scene.tetrahedron_states(object_handle), world_transform)`
   and write the new positions, normals and hidden faces to your mesh.

![A render surface sits inside the rest tetrahedral mesh, and when the tetrahedrons bend, the surface bends with them.](../../images/sdk-surface-embedded-in-tetrahedrons.svg "Embed the surface once at rest, then deform it every frame after the step.")

This example drops a glass cube onto a floor and skins its surface every frame:

```python
import deformable


def box(minimum, maximum):
    """A closed box as six outward quads."""
    (x0, y0, z0), (x1, y1, z1) = minimum, maximum
    positions = [(x, y, z) for z in (z0, z1) for y in (y0, y1) for x in (x0, x1)]
    corners = [0, 2, 3, 1, 4, 5, 7, 6, 0, 1, 5, 4, 2, 6, 7, 3, 0, 4, 6, 2, 1, 3, 7, 5]
    return deformable.PolygonMesh(positions, [4] * 6, corners)


def solid(polygons, maximum_area, maximum_edge_length):
    """Triangulate a closed polygon mesh, then fill it with tetrahedrons."""
    parameters = deformable.TriangulateParameters.default(maximum_area=maximum_area)
    cage = deformable.triangulate(polygons, parameters=parameters).mesh
    return deformable.tetrahedralize(cage, deformable.TetrahedralizeParameters(maximum_edge_length)).mesh


floor_mesh = solid(box((-3.0, -0.5, -3.0), (3.0, 0.0, 3.0)), 1.0, 1.0)
cube_polygons = box((-0.5, 2.0, -0.5), (0.5, 3.0, 0.5))
cube_mesh = solid(cube_polygons, 0.05, 0.3)

# One flat normal and one UV per corner, in the order of the box's six quads.
face_normals = [(0, 0, -1), (0, 0, 1), (0, -1, 0), (0, 1, 0), (-1, 0, 0), (1, 0, 0)]
normals = [normal for normal in face_normals for _ in range(4)]
uvs = [(0.0, 0.0), (1.0, 0.0), (1.0, 1.0), (0.0, 1.0)] * 6
surface = deformable.SurfaceMesh(cube_polygons, normals=normals, uv_sets=[uvs])

parameters = deformable.PreparationParameters(deformable.ClipMode.CLIP_WITH_INNER_FACES, uv_scale=1.0)
with deformable.embed_surface(cube_mesh, surface, parameters) as embedding:
    prepared = embedding.arrays().surface.mesh
    print("prepared:", len(prepared.positions), "vertices,", len(prepared.polygon_sizes), "faces")

    with deformable.Scene() as scene:
        stone = scene.add_material(deformable.MaterialParameters.preset("stone"))
        glass = scene.add_material(deformable.MaterialParameters.preset("glass"))
        floor = scene.add_object(floor_mesh, stone)
        scene.drive(floor, list(enumerate(floor_mesh.positions)))
        cube = scene.add_object(cube_mesh, glass)

        for frame in range(49):
            scene.step(frame / 24, substeps=10)
            states = scene.tetrahedron_states(cube)
            deformed = embedding.deform(states, deformable.IDENTITY)
            if frame % 24 == 0:
                print(f"frame {frame}: {sum(deformed.hidden_faces)} hidden faces")
```

```text
prepared: 5556 vertices, 1852 faces
frame 0: 1638 hidden faces
frame 24: 1198 hidden faces
frame 48: 1194 hidden faces
```

The cube lands and breaks. 444 inner faces show along the cracks.

## Describe the render surface

A `SurfaceMesh(mesh, normals=(), uv_sets=(), colours=())` is a `PolygonMesh` with optional per-corner channels.
Each channel is empty or holds one entry per corner, in the order of `mesh.polygon_vertices`:

- `normals`: one normal per corner. The library keeps the artist's normals and never invents one, so a surface
  without normals gets none back.
- `uv_sets`: any number of UV sets, each with one `(u, v)` pair per corner.
- `colours`: one `(red, green, blue, alpha)` colour per corner.

The surface is in the same space as the rest mesh. It does not have to match the cage you meshed: points outside
the rest mesh follow a nearby tetrahedron.

## Choose how to prepare it

`PreparationParameters(clip_mode, uv_scale, splinter_cage=None)` sets how the surface is prepared. The `clip_mode` is a
`ClipMode`; which one suits which object is on [Clip modes](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/render-surfaces/#clip-modes):

| `ClipMode` | What the call makes |
|---|---|
| `ASSIGN_ONLY` | Each vertex follows the tetrahedron it lies in. Nothing is cut, and no inner face is made. |
| `CLIP_WITH_INNER_FACES` | The surface is cut along the tetrahedron faces. The part of each interior face inside the solid becomes an inner face, hidden until a crack opens it. |
| `TETRAHEDRAL_MESH_BOUNDARY` | The tetrahedral mesh is the surface: each polygon follows the tetrahedron its centre lies in, uncut, and every interior face becomes an inner face. |

![A block with a crack path marked on its surface, then broken in two along tetrahedron faces, with the inner faces along the crack now showing.](../../images/sdk-inner-faces-show-on-cracks.svg "Inner faces stay hidden at rest and show only where a crack opens the object.")

The prepared surface keeps every channel the input has. Inner faces are opaque white when the surface has colours,
and get planar UVs at a random rotation and offset, scaled by `uv_scale`; 1 is a good start. The random stream has a fixed seed, so the same input always gives the same UVs.

## Read the prepared surface

`embedding.arrays()` returns a copy of the prepared surface and its embedding data. Read it once: it never changes.

- `surface` is the prepared `SurfaceMesh` in rest space. The prepared surface splits vertices where a crack can open,
  so it has more vertices than the input.
- `source_faces` gives the input face each output face was cut from, or -1 for inner faces and splinter caps. Use it
  to carry per-face materials to the output: give the -1 faces your
  [inner material](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/render-surfaces/#inner-faces).

```python
with deformable.embed_surface(cube_mesh, surface, parameters) as embedding:
    arrays = embedding.arrays()
print(arrays.source_faces.count(-1), "inner faces,", len(arrays.surface.mesh.polygon_vertices), "corners")
```

```text
1638 inner faces, 5556 corners
```

The other fields hold the embedding itself: the tetrahedron and weights each vertex follows. You need them only to
skin the surface yourself.

## Skin it every frame

`deform(states, world_transform, options=None)` skins the surface on the current tetrahedrons. Pass it the
object's `scene.tetrahedron_states(object_handle)`, one per rest tetrahedron, and the world matrix of your
render mesh. It returns a `DeformedSurface` of three flat `array.array` copies:

- `positions`, `array("f")`: x, y and z of each output vertex, in the order of `arrays().surface.mesh.positions`.
- `normals`, `array("f")`: x, y and z of the unit normal of each corner, in corner order. Empty without normals.
- `hidden_faces`, `array("b")`: 1 for each face to hide, 0 for each face to show, in face order.

Hand them to your mesh API as they are. For example, Blender's `foreach_set` takes them without a per-item
conversion.

A face is hidden while it is an inner face or a splinter cap that no crack has opened. Once a fracture exposes the
tetrahedron face under it, it shows for good. `SkinningOptions(show_inner_faces=True)` shows every inner face and
cap, which helps you inspect the preparation.

### Object space and the world transform

A host keeps the render mesh in its object space and places it with a world matrix. Do the same here:

1. Embed the surface in object space, with a rest mesh in object space.
2. Map the rest mesh to world space before `add_object`: the simulation runs in world space.
3. Pass the world matrix to `deform`. The result comes back in object space, ready for the mesh.

`AffineTransform(linear, translation)` maps row vectors, so `linear[i]` is where axis i goes. A matrix M that maps
column vectors (M · p, as in Blender) gives `linear[i][j] = M[j][i]`. Pass `deformable.IDENTITY` when the surface is
already in world space.

```python
local_polygons = box((-0.5, -0.5, -0.5), (0.5, 0.5, 0.5))
local_mesh = solid(local_polygons, 0.05, 0.3)
local_surface = deformable.SurfaceMesh(local_polygons, normals=normals)
world = deformable.AffineTransform(((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0)), (0.0, 2.5, 0.0))
world_mesh = deformable.TetrahedralMesh(
    [(x, y + 2.5, z) for x, y, z in local_mesh.positions], local_mesh.tetrahedrons
)

with deformable.embed_surface(local_mesh, local_surface, parameters) as embedding:
    with deformable.Scene() as scene:
        material = scene.add_material(deformable.MaterialParameters.preset("rubber"))
        cube = scene.add_object(world_mesh, material)
        deformed = embedding.deform(scene.tetrahedron_states(cube), world)
print(min(deformed.positions[1::3]), max(deformed.positions[1::3]))
```

```text
-0.5 0.5
```

The cube sits at y = 2.5 in the world, and its skinned surface comes back around the origin. A world matrix with a
non-uniform scale keeps the artist's normals too: they are mapped back into object space and made unit length. A
world matrix with no inverse raises `DeformableError` with the status `SINGULAR_TRANSFORM`.

## Splinters

A splinter cage gives the cracks the shapes of its cells; see
[Splinters](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/fracture-and-splinters/#splinters). The surface is cut into one piece per
cage cell, and each piece is capped. A piece's vertices follow their own tetrahedrons until a crack reaches them. Then
they follow the piece's one tetrahedron, so the piece moves as one rigid splinter.

![A wall surface with its splinter cells marked, then broken into separate brick splinters whose cap faces show.](../../images/sdk-surface-breaks-into-splinters.svg "Each closed cell of the cage becomes one piece, whose hidden cap faces show when the piece breaks loose.")

Make the cage with [splinters_from_image](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/tools/#make-a-splinter-cage-from-a-drawing), or
load one of the splinter meshes in the plugin zips. It must be in the surface's space. Pass it as `splinter_cage` with
`CLIP_WITH_INNER_FACES`:

```python
wall_polygons = box((-1.0, 0.0, -0.125), (1.0, 1.0, 0.125))
wall_mesh = solid(wall_polygons, 0.05, 0.25)

# A wall split in two cells by a vertical line, drawn as a 41 x 31 image.
width, height = 41, 31
pixels = [(255, 255, 255)] * (width * height)
for column in range(5, 36):
    pixels[5 * width + column] = pixels[25 * width + column] = (0, 0, 0)
for row in range(5, 26):
    for column in (5, 20, 35):
        pixels[row * width + column] = (0, 0, 0)
for column, row in [(5, 5), (20, 5), (35, 5), (5, 25), (20, 25), (35, 25)]:
    pixels[row * width + column] = (255, 0, 0)
image = deformable.PixelGrid(width, height, pixels)

# The cells span x from -1 to 1 and y from 0 to 1, a little deeper than the wall.
cage_parameters = deformable.SplinterImageParameters.default(size=(2.8, 1.55, 0.5), origin=(-1.4, -0.25, 0.25))
splinter_cage = deformable.splinters_from_image(image, cage_parameters)

splinter_parameters = deformable.PreparationParameters(
    deformable.ClipMode.CLIP_WITH_INNER_FACES, uv_scale=1.0, splinter_cage=splinter_cage
)
with deformable.embed_surface(wall_mesh, deformable.SurfaceMesh(wall_polygons), splinter_parameters) as embedding:
    arrays = embedding.arrays()
print(len(arrays.brick_tetrahedrons), "splinters")
```

```text
2 splinters
```

At rest, the caps between splinters are hidden. A cap shows once a fracture flags one of its tetrahedrons, the brick's
or the one under the cap's first corner, in its tetrahedron state, or from the start with
`SkinningOptions(start_splintered=True)`.

## Next steps

- [Scene](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/scene/): the scene the states come from.
- [Types and errors](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/types-and-errors/): handle a failed preparation, and skin from several
  threads.
- [Render surfaces reference](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/): every class and function of the
  embedding, with its signature.
