You are viewing the documentation for Deformable v0.5.0, an older version. Read the latest, v0.9.0
Python API Reference
Meshes
The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
On this page
The meshes the tools and the scene take and return: a TetrahedralMesh for each simulated object, a TriangleMesh or a PolygonMesh for cages, and a 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 (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, Vector2Array, IndexArray, IndexGroupArray, ColourArray and PixelArray, take any of these forms:
- a sequence of groups, such as a list of (x, y, z) tuples or of
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, soarray.array("f")vertex data from Blender’sforeach_getworks 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
@dataclasses.dataclass
class TetrahedralMesh:
positions: Vector3Array
tetrahedrons: IndexGroupArrayA 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 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 shell can invert some on sharp curvature, and span_layers keeps the flat tetrahedrons of layers that touch.
Fields
positions(Vector3Array)The node positions.tetrahedrons(IndexGroupArray)The four node indices of each tetrahedron.
Example
# 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)
# 1See also Guide: Mesh classes · C DeformableTetrahedralMesh · C DeformableTetrahedralMeshView · Rust TetrahedralMesh
TriangleMesh
Data class · deformable.TriangleMesh
@dataclasses.dataclass
class TriangleMesh:
positions: Vector3Array
triangles: IndexGroupArrayA triangle mesh: shared vertex positions and three vertex indices per triangle.
A closed cage, as tetrahedralize takes, lists the corners of each triangle counter-clockwise as seen from outside, so its normals point outward.
Fields
positions(Vector3Array)The vertex positions.triangles(IndexGroupArray)The three vertex indices of each triangle.
Example
# 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)
# 3See also Guide: Mesh classes · C DeformableTriangleMesh · C DeformableTriangleMeshView · Rust TriangleMesh
PolygonMesh
Data class · deformable.PolygonMesh
@dataclasses.dataclass
class PolygonMesh:
positions: Vector3Array
polygon_sizes: IndexArray
polygon_vertices: IndexArrayA 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 names each hole run.
Fields
positions(Vector3Array)The vertex positions.polygon_sizes(IndexArray)The number of corners of each polygon.polygon_vertices(IndexArray)The vertex index of each corner, polygon after polygon.
Example
# 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 · C DeformablePolygonMesh · C DeformablePolygonMeshView · Rust PolygonMesh
FaceHole
Named tuple · deformable.FaceHole
class FaceHole(NamedTuple):
face: int
first_corner: int
corner_count: intA run of a polygon’s corners that forms one hole loop; the corners before the polygon’s first hole form its outer loop.
triangulate and 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
# 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 · C DeformableFaceHole · Rust FaceHole
SurfaceMesh
Data class · deformable.SurfaceMesh
@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 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)The positions and polygons.normals(Vector3Array)The normal of each corner, or none. Default().uv_sets(Sequence[Vector2Array])The UV sets, each with one coordinate pair per corner. Default().colours(ColourArray)The red, green, blue and alpha of each corner, or none. Default().
Example
# 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 · C DeformableSurfaceMeshView · Rust SurfaceMesh
Vector3Array
Type alias · deformable.Vector3Array
Vector3Array = Union[Sequence[Sequence[float]], Sequence[float], Buffer]Points or vectors of three floats, x, y and z: Vector3 values or other groups of three, a flat sequence of numbers, or a buffer, read as doubles.
See also Guide: Array forms
Vector2Array
Type alias · deformable.Vector2Array
Vector2Array = Union[Sequence[Sequence[float]], Sequence[float], Buffer]Pairs of floats, such as the UV coordinates of the corners: Vector2 values or other pairs, a flat sequence of numbers, or a buffer, read as doubles.
See also Guide: Array forms
IndexArray
Type alias · deformable.IndexArray
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
IndexGroupArray
Type alias · deformable.IndexGroupArray
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
ColourArray
Type alias · deformable.ColourArray
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
PixelArray
Type alias · deformable.PixelArray
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
Buffer
Type alias · deformable.Buffer
Buffer = AnyAny 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
face_corners
Function · deformable.face_corners
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 and of 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 with one of these statuses:
INDEX_OUT_OF_RANGEfaceis above 3.
ValueError when face is negative or does not fit in 32 bits.
Example
# Face 1 is the face opposite corner 1.
deformable.face_corners(1)
# (0, 3, 2)See also Guide: Tetrahedron faces · C deformable_face_corners · Rust FACES
boundary_faces
Function · deformable.boundary_faces
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 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)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 numbers the faces.
Raises
DeformableError with one of these statuses:
EMPTY_MESHThe mesh has no tetrahedron.INDEX_OUT_OF_RANGEA tetrahedron uses a node index past the end of the positions.NON_FINITE_VALUEA position is NaN or infinite.NON_MANIFOLD_FACEThree 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
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)
# 12See also Guide: Tetrahedron faces · C deformable_boundary_faces · Rust boundary_faces