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

Python SDK

Types and errors

The value types, array forms, handles, errors, threads and units that every part of the Python SDK shares.

On this page

This page explains the rules that every part of the package follows: how you pass points and meshes in, what comes back, who frees what, and what happens when a call fails. Every name on this page is in the deformable module.

The examples on this page build on each other. Run them in order in one Python session, starting with the first. For every field and member of these types, see the Python API reference; the vectors and transforms are on the math reference.

Points, vectors and transforms

The package returns points as Vector3(x, y, z) and UVs as Vector2(x, y). Both are named tuples. The one exception is the skinned surface SurfaceEmbedding.deform returns: a DeformedSurface holds flat arrays of 32-bit floats, three per position or normal. Anywhere the package takes a point or a vector, a plain tuple or list of numbers works too.

AffineTransform(linear, translation) maps row vectors: a point p goes to p · linear + translation. 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]. IDENTITY is the transform that leaves every point where it is.

python
import deformable

turn = deformable.AffineTransform(((0.0, 1.0, 0.0), (-1.0, 0.0, 0.0), (0.0, 0.0, 1.0)), (0.0, 0.0, 5.0))
print(turn.linear[0], turn.translation)
print(deformable.IDENTITY.translation)
text
(0.0, 1.0, 0.0) (0.0, 0.0, 5.0)
(0.0, 0.0, 0.0)

This transform turns the x axis into the y axis, then moves points 5 units along z.

Mesh classes

The mesh classes are plain dataclasses. They hold whatever array form you give them. Any object with the same attribute names works in place of a mesh class, so you can pass your own mesh type.

Class Fields Made by
TetrahedralMesh positions, and tetrahedrons with four node indices each tetrahedralize, extrude, span_layers
TriangleMesh positions, and triangles with three vertex indices each triangulate, autocage
PolygonMesh positions; polygon_sizes, the corner count of each polygon; polygon_vertices, the vertex of each corner, polygon after polygon splinters_from_image
SurfaceMesh mesh, a PolygonMesh, plus the optional per-corner normals, uv_sets and colours SurfaceEmbedding.arrays

FaceHole(face, first_corner, corner_count) marks a run of a polygon’s corners as a hole loop, for triangulate and verify_surface. Every field of these classes is on the meshes reference.

Orientation

Every tetrahedral mesh the library takes must be positively oriented. For a tetrahedron (X0, X1, X2, X3), with eᵢ = Xᵢ - X0, the value -e1 · (e2 × e3) is positive: the corners are left-handed. Face k is the face opposite corner k, and face_corners(k) gives its three corners. The tools make positive tetrahedrons, though a thick extrude shell can invert some where the mesh curves sharply. If you build a mesh yourself and add_object raises DEGENERATE_TETRAHEDRON_INVERTED, your tetrahedrons are right-handed: swap two corners of each one.

Triangle cages face outward: seen from outside, the corners of a triangle run counter-clockwise.

Array forms

Every array input takes any of these forms:

  • A sequence of groups: a list of (x, y, z) tuples, of lists, 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 buffer that already holds the C type, array("d") for positions or array("I") for indices, is copied as one block. Any other buffer, such as array("f") from Blender’s foreach_get, is read number by number.
python
import array

positions = [(x, y, z) for z in (0.0, 1.0) for y in (0.0, 1.0) for x in (0.0, 1.0)]
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),
]
parameters = deformable.TetrahedralizeParameters(0.5)
from_tuples = deformable.tetrahedralize(deformable.TriangleMesh(positions, triangles), parameters).mesh

flat_positions = array.array("d", [coordinate for position in positions for coordinate in position])
flat_triangles = array.array("I", [vertex for triangle in triangles for vertex in triangle])
from_buffers = deformable.tetrahedralize(deformable.TriangleMesh(flat_positions, flat_triangles), parameters).mesh

print(from_tuples == from_buffers, from_buffers.positions[0], from_buffers.tetrahedrons[0])
text
True Vector3(x=0.0, y=0.0, z=0.0) (8, 4, 5, 0)

