deformable 0.1.0__py3-none-win_amd64.whl

deformable/errors.py

@@ -0,0 +1,150 @@
+"""Status codes and the exception a failed library call raises."""
+
+from __future__ import annotations
+
+import ctypes
+import enum
+
+from . import library, native
+
+
+class Status(enum.IntEnum):
+    """The DEFORMABLE_STATUS_* codes of deformable.h."""
+
+    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
+    OPEN_EDGE = 22
+    COULD_NOT_CONVERGE = 23
+    BAD_SCALES = 24
+    MESHING_FAILED = 25
+    NO_TETRAHEDRA = 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 = 49
+
+    @property
+    def is_license(self) -> bool:
+        """Whether 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."""
+        return Status.LICENSE_REQUIRED <= self <= Status.LICENSE_STORAGE_FAILED
+
+
+class DeformableError(Exception):
+    """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, as each status
+    describes in deformable.h; they are 0 when the status names none.
+    """
+
+    def __init__(self, status: Status | int, message: str, first_index: int = 0, second_index: int = 0):
+        super().__init__(f"{_status_name(status)}: {message}")
+        self.status = status
+        self.message = message
+        self.first_index = first_index
+        self.second_index = second_index
+
+
+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 LICENSE_* statuses or TRIAL_LIMIT_EXCEEDED.
+
+    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.
+    """
+
+
+class LicenseRequiredError(LicenseError):
+    """LICENSE_REQUIRED: no usable trial or license on this device, because the trial ended or the license was
+    removed. The message is the license status line, such as "Trial ended — Buy license"."""
+
+
+class TrialLimitExceededError(LicenseError):
+    """TRIAL_LIMIT_EXCEEDED: the trial allows at most `limit` tetrahedrons per simulation, and the call would have
+    made the simulation hold `tetrahedrons`. The message is "Trial limit: 2500 tetrahedrons"."""
+
+    @property
+    def tetrahedrons(self) -> int:
+        """The tetrahedrons the simulation would have held."""
+        return self.first_index
+
+    @property
+    def limit(self) -> int:
+        """The most tetrahedrons a trial simulation may hold."""
+        return self.second_index
+
+
+def _status_name(status: Status | int) -> str:
+    return status.name if isinstance(status, Status) else f"status {status}"
+
+
+def _status(code: int) -> Status | int:
+    # A newer library may return a code this package does not know yet; it is still reported, as a plain int.
+    try:
+        return Status(code)
+    except ValueError:
+        return code
+
+
+def error(status: Status | int, message: str, first_index: int = 0, second_index: int = 0) -> DeformableError:
+    """The exception for a failure: the subclass of DeformableError that matches its status."""
+    if status == Status.LICENSE_REQUIRED:
+        error_type = LicenseRequiredError
+    elif status == Status.TRIAL_LIMIT_EXCEEDED:
+        error_type = TrialLimitExceededError
+    elif isinstance(status, Status) and status.is_license:
+        error_type = LicenseError
+    else:
+        error_type = DeformableError
+    return error_type(status, message, first_index, second_index)
+
+
+def check(code: int) -> None:
+    """Raises the calling thread's last error as a DeformableError, or its license subclass, when a call returned a
+    failure code."""
+    if code == Status.OK:
+        return
+    functions = library.load()
+    message = functions.deformable_last_error_message().decode("utf-8", errors="replace")
+    details = native.ErrorDetails()
+    functions.deformable_last_error_details(ctypes.byref(details))
+    raise error(_status(code), message, details.first_index, details.second_index)

deformable/handles.py

@@ -0,0 +1,97 @@
+"""Ownership of the library's opaque handles."""
+
+from __future__ import annotations
+
+import contextlib
+import ctypes
+import threading
+import weakref
+from collections.abc import Iterator
+
+from . import library, native
+from .errors import check
+
+
+@contextlib.contextmanager
+def temporary_handle(destroy_name: str) -> Iterator[native.Handle]:
+    """An empty handle for a call to fill, destroyed at the end of the block; a result is copied out before then."""
+    handle = native.Handle()
+    try:
+        yield handle
+    finally:
+        # Every _destroy function accepts NULL, so a call that failed before filling the handle needs no test here.
+        getattr(library.load(), destroy_name)(handle)
+
+
+class OwnedHandle:
+    """A handle the Python object owns: destroyed by close(), at the end of a with block, or when collected.
+
+    Library calls release the global interpreter lock, so another thread may close the object while a call on it
+    runs. Every call therefore goes through _use(), and close() refuses new calls, then waits for the ones in flight
+    before destroying the handle.
+    """
+
+    _destroy_name = ""
+    _description = ""
+    _one_call_at_a_time = False
+    """True when the library forbids overlapping calls on one handle; _use() then queues them."""
+
+    def __init__(self, create_name: str):
+        handle = native.Handle()
+        check(getattr(library.load(), create_name)(ctypes.byref(handle)))
+        self._attach(handle)
+
+    def _attach(self, handle: native.Handle) -> None:
+        self._address = handle.value
+        self._condition = threading.Condition()
+        self._calls_in_flight = 0
+        self._close_requested = False
+        destroy = getattr(library.load(), self._destroy_name)
+        self._finalizer = weakref.finalize(self, destroy, self._address)
+
+    @classmethod
+    def _adopt(cls, handle: native.Handle):
+        owner = cls.__new__(cls)
+        owner._attach(handle)
+        return owner
+
+    @property
+    def closed(self) -> bool:
+        """True once the handle has been destroyed."""
+        return not self._finalizer.alive
+
+    @contextlib.contextmanager
+    def _use(self) -> Iterator[int]:
+        """The handle's address, kept alive until the block ends; lent pointers must be read inside the block."""
+        with self._condition:
+            if self._one_call_at_a_time:
+                self._condition.wait_for(lambda: self._calls_in_flight == 0 or self._close_requested)
+            if self._close_requested:
+                raise ValueError(f"the {self._description} is closed")
+            self._calls_in_flight += 1
+        try:
+            yield self._address
+        finally:
+            with self._condition:
+                self._calls_in_flight -= 1
+                self._condition.notify_all()
+
+    def _call(self, function_name: str, *arguments) -> None:
+        """Calls a library function with the handle first, raising DeformableError when it fails."""
+        with self._use() as address:
+            check(getattr(library.load(), function_name)(address, *arguments))
+
+    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."""
+        with self._condition:
+            self._close_requested = True
+            self._condition.notify_all()
+            self._condition.wait_for(lambda: self._calls_in_flight == 0)
+            self._finalizer()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exception_information) -> None:
+        self.close()

deformable/library.py

@@ -0,0 +1,410 @@
+"""Finding and loading libdeformable, the shared library of crates/ffi, with the prototype of every export.
+
+The library is searched in this order:
+
+1. the file named by the DEFORMABLE_LIBRARY environment variable;
+2. the package directory, where a distribution of the package places it;
+3. target/release of the Cargo workspace this package sits in (bindings/python/deformable), where a source checkout
+   builds it.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import functools
+import os
+import sys
+from pathlib import Path
+
+from . import native
+
+ENVIRONMENT_VARIABLE = "DEFORMABLE_LIBRARY"
+
+
+class LibraryNotFoundError(OSError):
+    """No shared library was found in any of the searched places."""
+
+
+def library_file_name(platform: str = sys.platform) -> str:
+    """The file name cargo gives the shared library on a platform (a sys.platform value)."""
+    if platform.startswith("win"):
+        return "deformable.dll"
+    if platform == "darwin":
+        return "libdeformable.dylib"
+    return "libdeformable.so"
+
+
+def candidate_paths() -> list[Path]:
+    """The places searched for the shared library, in search order."""
+    package_directory = Path(__file__).resolve().parent
+    workspace_directory = package_directory.parents[2]
+    candidates = []
+    configured = os.environ.get(ENVIRONMENT_VARIABLE)
+    if configured:
+        candidates.append(Path(configured))
+    candidates.append(package_directory / library_file_name())
+    candidates.append(workspace_directory / "target" / "release" / library_file_name())
+    return candidates
+
+
+@functools.cache
+def load() -> ctypes.CDLL:
+    """The shared library with every export's prototype declared, loaded once per process."""
+    candidates = candidate_paths()
+    for candidate in candidates:
+        if candidate.is_file():
+            library = ctypes.CDLL(str(candidate))
+            declare_prototypes(library)
+            return library
+    searched = ", ".join(str(candidate) for candidate in candidates)
+    raise LibraryNotFoundError(
+        f"libdeformable not found (searched {searched}); reinstall the deformable package for this platform or set "
+        f"{ENVIRONMENT_VARIABLE} to its path"
+    )
+
+
+def declare_prototypes(library: ctypes.CDLL) -> None:
+    """Sets the argument and result types of every export, so ctypes converts and checks each argument."""
+    for name, (result_type, argument_types) in PROTOTYPES.items():
+        function = getattr(library, name)
+        function.restype = result_type
+        function.argtypes = argument_types
+
+
+def _pointer(value_type):
+    return ctypes.POINTER(value_type)
+
+
+_handle_output = _pointer(native.Handle)
+_count_output = _pointer(native.Count)
+_boolean_output = _pointer(native.Boolean)
+_index_output = _pointer(native.Index)
+
+
+def _destroy(name: str) -> tuple[str, tuple]:
+    return name, (None, [native.Handle])
+
+
+def _lend(element_type) -> list:
+    """The arguments of a function that lends one array of an object: simulation, object, array and count."""
+    return [native.Handle, native.Index, _pointer(_pointer(element_type)), _count_output]
+
+
+PROTOTYPES: dict[str, tuple] = dict(
+    [
+        ("deformable_version", (ctypes.c_char_p, [])),
+        ("deformable_last_error_message", (ctypes.c_char_p, [])),
+        ("deformable_last_error_details", (native.Status, [_pointer(native.ErrorDetails)])),
+        # Declared for parity with deformable.h, which tests/test_native.py checks; the package never calls it, since
+        # check() reads the error right after the call that failed and the next successful call clears it.
+        ("deformable_last_error_clear", (native.Status, [])),
+        # License.
+        ("deformable_license_status", (native.Status, [_pointer(native.LicenseStatus)])),
+        ("deformable_license_refresh", (native.Status, [ctypes.c_uint32, _pointer(native.LicenseStatus)])),
+        (
+            "deformable_license_activate",
+            (native.Status, [_pointer(ctypes.c_char), ctypes.c_uint32, _pointer(native.LicenseStatus)]),
+        ),
+        ("deformable_license_deactivate", (native.Status, [ctypes.c_uint32, _pointer(native.LicenseStatus)])),
+        ("deformable_license_set_online_access", (native.Status, [native.Boolean])),
+        # Cancel flags.
+        ("deformable_cancel_flag_create", (native.Status, [_handle_output])),
+        _destroy("deformable_cancel_flag_destroy"),
+        ("deformable_cancel_flag_set", (native.Status, [native.Handle, native.Boolean])),
+        ("deformable_cancel_flag_is_set", (native.Status, [native.Handle, _boolean_output])),
+        # Meshes.
+        ("deformable_face_corners", (native.Status, [native.Index, _pointer(native.TriangleIndices)])),
+        (
+            "deformable_tetrahedral_mesh_view",
+            (native.Status, [native.Handle, _pointer(native.TetrahedralMeshView)]),
+        ),
+        _destroy("deformable_tetrahedral_mesh_destroy"),
+        ("deformable_polygon_mesh_view", (native.Status, [native.Handle, _pointer(native.PolygonMeshView)])),
+        _destroy("deformable_polygon_mesh_destroy"),
+        (
+            "deformable_triangle_surface_view",
+            (native.Status, [native.Handle, _pointer(native.TriangleSurfaceView)]),
+        ),
+        _destroy("deformable_triangle_surface_destroy"),
+        (
+            "deformable_boundary_faces",
+            (native.Status, [_pointer(native.TetrahedralMeshView), _handle_output]),
+        ),
+        (
+            "deformable_boundary_faces_masks",
+            (native.Status, [native.Handle, _pointer(_pointer(ctypes.c_uint8)), _count_output]),
+        ),
+        _destroy("deformable_boundary_faces_destroy"),
+        # Tools.
+        ("deformable_anisotropy_default", (native.Status, [_pointer(native.Anisotropy)])),
+        (
+            "deformable_triangulate_parameters_default",
+            (native.Status, [_pointer(native.TriangulateParameters)]),
+        ),
+        (
+            "deformable_triangulate",
+            (
+                native.Status,
+                [
+                    _pointer(native.PolygonMeshView),
+                    _pointer(native.FaceHole),
+                    native.Count,
+                    _pointer(native.TriangulateParameters),
+                    native.Handle,
+                    _handle_output,
+                ],
+            ),
+        ),
+        (
+            "deformable_triangulation_view",
+            (native.Status, [native.Handle, _pointer(native.TriangulationView)]),
+        ),
+        _destroy("deformable_triangulation_destroy"),
+        (
+            "deformable_tetrahedralize",
+            (
+                native.Status,
+                [
+                    _pointer(native.TriangleSurfaceView),
+                    _pointer(native.TetrahedralizeParameters),
+                    native.Handle,
+                    _handle_output,
+                ],
+            ),
+        ),
+        (
+            "deformable_tetrahedralization_view",
+            (native.Status, [native.Handle, _pointer(native.TetrahedralizationView)]),
+        ),
+        _destroy("deformable_tetrahedralization_destroy"),
+        (
+            "deformable_extrude",
+            (
+                native.Status,
+                [_pointer(native.TriangleSurfaceView), ctypes.c_double, native.Enumeration, _handle_output],
+            ),
+        ),
+        (
+            "deformable_span_layers",
+            (
+                native.Status,
+                [_pointer(native.TriangleSurfaceView), _pointer(native.TriangleSurfaceView), _handle_output],
+            ),
+        ),
+        ("deformable_autocage_parameters_default", (native.Status, [_pointer(native.AutocageParameters)])),
+        (
+            "deformable_autocage",
+            (
+                native.Status,
+                [
+                    _pointer(native.PolygonMeshView),
+                    _pointer(native.AutocageParameters),
+                    native.Handle,
+                    _handle_output,
+                ],
+            ),
+        ),
+        (
+            "deformable_splinter_image_parameters_default",
+            (native.Status, [_pointer(native.SplinterImageParameters)]),
+        ),
+        (
+            "deformable_splinters_from_image",
+            (
+                native.Status,
+                [_pointer(native.PixelGrid), _pointer(native.SplinterImageParameters), _handle_output],
+            ),
+        ),
+        ("deformable_mesh_checks_default", (native.Status, [_pointer(native.MeshChecks)])),
+        (
+            "deformable_verify_surface",
+            (
+                native.Status,
+                [
+                    _pointer(native.SurfaceMeshView),
+                    _pointer(native.FaceHole),
+                    native.Count,
+                    _pointer(native.MeshChecks),
+                    _handle_output,
+                ],
+            ),
+        ),
+        (
+            "deformable_mesh_issue_list_issues",
+            (native.Status, [native.Handle, _pointer(_pointer(native.MeshIssue)), _count_output]),
+        ),
+        _destroy("deformable_mesh_issue_list_destroy"),
+        (
+            "deformable_meshes_intersect",
+            (
+                native.Status,
+                [_pointer(native.TetrahedralMeshView), _pointer(native.TetrahedralMeshView), _boolean_output],
+            ),
+        ),
+        # Simulation.
+        ("deformable_simulation_create", (native.Status, [_handle_output])),
+        _destroy("deformable_simulation_destroy"),
+        ("deformable_simulation_set_scale", (native.Status, [native.Handle, ctypes.c_double])),
+        ("deformable_simulation_set_gravity", (native.Status, [native.Handle, native.Vector3])),
+        ("deformable_simulation_set_worker_count", (native.Status, [native.Handle, native.Count])),
+        ("deformable_material_parameters_default", (native.Status, [_pointer(native.MaterialParameters)])),
+        ("deformable_material_preset_count", (native.Count, [])),
+        (
+            "deformable_material_preset",
+            (
+                native.Status,
+                [native.Count, _pointer(_pointer(ctypes.c_char)), _pointer(native.MaterialParameters)],
+            ),
+        ),
+        (
+            "deformable_material_preset_find",
+            (native.Status, [_pointer(ctypes.c_char), _pointer(native.MaterialParameters)]),
+        ),
+        (
+            "deformable_simulation_add_material",
+            (native.Status, [native.Handle, _pointer(native.MaterialParameters), _index_output]),
+        ),
+        (
+            "deformable_simulation_set_material",
+            (native.Status, [native.Handle, native.Index, _pointer(native.MaterialParameters)]),
+        ),
+        ("deformable_object_options_default", (native.Status, [_pointer(native.ObjectOptions)])),
+        (
+            "deformable_simulation_add_object",
+            (
+                native.Status,
+                [
+                    native.Handle,
+                    _pointer(native.TetrahedralMeshView),
+                    _pointer(native.TetrahedronMaterials),
+                    _pointer(native.ObjectOptions),
+                    _index_output,
+                ],
+            ),
+        ),
+        (
+            "deformable_simulation_set_object_material",
+            (native.Status, [native.Handle, native.Index, _pointer(native.TetrahedronMaterials)]),
+        ),
+        ("deformable_simulation_remove_object", (native.Status, [native.Handle, native.Index])),
+        (
+            "deformable_simulation_set_object_disabled",
+            (native.Status, [native.Handle, native.Index, native.Boolean]),
+        ),
+        (
+            "deformable_simulation_set_self_collision",
+            (native.Status, [native.Handle, native.Index, native.Boolean]),
+        ),
+        (
+            "deformable_simulation_set_never_sleep",
+            (native.Status, [native.Handle, native.Index, native.Index, native.Boolean]),
+        ),
+        (
+            "deformable_simulation_set_glue_all",
+            (native.Status, [native.Handle, _pointer(native.GlueParameters)]),
+        ),
+        (
+            "deformable_simulation_add_glue_region",
+            (
+                native.Status,
+                [
+                    native.Handle,
+                    _pointer(native.ConvexRegion),
+                    _pointer(native.Index),
+                    native.Count,
+                    _pointer(native.GlueParameters),
+                ],
+            ),
+        ),
+        (
+            "deformable_convex_region_contains",
+            (native.Status, [_pointer(native.ConvexRegion), native.Vector3, _boolean_output]),
+        ),
+        (
+            "deformable_simulation_drive",
+            (native.Status, [native.Handle, native.Index, _pointer(native.DrivenVertex), native.Count]),
+        ),
+        (
+            "deformable_simulation_add_force",
+            (native.Status, [native.Handle, native.Index, native.Index, native.Vector3]),
+        ),
+        (
+            "deformable_simulation_step",
+            (
+                native.Status,
+                [native.Handle, ctypes.c_double, ctypes.c_uint32, native.Handle, _pointer(native.StepReport)],
+            ),
+        ),
+        ("deformable_simulation_skip_to", (native.Status, [native.Handle, ctypes.c_double])),
+        ("deformable_simulation_node_positions", (native.Status, _lend(native.Vector3))),
+        ("deformable_simulation_node_velocities", (native.Status, _lend(native.Vector3))),
+        ("deformable_simulation_node_masses", (native.Status, _lend(ctypes.c_double))),
+        ("deformable_simulation_tetrahedron_nodes", (native.Status, _lend(native.TetrahedronIndices))),
+        ("deformable_simulation_tetrahedron_states", (native.Status, _lend(native.TetrahedronState))),
+        ("deformable_simulation_face_events", (native.Status, _lend(native.FaceEvent))),
+        ("deformable_simulation_awake_tetrahedron_count", (native.Status, [native.Handle, _count_output])),
+        (
+            "deformable_simulation_statistics",
+            (native.Status, [native.Handle, _pointer(native.SimulationStatistics)]),
+        ),
+        (
+            "deformable_tetrahedron_state_face_centroid",
+            (native.Status, [_pointer(native.TetrahedronState), native.Index, _pointer(native.Vector3)]),
+        ),
+        (
+            "deformable_tetrahedron_state_face_normal",
+            (native.Status, [_pointer(native.TetrahedronState), native.Index, _pointer(native.Vector3)]),
+        ),
+        # Material regions.
+        (
+            "deformable_material_region_indices",
+            (
+                native.Status,
+                [_pointer(native.TetrahedralMeshView), _pointer(native.MaterialRegion), native.Count, _handle_output],
+            ),
+        ),
+        (
+            "deformable_material_region_indices_values",
+            (native.Status, [native.Handle, _pointer(_pointer(native.Index)), _count_output]),
+        ),
+        _destroy("deformable_material_region_indices_destroy"),
+        # Render surfaces.
+        (
+            "deformable_embed_surface",
+            (
+                native.Status,
+                [
+                    _pointer(native.TetrahedralMeshView),
+                    _pointer(native.SurfaceMeshView),
+                    _pointer(native.PreparationParameters),
+                    _handle_output,
+                ],
+            ),
+        ),
+        (
+            "deformable_surface_embedding_view",
+            (native.Status, [native.Handle, _pointer(native.SurfaceEmbeddingView)]),
+        ),
+        (
+            "deformable_surface_embedding_deform",
+            (
+                native.Status,
+                [
+                    native.Handle,
+                    _pointer(native.TetrahedronState),
+                    native.Count,
+                    _pointer(native.AffineTransform),
+                    _pointer(native.SkinningOptions),
+                    native.Handle,
+                ],
+            ),
+        ),
+        _destroy("deformable_surface_embedding_destroy"),
+        ("deformable_deformed_surface_create", (native.Status, [_handle_output])),
+        (
+            "deformable_deformed_surface_view",
+            (native.Status, [native.Handle, _pointer(native.DeformedSurfaceView)]),
+        ),
+        _destroy("deformable_deformed_surface_destroy"),
+    ]
+)