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

Python API Reference

Errors

Errors and status codes, the library version, and the cancel flag that stops a long call.

On this page

What a failed call reports: the Status that names what went wrong, and the DeformableError that carries it. Then the library version, and the CancelFlag that stops a long call from another thread.

DeformableError

Exception · deformable.DeformableError

python
class DeformableError(Exception):
    def __init__(
        self,
        status: Status | int,
        message: str,
        first_index: int = 0,
        second_index: int = 0,
    )

A library call failed: its status, the library’s message and up to two element indices.

The indices name the tetrahedron, region, polygon, face, vertex or edge the failure concerns, or the Free license’s tetrahedron count and limit, as each Status member says; they are 0 when the status names none. str(error) is the status name, a colon and the message. Arguments the package refuses before calling the library raise ValueError or TypeError instead.

Fields

  • status (Status or int)What went wrong; a plain int for a code a newer library returns that this package does not know yet.
  • message (str)The library’s message, in English. A LicenseError’s is written for the user, to show as it is.
  • first_index (int)The first element index the status names (the tetrahedron, region, polygon, face, vertex or edge’s first vertex, or the tetrahedrons a Free license scene would simulate), or 0. Default 0.
  • second_index (int)The second element index the status names (the region’s polygon, the edge’s second vertex, or the Free license’s tetrahedron limit), or 0. Default 0.

Example

python
try:
    scene.set_worker_count(0)
except deformable.DeformableError as error:
    print(error.status.name, error.first_index)
# INVALID_WORKER_COUNT 0

See also Guide: DeformableError · C DeformableErrorDetails · Rust Error

Status

Enum · deformable.Status

python
class Status(enum.IntEnum):
    OK = 0
    NULL_POINTER = 1
    INVALID_ARGUMENT = 2
    PANICKED = 3
    INDEX_OUT_OF_RANGE = 4
    UNKNOWN_MATERIAL = 5
    UNKNOWN_OBJECT = 6
    LENGTH_MISMATCH = 7
    NON_FINITE_VALUE = 8
    EMPTY_MESH = 9
    NON_MANIFOLD_FACE = 10
    DEGENERATE_TETRAHEDRON_TOO_SMALL = 11
    DEGENERATE_TETRAHEDRON_FLAT = 12
    DEGENERATE_TETRAHEDRON_INVERTED = 13
    SCALE_OUT_OF_RANGE = 14
    DEGENERATE_REGION = 15
    TIME_WENT_BACKWARDS = 16
    INVALID_WORKER_COUNT = 17
    CANCELLED = 18
    OUTPUT_TOO_LARGE = 19
    DEGENERATE_POLYGON = 20
    NON_MANIFOLD_EDGE = 21
    NON_CLOSED_BOUNDARY = 22
    COULD_NOT_CONVERGE = 23
    BAD_SCALES = 24
    MESHING_FAILED = 25
    NO_TETRAHEDRONS = 26
    INVALID_CAGE = 27
    NON_POSITIVE_THICKNESS = 28
    NOT_ISOMORPHIC = 29
    UNKNOWN_VERTEX = 30
    DUPLICATE_VERTEX = 31
    MULTIPLE_BOUNDARIES = 32
    DEGENERATE_FACE = 33
    NULL_NORMAL = 34
    EMPTY_INPUT = 35
    STEP_LIMIT_REACHED = 36
    INVALID_SPLINTER_CAGE = 37
    EMPTY_IMAGE = 38
    NO_VERTICES = 39
    NO_CELLS = 40
    ENDLESS_CYCLE = 41
    FACE_ALREADY_SET = 42
    SINGULAR_TRANSFORM = 43
    TETRAHEDRON_LIMIT_EXCEEDED = 44
    LICENSE_SERVICE_UNAVAILABLE = 45
    LICENSE_KEY_REJECTED = 46
    LICENSE_STORAGE_FAILED = 47

What a failed library call reports, in DeformableError.status: one member per status code of the library.

The indices of the DeformableError name the element a status concerns, as each member says; they are 0 when it names none. A newer library can add statuses: a code this package does not know comes as a plain int.

