Metadata-Version: 2.3
Name: deformable
Version: 0.5.0
Summary: Finite element deformation and fracture of tetrahedral meshes: ctypes bindings over libdeformable
Author: Tangerina Inc.
Author-email: Tangerina Inc. <support@tangerina.io>
License: Proprietary
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Project-URL: Homepage, https://tangerina.io/deformable
Project-URL: Documentation, https://docs.tangerina.io/deformable/latest/user-guides/python/getting-started/
Project-URL: Support, https://docs.tangerina.io/deformable/latest/support/
Description-Content-Type: text/markdown

# Deformable Python SDK

The Python SDK of [Tangerina Deformable](https://tangerina.io/deformable): finite element deformation and fracture of
tetrahedral meshes. It gives you a scene you drive frame by frame, render surfaces embedded in its objects, and
the mesh tools that prepare its inputs: triangulate, tetrahedralize, extrude, span layers, autocage, splinters from an
image, surface verification and mesh intersection.

The package is pure Python over `libdeformable`, the shared library of the Deformable C SDK, which it calls with
`ctypes`. It has no third-party dependency. The C SDK and the Rust crate `deformable` call the same library, so all
three SDKs behave the same.

## Install

```sh
pip install deformable
```

Or, in a uv project, `uv add deformable`. You need no compiler: the wheel for your platform carries the library.

Platforms: macOS 11 or later on Apple silicon, Linux x64 with glibc 2.28 or later, and Windows x64. The package needs
Python 3.9 or later.

Check the installation:

```python
import deformable

print(deformable.__version__, deformable.library_version())
```

The two versions match when the package and the library come from the same release.

## A first scene

This script fills a closed unit cube with tetrahedrons and lets it fall under gravity for one second:

```python
import deformable

# A closed unit cube: 8 corners and 12 outward triangles.
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),
]
cage = deformable.TriangleMesh(positions, triangles)

# Fill the cage with tetrahedrons.
mesh = deformable.tetrahedralize(cage, deformable.TetrahedralizeParameters(maximum_edge_length=0.5)).mesh

with deformable.Scene() as scene:
    material = scene.add_material(deformable.MaterialParameters.default())
    cube = scene.add_object(mesh, material)

    # 24 frames per second, 10 substeps per frame. The first call only records the time.
    for frame in range(25):
        scene.step(frame / 24, substeps=10)

    lowest = min(position.y for position in scene.node_positions(cube))
    print(f"the cube fell to y = {lowest:.2f}")
```

## What the package holds

- `Scene`: its materials, objects, glue, driven vertices and forces, the frame `step` and its outputs.
- `MaterialPreset` and `MaterialRegion`: ready-made materials, and materials per region of an object.
- The render surfaces: `embed_surface` binds a render mesh to an object, and its `SurfaceEmbedding` follows it.
- The mesh tools, such as `tetrahedralize`, `triangulate` and `extrude`, and their parameters.
- `TriangleMesh`, `TetrahedralMesh`, `Vector3` and the other types the calls share.
- `DeformableError`: a failed library call raises it, with the library's status, its message and the indices of the
  elements it names.
- `CancelFlag`: stops a long tool or step from another thread.
- `deformable.license`: the license of this program, which sets how many tetrahedrons a scene simulates: the Free
  license, a Standalone license on this device or an Application license, and activating either license key.

Library calls release the global interpreter lock. Calls on one scene run one at a time; the tools, a
`SurfaceEmbedding` and a `CancelFlag` can be used from several threads at once.

## Free, Standalone and Application licenses

There are three licenses, and `deformable.license.activate()` takes the key of either paid one. See
[Licensing](https://docs.tangerina.io/deformable/latest/licensing/).

The Free license needs no key, no account and no internet, and nothing is sent. The engine works forever in the
Blender and Maya plugins and the C, Rust and Python SDKs, up to 2,500 tetrahedrons per scene: an object that would go
over is not added, and the rest of the scene runs. It is for your own work, personal or commercial; to ship the engine
inside an application that others use, you need an Application license.

The Standalone license removes the limit, with 1 device per seat, in the plugins and the SDKs. It costs $99 per seat,
one time (USD), on the [Licenses page](https://platform.tangerina.io/licenses) of the Tangerina platform. It is
perpetual and covers every future version, with email support at support@tangerina.io. Its key,
`tgdfp-xxxxx-xxxxx-xxxxx-xxxxx`, is activated online; the license then renews by itself while the engine runs online,
and the device may stay offline up to 7 days between renewals. `deformable.license.deactivate()` frees the seat for
another device. The plugins and every SDK on the device share one Standalone license. It can be refunded on the Licenses
page within 14 days of purchase.

The Application license is for one company that ships the engine inside one app, and works in the C, Rust and Python
SDKs only: the plugins refuse its key. It costs $499 per app, then $99 per year to keep updates (USD), on the Licenses
page. Its key covers every version released while its updates are paid and keeps working in those versions forever, for
any number of users of that app. A free 30-day Application trial starts on the Licenses page: its key has no limit, and
when it ends the engine falls back to the Free license. The key is checked offline and kept only while the program runs,
so your app activates it at every start, as its first Deformable call, before status and refresh; its users need no
activation, network or seat. There is no refund, so try it first with the 30-day trial.

```python
import deformable

# A Standalone key, or an Application key as it was given: "tgdfp-<payload hex>-<signature hex>".
deformable.license.activate("tgdfp-xxxxx-xxxxx-xxxxx-xxxxx")
# "Free license: up to 2,500 tetrahedrons per scene — Buy license", "Standalone license",
# "Application license: Acme Inc.", ...
print(deformable.license.status().message)
```

A Standalone license belongs to each device that runs your script: on a colleague's device, a server or a render farm
node the script runs under the Free license unless that device has a seat of its own. To ship the engine inside an
application you give to others, you need an Application license. Your application then activates its key at every start,
offline, and its users need no activation, network or seat.

When an object would take a Free license scene past its limit, `add_object` raises
`deformable.TetrahedronLimitExceededError`, a `deformable.LicenseError` like every license failure. Its message is
written to show your user as it is.

## Documentation

- [Getting started](https://docs.tangerina.io/deformable/latest/user-guides/python/getting-started/): install, a first
  simulation, the license and how the package finds the library.
- [User guide](https://docs.tangerina.io/deformable/latest/user-guides/python/): the scene, the tools, render surfaces,
  types and errors.
- [API reference](https://docs.tangerina.io/deformable/latest/api-references/python/): every class, function and field.

## License

The package is proprietary software of Tangerina Inc. Its use is governed by the
[Deformable License Agreement](https://tangerina.io/legal/deformable/license-agreement).

The tetrahedralize tool of the library in the package is based on Netgen and is licensed under the GNU LGPL 2.1. Its
notice is `THIRD_PARTY_NOTICES.txt` in the package.
