You are viewing the documentation for Deformable v0.1.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
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 trial’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(Statusorint)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. ALicenseError’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 that would take part in a trial scene), or 0. Default0.second_index(int)The second element index the status names (the region’s polygon, the edge’s second vertex, or the trial’s tetrahedron limit), or 0. Default0.
Example
try:
scene.set_worker_count(0)
except deformable.DeformableError as error:
print(error.status.name, error.first_index)
# INVALID_WORKER_COUNT 0See also Guide: DeformableError · C DeformableErrorDetails · Rust Error
Status
Enum · deformable.Status
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
LICENSE_REQUIRED = 44
TRIAL_LIMIT_EXCEEDED = 45
LICENSE_NEEDS_ONLINE = 46
LICENSE_SERVICE_UNAVAILABLE = 47
LICENSE_KEY_REJECTED = 48
LICENSE_STORAGE_FAILED = 49What 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; noDeformableErrorcarries 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, and for another key while one is stored.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 toolsfirst_indexnames 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 tetrahedronfirst_indexnames has a positive orientation determinant above 1e-15 and at most 1e-9, or a NaN one.DEGENERATE_TETRAHEDRON_FLAT(12)The tetrahedronfirst_indexnames has an orientation determinant of magnitude at most 1e-15.DEGENERATE_TETRAHEDRON_INVERTED(13)The tetrahedronfirst_indexnames 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 polygonsecond_indexnames, of the material regionfirst_indexnames, 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, forautocage, the targets ask for triangles finer than the tool resolves.DEGENERATE_POLYGON(20)The polygonfirst_indexnames 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 verticesfirst_indexandsecond_indexborders three or more polygons.NON_CLOSED_BOUNDARY(22)The edge between the verticesfirst_indexandsecond_indexborders 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 facefirst_indexnames has a vertex past the end of the positions.DUPLICATE_VERTEX(31)The facefirst_indexnames uses one vertex at two corners.MULTIPLE_BOUNDARIES(32)The faces around the vertexfirst_indexnames form more than one fan.DEGENERATE_FACE(33)The facefirst_indexnames has a zero normal.NULL_NORMAL(34)The angle-weighted normals around the vertexfirst_indexnames cancel out.EMPTY_INPUT(35)No polygon has three or more corners, or all the vertices they use coincide.STEP_LIMIT_REACHED(36)Theautocagefront 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.LICENSE_REQUIRED(44)No usable trial or license on this device: the trial ended, this device cannot have one, or the license was removed. It raisesLicenseRequiredError, whose message is the license status line, such as “Trial ended — Buy license”, written to show the user as it is.TRIAL_LIMIT_EXCEEDED(45)The trial allows at most 2,500 tetrahedrons per scene and the call would go over. It raisesTrialLimitExceededError:tetrahedronsis the count that would take part, those of the scene’s enabled objects (a disabled object does not count),limitthe limit, and the message says both, such as “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.LICENSE_NEEDS_ONLINE(46)One online check is needed: the trial never started, the license went without a renewal for longer than it may run offline, or the clock is behind. The message is the license status line.LICENSE_KEY_REJECTED(48)The licensing service refused the license key: unknown, revoked or expired, of another product, or its seat is in use on another device; or the service takes no more devices.LICENSE_STORAGE_FAILED(49)The per-user license state 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
@property
def is_license(self) -> boolWhether the status is about the license of this device and user, rather than the call’s arguments: its message is a status line or a licensing service’s answer, written for the user as it is.
It is true for the six license statuses, from LICENSE_REQUIRED to LICENSE_STORAGE_FAILED, the ones that raise LicenseError.
Example
deformable.Status.TRIAL_LIMIT_EXCEEDED.is_license
# True
deformable.Status.INVALID_ARGUMENT.is_license
# FalseSee also Rust ErrorKind::is_license
LicenseError
Exception · deformable.LicenseError
class LicenseError(DeformableError)The license of this device and user refused a call, or the licensing service could not be reached or refused the key: one of the six statuses whose Status.is_license is true, LICENSE_REQUIRED to LICENSE_STORAGE_FAILED.
Its message is written for the user as it is, such as “Trial ended — Buy license”, so a host shows message alone, without the status name. LICENSE_REQUIRED and TRIAL_LIMIT_EXCEEDED raise its subclasses LicenseRequiredError and TrialLimitExceededError.
Example
try:
report = scene.step(1.0, substeps=10)
except deformable.TrialLimitExceededError as error:
print(error.tetrahedrons, "over", error.limit)
except deformable.LicenseError as error:
print(error.message)See also Guide: License errors
LicenseRequiredError
Exception · deformable.LicenseRequiredError
class LicenseRequiredError(LicenseError)LICENSE_REQUIRED: no usable trial or license on this device, because the trial ended, this device cannot have one, or the license was removed. The message is the license status line, such as “Trial ended — Buy license”.
See also Guide: License errors
TrialLimitExceededError
Exception · deformable.TrialLimitExceededError
class TrialLimitExceededError(LicenseError)TRIAL_LIMIT_EXCEEDED: the trial allows at most limit tetrahedrons per scene, and with the call tetrahedrons would take part, those of the scene’s enabled objects (a disabled object does not count). The message says both, such as “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.
See also Guide: License errors
TrialLimitExceededError.tetrahedrons
Property · deformable.TrialLimitExceededError.tetrahedrons
@property
def tetrahedrons(self) -> intThe tetrahedrons the scene would have held: the error’s first_index.
TrialLimitExceededError.limit
Property · deformable.TrialLimitExceededError.limit
@property
def limit(self) -> intThe most tetrahedrons a trial scene may hold, 2,500: the error’s second_index.
library_version
Function · deformable.library_version
def library_version() -> strThe 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
version = deformable.library_version()
len(version.split("."))
# 3See also Guide: Versions · C deformable_version · Rust version
LibraryNotFoundError
Exception · deformable.LibraryNotFoundError
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
class CancelFlag:
def __init__(self) -> NoneA 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
with deformable.CancelFlag() as cancel:
cancel.set()
try:
deformable.triangulate(polygons, cancel=cancel)
except deformable.DeformableError as error:
print(error.status.name)
# CANCELLEDSee also Guide: Cancel a long call · C DeformableCancelFlag · Rust CancelFlag
CancelFlag.set
Method · deformable.CancelFlag.set
def set(self) -> NoneSets 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
def clear(self) -> NoneClears the flag, so it can be used again.
Raises
ValueError when the flag is closed.
CancelFlag.is_set
Method · deformable.CancelFlag.is_set
def is_set(self) -> boolTrue 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
@property
def closed(self) -> boolTrue once the handle has been destroyed.
CancelFlag.close
Method · deformable.CancelFlag.close
def close(self) -> NoneDestroys 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