Results are copied out of the library at once. They are lists of Vector3, of int and of index tuples, and they stay valid after later calls. The one exception is SurfaceEmbedding.deform, which returns flat array.array copies for speed.

Enumerations

Every enumeration is an enum.IntEnum, so its members compare equal to their numbers, and a plain int works as an argument. A number the library does not define raises INVALID_ARGUMENT.

Enumeration Used by
StepOutcome Scene.step, see Scene
ClipMode embed_surface, see Render surfaces
ExtrudeDirection extrude, see Tools
SelfIntersectionCheck, MeshIssueKind verify_surface, see Tools
Status DeformableError, below

The members and their numbers are under each enumeration in the Python API reference: StepOutcome, ClipMode, ExtrudeDirection, SelfIntersectionCheck, MeshIssueKind and Status.

Errors

The package raises these exceptions.

Exception When
DeformableError The library refused a call.
LicenseError An object past the Free license’s limit, or a license call that failed. A subclass of DeformableError, see License errors.
ValueError The package refused an argument before the call, or the handle is closed.
TypeError An argument has the wrong type, such as a string where numbers belong.
LibraryNotFoundError No shared library was found. It is a subclass of OSError.

DeformableError

A DeformableError carries four attributes:

  • status: a member of deformable.Status, such as Status.NON_CLOSED_BOUNDARY. A code newer than the package comes through as a plain int.
  • message: the library’s message, in English.
  • first_index and second_index: the elements the failure concerns, such as the tetrahedron, the polygon or the two vertices of an edge. They are 0 when the status names none.

str(error) is the status name, a colon and the message. In these guides, a status name such as NON_CLOSED_BOUNDARY means a DeformableError with that status. Nothing is created when a call fails.

python
cube = from_tuples
tetrahedrons = [list(tetrahedron) for tetrahedron in cube.tetrahedrons]
tetrahedrons[3][0], tetrahedrons[3][1] = tetrahedrons[3][1], tetrahedrons[3][0]

with deformable.Scene() as scene:
    material = scene.add_material(deformable.MaterialParameters.default())
    try:
        scene.add_object(deformable.TetrahedralMesh(cube.positions, tetrahedrons), material)
    except deformable.DeformableError as error:
        print(error.status == deformable.Status.DEGENERATE_TETRAHEDRON_INVERTED, error.first_index)
        print(error)
text
True 3
DEGENERATE_TETRAHEDRON_INVERTED: tetrahedron 3 is inverted

Swapping two corners turns tetrahedron 3 inside out, so add_object refuses the mesh and names the tetrahedron.

The status codes are the same as the C SDK’s. The full list, with what each index names, is on the errors reference.

License errors

Nothing ever refuses to run. Without a license, the Free license runs, and a scene simulates up to 2,500 tetrahedrons. The license is the Developer license key the program activated, or else the Free or Standard license of this device. A license failure raises LicenseError, a subclass of DeformableError, with one of these statuses. Its message is written to show the user as it is, such as Free license: this would simulate 3,120 tetrahedrons; the limit is 2,500 per scene. TETRAHEDRON_LIMIT_EXCEEDED raises the subclass TetrahedronLimitExceededError, whose tetrahedrons and limit name the count the scene would simulate with the object and the limit.

Status When
TETRAHEDRON_LIMIT_EXCEEDED Under the Free license, Scene.add_object would take the scene past 2,500 tetrahedrons; a disabled object does not count. first_index is the count the scene would simulate with the object, second_index the limit. Scene.add_object adds nothing then, and the scene goes on with the objects it holds.
LICENSE_SERVICE_UNAVAILABLE activate, deactivate or refresh could not reach our licensing service or it did not answer, its answer did not verify, the device’s clock contradicts it, or set_online_access(False) turned contacts off.
LICENSE_KEY_REJECTED Our licensing service refused the Standard key: it does not exist, was revoked or refunded, is not for Deformable, every seat of the license is in use, or this device was removed. Or the Developer key was refused: it was revoked, its trial ended, its updates ended before this version was released, or the program is Blender or Maya, where Developer licenses do not work.
LICENSE_STORAGE_FAILED The license state could not be saved in your user folder.

