Metadata-Version: 2.3
Name: deformable
Version: 0.2.1
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 the library checks before every engine call: the
  Standard license and its trial on this computer, or a Developer 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.

## Standard and Developer licenses

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

The Standard license is for one person on one computer, and works in the Blender and Maya plugins and the C, Rust and
Python SDKs. Its free trial starts on the first engine call, or on `deformable.license.refresh()`. It needs the internet
once, runs 7 days and allows up to 2,500 tetrahedrons per scene: an object that would go over is not added, and the rest
of the scene runs. After 7 days the engine calls stop until a license is activated. The Standard license costs $99 one
time (USD), on the payment page. It is 1 seat (one computer), perpetual and with no subscription; it covers all future
versions and includes email support at support@tangerina.io. Its key, activated online, removes the limit; it renews by
itself whenever the program runs online, and works offline between renewals, which are needed at least once every 7 days
of use. The plugins and every SDK on the computer share one Standard trial and one Standard license. It can be refunded
within 14 days of purchase.

The Developer license is for one company that ships the engine inside one application, and works in the C, Rust and
Python SDKs only: the plugins refuse its key. Its free trial is a 30-day trial key that we email you when you ask, with
no tetrahedron limit; when the trial key ends, the engine calls stop. It has no public price: to buy one, or to ask for
a trial key, contact us at support@tangerina.io. It covers any number of users of that application, perpetual and with
no subscription; it covers all future versions and includes email support at support@tangerina.io. Its key is checked
offline and is kept only while the program runs, so your application 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 once the
full key is sent, so try it first with the 30-day trial key.

```python
import deformable

# A Standard key, or a Developer key as it was sent: "TGDF-<payload>.<signature>".
deformable.license.activate("TGDF-XXXX-XXXX-XXXX")
# "Standard trial: 7 days left", "Standard license", "Developer license: Acme Inc.", ...
print(deformable.license.status().message)
```

The Standard trial and the Standard license belong to each computer that runs your script: on a colleague's computer,
a server or a render farm node it starts its own Standard trial and needs its own seat to keep running after 7 days.
To ship the engine inside an application you give to others, you need a Developer license: contact us at
support@tangerina.io. Your application then activates its key at every start, offline, and its users need no
activation, network or seat.

When the trial or license does not allow a call, it raises `deformable.LicenseError`, a `DeformableError`. 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
[terms of use](https://tangerina.io/terms-of-use).

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.
