deformable 0.1.0__py3-none-win_amd64.whl

deformable/license.py

@@ -0,0 +1,154 @@
+"""The license of this device and user: its state, and starting, renewing, activating and deactivating it with our
+licensing service.
+
+The library keeps one license state per device and user, shared by every program that loads it: the Blender plugin,
+this package and the other SDKs. Engine calls check it themselves and raise LicenseError when the trial or license
+does not allow them: LicenseRequiredError once the trial ended or the license was removed, TrialLimitExceededError for
+a trial simulation past its tetrahedron limit, and LicenseError itself when one online check is needed. The error's
+message is written for the user, such as "Trial ended — Buy license" or "Trial limit: 2500 tetrahedrons".
+
+status() never contacts the service and is cheap enough for every redraw. refresh(), activate() and deactivate() wait
+on the network for at most their timeout, with the global interpreter lock released, so a host with an interface
+runs them off its main thread. set_online_access() keeps a process off the network when its user asked for that.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+import enum
+import math
+
+from . import errors, library, native
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "LicenseState",
+    "LicenseStatus",
+    "activate",
+    "deactivate",
+    "refresh",
+    "set_online_access",
+    "status",
+]
+
+DEFAULT_TIMEOUT = 15.0
+"""How long refresh(), activate() and deactivate() wait for the licensing service by default, in seconds."""
+
+_LARGEST_TIMEOUT_MILLISECONDS = 0xFFFFFFFF
+
+
+class LicenseState(enum.IntEnum):
+    """The DEFORMABLE_LICENSE_STATE_* values of deformable.h."""
+
+    NOT_STARTED = 0
+    """No trial or license yet: the next refresh(), or the first engine call, starts the trial online."""
+    TRIAL = 1
+    """The trial runs: every feature, at most tetrahedron_limit tetrahedrons per simulation."""
+    TRIAL_ENDED = 2
+    """The trial ended, or this device cannot have one; engine calls fail until a license is activated."""
+    LICENSED = 3
+    """A license is active on this device; no limit."""
+    NEEDS_ONLINE = 4
+    """A license (or the trial) needs one online check before engine calls work again."""
+    DEVELOPMENT = 5
+    """A development build of the library: licensing is off and nothing contacts the licensing service."""
+
+
+@dataclasses.dataclass(frozen=True)
+class LicenseStatus:
+    """The license state as a status line shows it."""
+
+    state: LicenseState | int
+    """The state; a plain int for a state a newer library reports that this package does not know yet."""
+    days_left: int
+    """In TRIAL, the whole days left, 7 down to 1, counting the current day; 0 in any other state."""
+    tetrahedron_limit: int | None
+    """The most tetrahedrons one simulation may hold in TRIAL; None when there is no limit."""
+    usable: bool
+    """Engine calls work (TRIAL, LICENSED, DEVELOPMENT)."""
+    needs_online: bool
+    """The state changes only after an online check (NOT_STARTED, NEEDS_ONLINE)."""
+    has_license_key: bool
+    """A license key is stored on this device, so a host offers Deactivate rather than Activate."""
+    message: str
+    """The status line: "Trial: 7 days left", "Trial ended — Buy license", "Licensed", ..."""
+
+
+def status() -> LicenseStatus:
+    """The license state of this device and user. It never contacts the licensing service."""
+    result = native.LicenseStatus()
+    errors.check(library.load().deformable_license_status(ctypes.byref(result)))
+    return _converted(result)
+
+
+def refresh(timeout: float = DEFAULT_TIMEOUT) -> LicenseStatus:
+    """Brings the license up to date with the licensing service when a contact is due, waiting at most `timeout`
+    seconds: starts the trial on a device that never started it, reports a running trial once a day, and renews a
+    stored license. Otherwise nothing is sent. Raises LicenseError when the service cannot be reached or refuses."""
+    result = native.LicenseStatus()
+    errors.check(library.load().deformable_license_refresh(timeout_milliseconds(timeout), ctypes.byref(result)))
+    return _converted(result)
+
+
+def activate(license_key: str, timeout: float = DEFAULT_TIMEOUT) -> LicenseStatus:
+    """Activates a license key on this device, waiting at most `timeout` seconds; the state is then LICENSED. Raises
+    ValueError for an empty key, DeformableError (INVALID_ARGUMENT) for text that is no license key or while another
+    key is active here, and LicenseError when the service refuses the key or cannot be reached, with a message written
+    for the user."""
+    if not isinstance(license_key, str) or not license_key.strip():
+        raise ValueError("the license key must be a non-empty string")
+    if "\0" in license_key:
+        raise ValueError("the license key must not contain a NUL character")
+    result = native.LicenseStatus()
+    code = library.load().deformable_license_activate(
+        ctypes.create_string_buffer(license_key.encode("utf-8")), timeout_milliseconds(timeout), ctypes.byref(result)
+    )
+    errors.check(code)
+    return _converted(result)
+
+
+def deactivate(timeout: float = DEFAULT_TIMEOUT) -> LicenseStatus:
+    """Frees this device's seat with the licensing service and forgets the key, waiting at most `timeout` seconds.
+    Without a stored key it does nothing. When the service cannot be reached nothing changes and LicenseError is
+    raised."""
+    result = native.LicenseStatus()
+    errors.check(library.load().deformable_license_deactivate(timeout_milliseconds(timeout), ctypes.byref(result)))
+    return _converted(result)
+
+
+def set_online_access(allowed: bool) -> None:
+    """Allows (the default) or forbids every contact with the licensing service from this process, for a host whose
+    user turned online access off. Forbidden, nothing is sent: refresh(), activate() and deactivate() raise LicenseError
+    and change nothing, and engine calls neither start the trial nor renew the license on their own, so a state that
+    needs the service stays as it is. It grants nothing."""
+    errors.check(library.load().deformable_license_set_online_access(1 if allowed else 0))
+
+
+def timeout_milliseconds(timeout: float) -> int:
+    """A timeout in seconds as the library takes it: whole milliseconds, rounded up, at least 1. The library counts
+    anything above 60 s as 60 s."""
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        raise TypeError("the timeout must be a number of seconds")
+    if math.isnan(timeout) or timeout <= 0:
+        raise ValueError("the timeout must be a positive number of seconds")
+    if math.isinf(timeout):
+        return _LARGEST_TIMEOUT_MILLISECONDS
+    return min(max(1, math.ceil(timeout * 1000)), _LARGEST_TIMEOUT_MILLISECONDS)
+
+
+def _converted(result: native.LicenseStatus) -> LicenseStatus:
+    try:
+        state = LicenseState(result.state)
+    except ValueError:
+        # A newer library may report a state this package does not know yet; it is still reported, as a plain int.
+        state = result.state
+    return LicenseStatus(
+        state=state,
+        days_left=result.days_left,
+        tetrahedron_limit=result.tetrahedron_limit or None,
+        usable=bool(result.usable),
+        needs_online=bool(result.needs_online),
+        has_license_key=bool(result.has_license_key),
+        message=result.message.decode("utf-8", errors="replace"),
+    )

deformable/material_regions.py

@@ -0,0 +1,48 @@
+"""Material Regions: which region, if any, holds each tetrahedron of a mesh."""
+
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+from collections.abc import Sequence
+from typing import Any
+
+from . import conversion, library, native
+from .errors import check
+from .handles import temporary_handle
+from .meshes import polygon_mesh_view, tetrahedral_mesh_view
+from .values import IDENTITY, AffineTransform
+
+
+@dataclasses.dataclass
+class MaterialRegion:
+    """A polygon mesh in its own object space and its map into the tetrahedral mesh's object space (the region's
+    world matrix times the inverse of the object's)."""
+
+    mesh: Any
+    """The region's mesh, normally a closed convex polyhedron with outward faces such as a unit cube."""
+    to_mesh_space: AffineTransform = IDENTITY
+    """Maps the region's points into the tetrahedral mesh's object space."""
+
+    def _native(self) -> native.MaterialRegion:
+        return native.MaterialRegion(polygon_mesh_view(self.mesh), conversion.affine_transform(self.to_mesh_space))
+
+
+def material_region_indices(mesh: Any, regions: Sequence[MaterialRegion]) -> list[int]:
+    """Per tetrahedron of mesh: 0, or k + 1 for the first region k, in ascending signed volume of its untransformed
+    mesh, whose transformed face planes all hold n·c + d <= 0 at the tetrahedron's centroid c.
+
+    The host turns the result into materials: 0 is the object's material, k + 1 region k's.
+    """
+    functions = library.load()
+    region_array = conversion.structure_array(regions, native.MaterialRegion, MaterialRegion._native)
+    with temporary_handle("deformable_material_region_indices_destroy") as handle:
+        check(
+            functions.deformable_material_region_indices(
+                ctypes.byref(tetrahedral_mesh_view(mesh)), region_array, len(region_array), ctypes.byref(handle)
+            )
+        )
+        values = ctypes.POINTER(native.Index)()
+        count = native.Count()
+        check(functions.deformable_material_region_indices_values(handle, ctypes.byref(values), ctypes.byref(count)))
+        return conversion.read_scalars(values, ctypes.c_uint32, count.value)