Values

  • OK (0)The call succeeded; no DeformableError carries it.
  • NULL_POINTER (1)A required argument was missing at the library boundary. The package never lets one through, so seeing it means a defect in this package.
  • INVALID_ARGUMENT (2)An argument the library cannot read: an enumeration value it does not define, an array larger than the address space, or a material preset name it does not ship. The license calls give it for text that is no license key, an Application license key that does not verify, another Standalone key while one is stored, another Application key once one is set, and a Standalone key in a program on an Application license.
  • PANICKED (3)The library panicked; the objects the call used should be closed.
  • INDEX_OUT_OF_RANGE (4)An index points past the end of the list it indexes; for the polygon tools first_index names the polygon.
  • UNKNOWN_MATERIAL (5)A material handle names no material of the scene.
  • UNKNOWN_OBJECT (6)An object handle names no object of the scene, or a removed one.
  • LENGTH_MISMATCH (7)A list does not have the length its partner requires.
  • NON_FINITE_VALUE (8)A position or parameter is NaN or infinite.
  • EMPTY_MESH (9)A mesh has no tetrahedrons, vertices or polygons.
  • NON_MANIFOLD_FACE (10)Three or more tetrahedrons share one face.
  • DEGENERATE_TETRAHEDRON_TOO_SMALL (11)The tetrahedron first_index names has a positive orientation determinant above 1e-15 and at most 1e-9, or a NaN one.
  • DEGENERATE_TETRAHEDRON_FLAT (12)The tetrahedron first_index names has an orientation determinant of magnitude at most 1e-15.
  • DEGENERATE_TETRAHEDRON_INVERTED (13)The tetrahedron first_index names is ordered right-handed: its orientation determinant is below -1e-15.
  • SCALE_OUT_OF_RANGE (14)The length scale lies outside [0.001, 1,000].
  • DEGENERATE_REGION (15)The polygon second_index names, of the material region first_index names, has fewer than 3 vertices or a zero normal.
  • TIME_WENT_BACKWARDS (16)A step’s time lies before the last step’s time.
  • INVALID_WORKER_COUNT (17)A worker count of 0.
  • CANCELLED (18)The cancel flag stopped a tool.
  • OUTPUT_TOO_LARGE (19)The output would hold more elements than 32-bit indices address, or, for autocage, the targets ask for triangles finer than the tool resolves.
  • DEGENERATE_POLYGON (20)The polygon first_index names has a loop of fewer than 3 vertices, a zero normal or loops the triangulator cannot mesh.
  • NON_MANIFOLD_EDGE (21)The edge between the vertices first_index and second_index borders three or more polygons.
  • NON_CLOSED_BOUNDARY (22)The edge between the vertices first_index and second_index borders only one polygon.
  • COULD_NOT_CONVERGE (23)The triangulation of a polygon mesh did not settle at any quality.
  • BAD_SCALES (24)An anisotropy scale or direction is NaN.
  • MESHING_FAILED (25)The mesher stopped without a mesh, or the maximum edge length is 0 or less.
  • NO_TETRAHEDRONS (26)The mesh has no tetrahedron.
  • INVALID_CAGE (27)The cage is not closed, does not face outward, or crosses itself.
  • NON_POSITIVE_THICKNESS (28)The extrusion thickness is 0, negative or NaN.
  • NOT_ISOMORPHIC (29)The two layers do not have the same vertices and faces.
  • UNKNOWN_VERTEX (30)The face first_index names has a vertex past the end of the positions.
  • DUPLICATE_VERTEX (31)The face first_index names uses one vertex at two corners.
  • MULTIPLE_BOUNDARIES (32)The faces around the vertex first_index names form more than one fan.
  • DEGENERATE_FACE (33)The face first_index names has a zero normal.
  • NULL_NORMAL (34)The angle-weighted normals around the vertex first_index names cancel out.
  • EMPTY_INPUT (35)No polygon has three or more corners, or all the vertices they use coincide.
  • STEP_LIMIT_REACHED (36)The autocage front did not close within its step cap.
  • INVALID_SPLINTER_CAGE (37)A splinter cage polygon has fewer than 3 vertices, or a brick has 3 faces or fewer.
  • EMPTY_IMAGE (38)The image width or height is 0.
  • NO_VERTICES (39)The image has no vertex pixel, or none is left after the cleanup.
  • NO_CELLS (40)The image has vertices but no closed cell.
  • ENDLESS_CYCLE (41)A splinter face trace took more steps than there are vertices.
  • FACE_ALREADY_SET (42)A splinter face trace met an edge side another face already holds.
  • SINGULAR_TRANSFORM (43)The world transform has no inverse: its linear part is singular, or its inverse overflows.
  • TETRAHEDRON_LIMIT_EXCEEDED (44)Under the Free license, adding the object would take the scene past the 2,500 tetrahedrons one scene simulates. It raises TetrahedronLimitExceededError: tetrahedrons is the count the scene would simulate with it (those of the objects it simulates now, and the object’s), limit the limit, and the message says both, such as “Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”. Nothing is created and the rest of the scene runs.
  • LICENSE_SERVICE_UNAVAILABLE (45)The licensing service could not be reached (no network, a timeout, a busy service), did not answer, or gave an answer that did not verify or that this device’s clock contradicts; or online access is off in this process.
  • LICENSE_KEY_REJECTED (46)The license key was refused. The licensing service refused the Standalone 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 Application key was revoked, is a trial key that ended, covers only versions released before this one, or was given inside a plugin host.
  • LICENSE_STORAGE_FAILED (47)The per-user license store could not be written; the message names its folder.

See also Guide: Errors · C DeformableStatus · Rust ErrorKind

Status.is_license

Property · deformable.Status.is_license

python
@property
def is_license(self) -> bool

Whether the status is about the license of this program, rather than the call’s arguments: its message is a status line, a licensing service’s answer or why an Application key was refused, written for the user as it is.

