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

Python API Reference

Overview

The reference of the deformable Python package: its conventions, and the pages that list every public item.

On this page

The Python SDK is the deformable package. These pages list every public name of the package with its signature and documentation, generated from its source. They group the names by topic rather than by module: the kind line under each heading gives the name’s path in the package.

For tasks and worked examples, start with the getting-started guide.

Pages

  • Scene: The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs.
  • Tools: Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.
  • Mesh checks: Check a surface for problems before you use it, and find tetrahedral meshes that overlap.
  • Meshes: The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
  • Render surfaces: Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
  • Math: The points, vectors, transforms, planes and convex regions the other pages take and return.
  • Errors: Errors and status codes, the library version, and the cancel flag that stops a long call.
  • License: The license state of this device, and the calls that refresh, activate and deactivate it.

Conventions

  • Errors. A failed call raises DeformableError with the library’s status, message and element indices. Arguments the package refuses before calling the library raise ValueError or TypeError; a closed handle raises ValueError.
  • Handles. Scene, SurfaceEmbedding and CancelFlag own a library handle, freed by close(), at the end of a with block, or when the object is collected; close() waits for calls in flight on the object from other threads, and later calls raise ValueError. Object and material handles are ints counting up from 0.
  • Arrays. Vertex and index data may be lists or tuples of groups, flat sequences of numbers, array.array, memoryview or any other buffer, as the type aliases Vector3Array, Vector2Array, IndexArray, IndexGroupArray, ColourArray and PixelArray describe. Results are lists of Vector3 (Vector2 for UV sets), index tuples for grouped indices and plain int lists for flat ones, except the skinned output of SurfaceEmbedding.deform (DeformedSurface), which is flat array.array copies: 32-bit floats for positions and normals, bytes for the hidden faces.
  • Units. Lengths cross in host units; time, forces, gravity, masses and material values in simulation units. The scene’s scale converts host lengths to simulation lengths.
  • Threads. Library calls release the global interpreter lock. Calls on one scene from several threads run one at a time; tools, embeddings and cancel flags may be used from several threads at once.
  • License. The library checks the license of this device and user before engine work; deformable.license reads it and activates a license key. A call the trial or license does not allow raises LicenseError, a DeformableError whose message is written for the user: LicenseRequiredError (“Trial ended — Buy license”) and TrialLimitExceededError (“Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”) are its two most common kinds.
  • Examples. The examples share a few values set up out of view: cage, the unit cube as a closed TriangleMesh with outward normals; polygons, the same cube as a PolygonMesh of six quads; mesh, the cage filled with tetrahedrons; scene, a Scene holding one object made of mesh with one default material; and material and object, the handles of that material and object.

The package

deformable: finite element deformation and fracture of tetrahedral meshes, from Python.

A pure-Python package over libdeformable, the shared library of the C SDK (declared in deformable.h), loaded with ctypes. It needs no third-party package: only the shared library, which the platform wheel carries in the package directory. The library is looked up through the DEFORMABLE_LIBRARY environment variable, then in the package directory, then in the target/release folder of the Cargo workspace the package sits in (deformable.library).

It runs on Python 3.9 and later, so it also runs inside Blender, whose bundled Python is 3.10 or later since Blender 3.1: put the package and the shared library on Blender’s module path, or set DEFORMABLE_LIBRARY.

The host flow below fills a closed cage with tetrahedrons, makes the mesh an object of a new scene, steps it for one second and reads where its nodes are:

python
import deformable
# The unit cube as a closed cage of outward triangles.
corners = [(x, y, z) for z in (0, 1) for y in (0, 1) for x in (0, 1)]
triangles = [
    (0, 2, 3), (0, 3, 1), (4, 5, 7), (4, 7, 6), (0, 1, 5), (0, 5, 4),
    (2, 6, 7), (2, 7, 3), (0, 4, 6), (0, 6, 2), (1, 3, 7), (1, 7, 5),
]
cage = deformable.TriangleMesh(corners, triangles)
parameters = deformable.TetrahedralizeParameters(
    maximum_edge_length=0.5
)
mesh = deformable.tetrahedralize(cage, parameters).mesh
with deformable.Scene() as scene:
    defaults = deformable.MaterialParameters.default()
    material = scene.add_material(defaults)
    cube = scene.add_object(mesh, material)
    for frame in range(25):
        report = scene.step(frame / 24, substeps=10)
    positions = scene.node_positions(cube)
report.outcome
# <StepOutcome.STEPPED: 0>
all(position.y < 1 for position in positions)  # it fell
# True