You are viewing the documentation for Deformable v0.7.0, 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
- Build the object’s tetrahedral mesh with the tools.
- Call
embed_surface(rest, surface, parameters)with the rest mesh and the render surface. Keep the returnedSurfaceEmbeddingfor the life of the object. - Read the prepared surface once with
embedding.arrays(). Build your render mesh from it: its polygons and per-corner channels never change. - After each
Scene.step, callembedding.deform(scene.tetrahedron_states(object_handle), world_transform)and write the new positions, normals and hidden faces to your mesh.
This example drops a glass cube onto a floor and skins its surface every frame:
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")prepared: 5556 vertices, 1852 faces
frame 0: 1638 hidden faces
frame 24: 1198 hidden faces
frame 48: 1194 hidden facesThe 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:
Clip |
What the call makes |
|---|---|
ASSIGN_ |
Each vertex follows the tetrahedron it lies in. Nothing is cut, and no inner face is made. |
CLIP_ |
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_ |
The tetrahedral mesh is the surface: each polygon follows the tetrahedron its centre lies in, uncut, and every interior face becomes an inner face. |
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.
surfaceis the preparedSurfaceMeshin rest space. The prepared surface splits vertices where a crack can open, so it has more vertices than the input.source_facesgives 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.
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")1638 inner faces, 5556 cornersThe 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 ofarrays().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:
- Embed the surface in object space, with a rest mesh in object space.
- Map the rest mesh to world space before
add_object: the simulation runs in world space. - 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.
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]))-0.5 0.5The 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.
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:
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")2 splintersAt 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: the scene the states come from.
- Types and errors: handle a failed preparation, and skin from several threads.
- Render surfaces reference: every class and function of the embedding, with its signature.