It is true for the four license statuses, from TETRAHEDRON_LIMIT_EXCEEDED to LICENSE_STORAGE_FAILED, the ones that raise LicenseError.

Example

python
deformable.Status.TETRAHEDRON_LIMIT_EXCEEDED.is_license
# True
deformable.Status.INVALID_ARGUMENT.is_license
# False

See also Rust ErrorKind::is_license

LicenseError

Exception · deformable.LicenseError

python
class LicenseError(DeformableError)

A license failure: an object past the Free license’s limit, the licensing service could not be reached, or a license key was refused. One of the four statuses whose Status.is_license is true, TETRAHEDRON_LIMIT_EXCEEDED to LICENSE_STORAGE_FAILED.

Its message is written for the user as it is, such as “This license key was revoked”, so a host shows message alone, without the status name. TETRAHEDRON_LIMIT_EXCEEDED raises its subclass TetrahedronLimitExceededError.

Example

python
try:
    handle = scene.add_object(mesh, material)
except deformable.TetrahedronLimitExceededError as error:
    print(error.tetrahedrons, "over", error.limit)
except deformable.LicenseError as error:
    print(error.message)

See also Guide: License errors

TetrahedronLimitExceededError

Exception · deformable.TetrahedronLimitExceededError

python
class TetrahedronLimitExceededError(LicenseError)

TETRAHEDRON_LIMIT_EXCEEDED: under the Free license a scene simulates at most limit tetrahedrons, and with the object it would simulate tetrahedrons. The object is not created and the rest of the scene runs. The message says both, such as “Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.

See also Guide: License errors

TetrahedronLimitExceededError.tetrahedrons

Property · deformable.TetrahedronLimitExceededError.tetrahedrons

python
@property
def tetrahedrons(self) -> int

The tetrahedrons the scene would have simulated: the error’s first_index.

TetrahedronLimitExceededError.limit

Property · deformable.TetrahedronLimitExceededError.limit

python
@property
def limit(self) -> int

The most tetrahedrons a Free license scene simulates, 2,500: the error’s second_index.

library_version

Function · deformable.library_version

python
def library_version() -> str

The version of the loaded shared library, as major.minor.patch. It matches deformable.__version__ when the package and the library come from the same release.

Raises

LibraryNotFoundError when no shared library is found; this call loads it when no call has yet.

Example

python
version = deformable.library_version()
len(version.split("."))
# 3

See also Guide: Versions · C deformable_version · Rust version

LibraryNotFoundError

Exception · deformable.LibraryNotFoundError

python
class LibraryNotFoundError(OSError)

No shared library was found. The package loads it the first time a call needs it, from the first of these places that holds it: the file the DEFORMABLE_LIBRARY environment variable names, the package directory, where a distribution of the package places it, then target/release of the Cargo workspace the package sits in, where a source checkout builds it. The message lists the places searched.

See also Guide: How the package finds the library

CancelFlag

Class · deformable.CancelFlag

python
class CancelFlag:
    def __init__(self) -> None

A thread-safe cancel flag, not set when created: set from any thread, it stops a running tool, which raises DeformableError with the status CANCELLED, or a running step, which reports StepOutcome.CANCELLED.

Scene.step, triangulate, tetrahedralize and autocage take one and stop at their next check once it is set: a tool at once when it is already set, a step after its first substep. The flag stays set until it is cleared, and one flag can serve several calls at once. Library calls release the global interpreter lock, so one Python thread can set the flag while another runs a step or a tool that was given it.

It works as a context manager: a with block calls close() when it ends.

Example

python
with deformable.CancelFlag() as cancel:
    cancel.set()
    try:
        deformable.triangulate(polygons, cancel=cancel)
    except deformable.DeformableError as error:
        print(error.status.name)
# CANCELLED

See also Guide: Cancel a long call · C DeformableCancelFlag · Rust CancelFlag

CancelFlag.set

Method · deformable.CancelFlag.set

python
def set(self) -> None

Sets the flag; a call that reads it stops at its next check.

Raises

ValueError when the flag is closed.

See also C deformable_cancel_flag_set · Rust CancelFlag::set

CancelFlag.clear

Method · deformable.CancelFlag.clear

python
def clear(self) -> None

Clears the flag, so it can be used again.

Raises

ValueError when the flag is closed.

CancelFlag.is_set

Method · deformable.CancelFlag.is_set

python
def is_set(self) -> bool

True while the flag is set.

Raises

ValueError when the flag is closed.

See also C deformable_cancel_flag_is_set · Rust CancelFlag::is_set

CancelFlag.closed

Property · deformable.CancelFlag.closed

python
@property
def closed(self) -> bool

True once the handle has been destroyed.

CancelFlag.close

Method · deformable.CancelFlag.close

python
def close(self) -> None

Destroys the handle once the calls in flight on it end; later calls on the object raise ValueError. Closing twice does nothing.

See also C deformable_cancel_flag_destroy