﻿---
title: Overview
description: "The reference of the deformable Python package: its conventions, and the pages that list every public item."
url: https://help.tangerina.io/deformable/v0.8.0/api-references/python/overview/
---

# Overview – Python API Reference – Deformable v0.8.0

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](https://help.tangerina.io/deformable/v0.8.0/user-guides/python/getting-started/).

## Pages

- [Scene](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/): The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs.
- [Tools](https://help.tangerina.io/deformable/v0.8.0/api-references/python/tools/): Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.
- [Mesh checks](https://help.tangerina.io/deformable/v0.8.0/api-references/python/mesh-checks/): Check a surface for problems before you use it, and find tetrahedral meshes that overlap.
- [Meshes](https://help.tangerina.io/deformable/v0.8.0/api-references/python/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](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/): Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
- [Math](https://help.tangerina.io/deformable/v0.8.0/api-references/python/math/): The points, vectors, transforms, planes and convex regions the other pages take and return.
- [Errors](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/): Errors and status codes, the library version, and the cancel flag that stops a long call.
- [License](https://help.tangerina.io/deformable/v0.8.0/api-references/python/license/): The license state of this device, or of this program under an Application license, and the calls that refresh it, sign in to a subscription, and activate and deactivate a license.

## Conventions

- **Errors.** A failed call raises [`DeformableError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#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`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/#scene), [`SurfaceEmbedding`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/#surfaceembedding) and [`CancelFlag`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#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`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#vector3array), [`Vector2Array`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#vector2array), [`IndexArray`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#indexarray), [`IndexGroupArray`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#indexgrouparray), [`ColourArray`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#colourarray) and [`PixelArray`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#pixelarray) describe. Results are lists of [`Vector3`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/math/#vector3) ([`Vector2`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/math/#vector2) for UV sets), index tuples for grouped indices and plain int lists for flat ones, except the skinned output of [`SurfaceEmbedding.deform`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/#surfaceembedding-deform) ([`DeformedSurface`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/render-surfaces/#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.** Nothing ever refuses to run: without a subscription or a license, Free runs, and a scene simulates at most 2,500 tetrahedrons. `deformable.license` reads the license, signs in to a Standalone subscription and activates a license key. A Standalone subscription or license belongs to this device and user; an Application license, refused inside the plugins, licenses the program that activates its key at every start. A license failure raises [`LicenseError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#licenseerror), a [`DeformableError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#deformableerror) whose message is written for the user, such as [`TetrahedronLimitExceededError`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/errors/#tetrahedronlimitexceedederror) for an object past Free's limit ("Free: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene").
- **Examples.** The examples share a few values set up out of view: `cage`, the unit cube as a closed [`TriangleMesh`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#trianglemesh) with outward normals; `polygons`, the same cube as a [`PolygonMesh`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/meshes/#polygonmesh) of six quads; `mesh`, the cage filled with tetrahedrons; `scene`, a [`Scene`](https://help.tangerina.io/deformable/v0.8.0/api-references/python/scene/#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
```