Scene.add_object is the only engine call the license can refuse. The mesh tools and render surfaces have no limit. When a scene holds more than fits, such as after a Standard license ran out of renewals, Scene.step simulates the objects that fit, in the order they were added, and holds the rest still until a license applies again. Creating a scene, setting its values, reading its outputs and closing handles never check the license, so your tool can always clean up. deformable.license reads and changes the license state: see License.

python
with deformable.Scene() as scene:
    material = scene.add_material(deformable.MaterialParameters.default())
    try:
        scene.add_object(cube, material)
        scene.step(1.0, substeps=10)
    except deformable.TetrahedronLimitExceededError as error:
        print(f"{error.tetrahedrons} tetrahedrons, the limit is {error.limit}")

While the scene fits under the limit, or a license applies, this prints nothing.

What the package refuses before the call

Some arguments cannot be checked by the library, so the package checks them first:

  • A negative index, handle or count, or one too large for its C type, raises ValueError. Indices and handles stop below 2^32.
  • Vertex or index data that is not a whole number of groups raises ValueError, for example 2 numbers for a position.
  • A UV set without one pair per corner raises ValueError.
  • A string where numbers belong raises TypeError, and so does a preset name that is not a str.
  • Any call on a closed Scene, SurfaceEmbedding or CancelFlag raises ValueError.
python
try:
    deformable.boundary_faces(deformable.TetrahedralMesh([0.0, 1.0], [(0, 1, 2, 3)]))
except ValueError as error:
    print(error)
text
positions holds 2 numbers, not a whole number of groups of 3

Handles

Three classes own a library handle: Scene, SurfaceEmbedding and CancelFlag. Each one frees its handle in one of three ways:

  • at the end of a with block;
  • when you call close();
  • when the garbage collector collects it, at a time you do not control.

close() waits for the calls in flight on the object from other threads, then frees the handle. Closing twice does nothing, and closed is True afterwards. Any later call raises ValueError.

python
scene = deformable.Scene()
scene.close()
try:
    scene.step(0.0, 10)
except ValueError as error:
    print(scene.closed, error)
text
True the scene is closed

Object and material handles are not classes. They are int values that count up from 0 in creation order, and they belong to the scene that made them.

Cancel a long call

A CancelFlag stops a long call from another thread. Call set() to raise it, clear() to use it again, and is_set() to read it. Scene.step, triangulate, tetrahedralize and autocage take one. See the cancel flag reference.

A tool stops with CANCELLED. A step stops between two substeps and returns a StepReport whose outcome is StepOutcome.CANCELLED; it does not raise.

python
with deformable.CancelFlag() as cancel:
    cancel.set()
    try:
        deformable.tetrahedralize(deformable.TriangleMesh(positions, triangles), parameters, cancel)
    except deformable.DeformableError as error:
        print(error.status.name, cancel.is_set())
text
CANCELLED True

Tools shows how to set the flag from another thread while a tool runs.

Threads

Library calls release the global interpreter lock, so other Python threads run while a call works.

  • A Scene can move between threads. Calls on one scene from several threads run one at a time.
  • Tools, SurfaceEmbedding reads and skinning, and cancel flags work from several threads at once.
  • Results are bitwise identical run to run, whatever the worker count.

Units

Lengths cross in host units: positions, driven targets, glue plane offsets and every tool input. Time is in seconds. Forces, gravity, node masses and material values are in simulation units. Scene.set_scale converts host lengths to simulation lengths. The default scale of 1 makes them the same, and the default gravity of 9.81 makes a unit read as a metre. The tools always work in their input’s unit. See Units and axes.

Versions

deformable.__version__ is the package version, such as "0.1.0". deformable.library_version() loads the library and returns its version, as major.minor.patch. The two match when the package and the library come from the same release. See Getting started for how the package finds the library.

Next steps

  • Scene: materials, objects, driving, glue, stepping and outputs.
  • Errors reference: every status, with what its indices name.
  • Support: report a bug in the SDK.