You are viewing the documentation for Deformable v0.1.1, an older version. Read the latest, v0.9.0

Python SDK

Render surfaces

Embed a render mesh in an object's rest tetrahedral mesh, then skin it on the simulated object every frame, cracks and splinters included.

On this page

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 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.

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.
  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.
at rest: embed once each frame: deform

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:

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.
at rest: inner faces hidden after a crack: inner faces show

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.
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. 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.

at rest: caps hidden broken: each splinter shows its caps

Make the cage with splinters_from_image, 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