deformable/mesh_verification.py

@@ -0,0 +1,187 @@
+"""The mesh checks: verify_surface on a render surface and meshes_intersect on two tetrahedral meshes."""
+
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+from collections.abc import Sequence
+from typing import Any
+
+from . import conversion, library, native
+from .errors import check
+from .handles import temporary_handle
+from .meshes import FaceHole, SurfaceMesh, face_hole_array, surface_mesh_view, tetrahedral_mesh_view
+from .values import MeshIssueKind, SelfIntersectionCheck
+
+
+@dataclasses.dataclass(frozen=True)
+class MeshChecks:
+    """The checks verify_surface runs."""
+
+    angle_threshold_degrees: float
+    """A face whose smallest corner angle is below this many degrees is a SMALL FACE ANGLE."""
+    gap_threshold: float
+    """Two corners of a face closer than this fraction of the mesh radius are NEAR VERTICES."""
+    planar_threshold: float
+    """A face deviating from its plane by more than this fraction of its radius is NON-PLANAR."""
+    uv_threshold: float | None
+    """INCONSISTENT UV when a corner lies farther than this fraction of the face radius from where the UV map puts
+    it; None skips the check."""
+    same_uv: bool
+    """SAME UV: two corners of a face at different places with identical UVs."""
+    convex: bool
+    """Reflex corners (NON-CONVEX)."""
+    watertight: bool
+    """NOT WATERTIGHT, and the inward-normal and nesting stage."""
+    self_intersection: SelfIntersectionCheck | int
+    """How far the self-intersection stage goes."""
+
+    @classmethod
+    def default(cls, **changes: Any) -> MeshChecks:
+        """The verify_surface defaults (angle 2°, gap 0.001, planar 0.05, no UV consistency, SAME UV, convexity or
+        watertightness check, self-intersection per island), with the given fields changed."""
+        structure = native.MeshChecks()
+        check(library.load().deformable_mesh_checks_default(ctypes.byref(structure)))
+        defaults = cls(
+            structure.angle_threshold_degrees,
+            structure.gap_threshold,
+            structure.planar_threshold,
+            structure.uv_threshold if structure.check_uv_consistency else None,
+            bool(structure.same_uv),
+            bool(structure.convex),
+            bool(structure.watertight),
+            SelfIntersectionCheck(structure.self_intersection),
+        )
+        return dataclasses.replace(defaults, **changes)
+
+    def _native(self) -> native.MeshChecks:
+        return native.MeshChecks(
+            self.angle_threshold_degrees,
+            self.gap_threshold,
+            self.planar_threshold,
+            self.uv_threshold is not None,
+            0.0 if self.uv_threshold is None else self.uv_threshold,
+            bool(self.same_uv),
+            bool(self.convex),
+            bool(self.watertight),
+            int(self.self_intersection),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class MeshIssue:
+    """One finding of verify_surface. kind says which fields it fills (deformable.h lists them); the others are 0 or
+    empty. Vertices are input vertex indices, an edge is a pair of vertex indices (smaller first), corners count
+    within their polygon, holes within their face, and islands are numbered by their lowest face."""
+
+    kind: MeshIssueKind
+    """What the issue is."""
+    vertex: int
+    """The vertex."""
+    face: int
+    """The face."""
+    hole: int
+    """The hole within the face."""
+    corner: int
+    """The corner within the face."""
+    uv_set: int
+    """The UV set, 0 or 1."""
+    island: int
+    """The island."""
+    container: int
+    """The innermost container island."""
+    use_count: int
+    """The face count of a non-manifold edge, or the loop-edge count for an edge of distinct positions."""
+    hole_count: int
+    """The hole count of the face."""
+    island_count: int
+    """The island count of the mesh."""
+    edge: tuple[int, int]
+    """The edge's two vertices."""
+    corners: tuple[int, int]
+    """The two corners within the face."""
+    inward: bool
+    """True when both nested islands have inward face normals."""
+    distance: float
+    """The distance between the two corners."""
+    relative_distance: float
+    """A distance over the mesh or face radius."""
+    degrees: float
+    """The smallest corner angle in degrees."""
+    relative_deviation: float
+    """The largest distance to the plane over the face radius."""
+    interior_angle_degrees: float
+    """The interior angle of the most reflex corner in degrees."""
+    vertices: list[int]
+    """The co-located vertices, ascending."""
+    edges: list[tuple[int, int]]
+    """The co-located edges, in order of first use."""
+    uncontained: list[int]
+    """The uncontained inward islands, ascending."""
+
+    @classmethod
+    def _from_native(cls, record: native.MeshIssue) -> MeshIssue:
+        return cls(
+            MeshIssueKind(record.kind),
+            record.vertex,
+            record.face,
+            record.hole,
+            record.corner,
+            record.uv_set,
+            record.island,
+            record.container,
+            record.use_count,
+            record.hole_count,
+            record.island_count,
+            tuple(record.edge),
+            tuple(record.corners),
+            bool(record.inward),
+            record.distance,
+            record.relative_distance,
+            record.degrees,
+            record.relative_deviation,
+            record.interior_angle_degrees,
+            conversion.read_scalars(record.vertices, ctypes.c_uint32, record.vertex_count),
+            conversion.read_groups(record.edges, ctypes.c_uint32, record.edge_count, 2),
+            conversion.read_scalars(record.uncontained, ctypes.c_uint32, record.uncontained_count),
+        )
+
+
+def verify_surface(
+    surface: SurfaceMesh, holes: Sequence[FaceHole] = (), checks: MeshChecks | None = None
+) -> list[MeshIssue]:
+    """The issues checks finds on a surface, in check order (none = passes), from positions, holes and
+    the first two UV sets. checks defaults to MeshChecks.default()."""
+    checks = MeshChecks.default() if checks is None else checks
+    functions = library.load()
+    hole_array = face_hole_array(holes)
+    with temporary_handle("deformable_mesh_issue_list_destroy") as handle:
+        check(
+            functions.deformable_verify_surface(
+                ctypes.byref(surface_mesh_view(surface)),
+                hole_array,
+                len(hole_array),
+                ctypes.byref(checks._native()),
+                ctypes.byref(handle),
+            )
+        )
+        records = ctypes.POINTER(native.MeshIssue)()
+        count = native.Count()
+        check(functions.deformable_mesh_issue_list_issues(handle, ctypes.byref(records), ctypes.byref(count)))
+        return [
+            MeshIssue._from_native(record) for record in conversion.lent_array(records, native.MeshIssue, count.value)
+        ]
+
+
+def meshes_intersect(first: Any, second: Any) -> bool:
+    """True when a tetrahedron pair, one from each mesh in world space, has overlapping closed boxes and
+    a clipped overlap volume above 1e-10 with a nonzero normal."""
+    intersect = native.Boolean()
+    check(
+        library.load().deformable_meshes_intersect(
+            ctypes.byref(tetrahedral_mesh_view(first)),
+            ctypes.byref(tetrahedral_mesh_view(second)),
+            ctypes.byref(intersect),
+        )
+    )
+    return bool(intersect.value)

deformable/meshes.py

@@ -0,0 +1,179 @@
+"""Mesh types, their borrowed C views, and the queries on a tetrahedral mesh.
+
+The mesh classes hold whatever array form they were given (see deformable.conversion); meshes the library returns hold
+lists of Vector3 and of index tuples. Any object with the same attributes can stand in for a mesh class.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+from collections.abc import Sequence
+from typing import Any, NamedTuple
+
+from . import conversion, library, native
+from .errors import check
+from .handles import temporary_handle
+
+
+@dataclasses.dataclass
+class TetrahedralMesh:
+    """Node positions and four node indices per tetrahedron, positively oriented (left-handed)."""
+
+    positions: Any
+    """The node positions."""
+    tetrahedrons: Any
+    """Four node indices per tetrahedron."""
+
+
+@dataclasses.dataclass
+class TriangleSurface:
+    """Vertex positions and three vertex indices per triangle."""
+
+    positions: Any
+    """The vertex positions."""
+    triangles: Any
+    """Three vertex indices per triangle."""
+
+
+@dataclasses.dataclass
+class PolygonMesh:
+    """Shared positions, the corner count of each polygon, and the vertex of every corner, polygon after polygon."""
+
+    positions: Any
+    """The vertex positions."""
+    polygon_sizes: Any
+    """The corner count of each polygon."""
+    polygon_vertices: Any
+    """The vertex index of each corner."""
+
+
+@dataclasses.dataclass
+class SurfaceMesh:
+    """A render surface: a polygon mesh with per-corner channels, each empty or with one entry per corner."""
+
+    mesh: PolygonMesh
+    """Positions and polygons."""
+    normals: Any = ()
+    """One normal per corner, or none."""
+    uv_sets: Sequence[Any] = ()
+    """UV sets, each with one coordinate pair per corner."""
+    colours: Any = ()
+    """One red, green, blue and alpha colour per corner, or none."""
+
+
+class FaceHole(NamedTuple):
+    """A run of a face's corners that forms one hole loop; the corners before the face's first hole form its outer
+    loop."""
+
+    face: int
+    """The polygon holding the hole."""
+    first_corner: int
+    """Index of the run's first corner within the polygon."""
+    corner_count: int
+    """Number of corners in the run."""
+
+
+def tetrahedral_mesh_view(mesh: Any) -> native.TetrahedralMeshView:
+    """The borrowed C view of a tetrahedral mesh."""
+    positions = conversion.vector3_array(mesh.positions)
+    tetrahedrons = conversion.index_group_array(mesh.tetrahedrons, 4, "tetrahedrons")
+    return native.TetrahedralMeshView(positions, len(positions), tetrahedrons, len(tetrahedrons))
+
+
+def triangle_surface_view(surface: Any) -> native.TriangleSurfaceView:
+    """The borrowed C view of a triangle surface."""
+    positions = conversion.vector3_array(surface.positions)
+    triangles = conversion.index_group_array(surface.triangles, 3, "triangles")
+    return native.TriangleSurfaceView(positions, len(positions), triangles, len(triangles))
+
+
+def polygon_mesh_view(mesh: Any) -> native.PolygonMeshView:
+    """The borrowed C view of a polygon mesh."""
+    positions = conversion.vector3_array(mesh.positions)
+    sizes = conversion.index_array(mesh.polygon_sizes, "polygon_sizes")
+    vertices = conversion.index_array(mesh.polygon_vertices, "polygon_vertices")
+    return native.PolygonMeshView(positions, len(positions), sizes, len(sizes), vertices, len(vertices))
+
+
+def surface_mesh_view(surface: Any) -> native.SurfaceMeshView:
+    """The borrowed C view of a render surface; every UV set must have one pair per corner."""
+    mesh = polygon_mesh_view(surface.mesh)
+    normals = conversion.vector3_array(surface.normals, "normals")
+    uv_sets = [conversion.vector2_array(uv_set, "uv_sets") for uv_set in surface.uv_sets]
+    for uv_set in uv_sets:
+        # The library reads uv_set_count × corner_count pairs, so a short set would be read past its end.
+        if len(uv_set) != mesh.corner_count:
+            raise ValueError(f"a UV set holds {len(uv_set)} pairs for {mesh.corner_count} corners")
+    uv_type = native.Vector2 * (mesh.corner_count * len(uv_sets))
+    uvs = uv_type.from_buffer_copy(b"".join(bytes(uv_set) for uv_set in uv_sets))
+    colours = conversion.grouped_array(surface.colours, native.Colour, ctypes.c_double, 4, "colours")
+    return native.SurfaceMeshView(mesh, normals, len(normals), uvs, len(uv_sets), colours, len(colours))
+
+
+def face_hole_array(holes: Sequence[Any]):
+    """The C array of face holes, each a FaceHole or a (face, first_corner, corner_count) triple."""
+    return conversion.structure_array(
+        holes,
+        native.FaceHole,
+        lambda hole: native.FaceHole(*(conversion.unsigned(value) for value in hole)),
+    )
+
+
+def read_tetrahedral_mesh(view: native.TetrahedralMeshView) -> TetrahedralMesh:
+    """A copy of a lent tetrahedral mesh."""
+    return TetrahedralMesh(
+        conversion.read_vector3_list(view.positions, view.position_count),
+        conversion.read_groups(view.tetrahedrons, ctypes.c_uint32, view.tetrahedron_count, 4),
+    )
+
+
+def read_triangle_surface(view: native.TriangleSurfaceView) -> TriangleSurface:
+    """A copy of a lent triangle surface."""
+    return TriangleSurface(
+        conversion.read_vector3_list(view.positions, view.position_count),
+        conversion.read_groups(view.triangles, ctypes.c_uint32, view.triangle_count, 3),
+    )
+
+
+def read_polygon_mesh(view: native.PolygonMeshView) -> PolygonMesh:
+    """A copy of a lent polygon mesh."""
+    return PolygonMesh(
+        conversion.read_vector3_list(view.positions, view.position_count),
+        conversion.read_scalars(view.polygon_sizes, ctypes.c_uint32, view.polygon_count),
+        conversion.read_scalars(view.polygon_vertices, ctypes.c_uint32, view.corner_count),
+    )
+
+
+def read_surface_mesh(view: native.SurfaceMeshView) -> SurfaceMesh:
+    """A copy of a lent render surface."""
+    corner_count = view.mesh.corner_count
+    uvs = conversion.read_vector2_list(view.uvs, view.uv_set_count * corner_count)
+    return SurfaceMesh(
+        read_polygon_mesh(view.mesh),
+        conversion.read_vector3_list(view.normals, view.normal_count),
+        [uvs[start : start + corner_count] for start in range(0, len(uvs), corner_count)],
+        conversion.read_groups(view.colours, ctypes.c_double, view.colour_count, 4),
+    )
+
+
+def face_corners(face: int) -> tuple[int, int, int]:
+    """The three local corners (0-3) of tetrahedron face face (0-3, the face opposite corner face).
+
+    Seen from outside a positively oriented (left-handed) tetrahedron they run clockwise, so (b - a) × (c - a) points
+    inward.
+    """
+    corners = native.TriangleIndices()
+    check(library.load().deformable_face_corners(conversion.unsigned(face), ctypes.byref(corners)))
+    return tuple(corners)
+
+
+def boundary_faces(mesh: Any) -> list[int]:
+    """The static outer-face mask of each tetrahedron: bit k is set when face k, opposite node k, has no neighbour."""
+    functions = library.load()
+    with temporary_handle("deformable_boundary_faces_destroy") as handle:
+        check(functions.deformable_boundary_faces(ctypes.byref(tetrahedral_mesh_view(mesh)), ctypes.byref(handle)))
+        masks = ctypes.POINTER(ctypes.c_uint8)()
+        count = native.Count()
+        check(functions.deformable_boundary_faces_masks(handle, ctypes.byref(masks), ctypes.byref(count)))
+        return conversion.read_scalars(masks, ctypes.c_uint8, count.value)