deformable 0.1.0__py3-none-win_amd64.whl

deformable/__init__.py

@@ -0,0 +1,191 @@
+"""deformable: finite element deformation and fracture of tetrahedral meshes, from Python.
+
+A pure-Python package over libdeformable, the shared library of the C SDK (declared in deformable.h), loaded with
+ctypes. It needs no third-party package: only the shared library, which the platform wheel carries in the package
+directory. The library is looked up through the DEFORMABLE_LIBRARY environment variable, then in the package
+directory, then in the target/release folder of the Cargo workspace the package sits in (deformable.library).
+
+It runs on Python 3.9 and later, so it also runs inside Blender, whose bundled Python is 3.10 or later since
+Blender 3.1: put the package and the shared library on Blender's module path, or set DEFORMABLE_LIBRARY.
+
+The host flow::
+
+    import deformable
+
+    cage = deformable.TriangleSurface(positions, triangles)
+    mesh = deformable.tetrahedralize(cage, deformable.TetrahedralizeParameters(maximum_edge_length=0.5)).mesh
+    with deformable.Simulation() as simulation:
+        material = simulation.add_material(deformable.MaterialParameters.default())
+        cube = simulation.add_object(mesh, material)
+        for frame in range(25):
+            simulation.step(frame / 24, substeps=10)
+        positions = simulation.node_positions(cube)
+
+Conventions:
+
+- Errors. A failed call raises DeformableError with the library's status, message and element indices. Arguments the
+  package refuses before calling the library raise ValueError or TypeError; a closed handle raises ValueError.
+- Arrays. Vertex and index data may be lists or tuples of groups, flat sequences of numbers, array.array, memoryview
+  or any other buffer (deformable.conversion). Results are lists of Vector3 and of index tuples, except the skinned
+  output of SurfaceEmbedding.deform (DeformedSurface), which is flat array.array copies: 32-bit floats for positions
+  and normals, bytes for the hidden faces.
+- Handles. Simulation, SurfaceEmbedding and CancelFlag own a library handle, freed by close(), at the end of a with
+  block, or when the object is collected; close() waits for calls in flight on the object from other threads, and
+  later calls raise ValueError. Object and material handles are ints counting up from 0.
+- Units. Lengths cross in host units; time, forces, gravity, masses and material values in simulation units. The
+  simulation's scale converts host lengths to simulation lengths.
+- License. The library checks the license of this device and user before engine work; deformable.license reads it
+  and activates a license key. A call the trial or license does not allow raises LicenseError, a DeformableError
+  whose message is written for the user: LicenseRequiredError ("Trial ended — Buy license") and
+  TrialLimitExceededError ("Trial limit: 2500 tetrahedrons") are its two most common kinds.
+- Threads. Library calls release the global interpreter lock. Calls on one simulation from several threads run one
+  at a time; tools, embeddings and cancel flags may be used from several threads at once.
+"""
+
+from __future__ import annotations
+
+from . import library, license
+from .cancel_flag import CancelFlag
+from .embedding import (
+    DeformedSurface,
+    PreparationParameters,
+    SkinningOptions,
+    SurfaceEmbedding,
+    SurfaceEmbeddingArrays,
+    embed_surface,
+)
+from .errors import DeformableError, LicenseError, LicenseRequiredError, Status, TrialLimitExceededError
+from .library import LibraryNotFoundError
+from .license import LicenseState, LicenseStatus
+from .material_regions import MaterialRegion, material_region_indices
+from .mesh_verification import MeshChecks, MeshIssue, meshes_intersect, verify_surface
+from .meshes import (
+    FaceHole,
+    PolygonMesh,
+    SurfaceMesh,
+    TetrahedralMesh,
+    TriangleSurface,
+    boundary_faces,
+    face_corners,
+)
+from .simulation import (
+    ConvexRegion,
+    DrivenVertex,
+    FaceEvent,
+    GlueParameters,
+    MaterialParameters,
+    MaterialPreset,
+    ObjectOptions,
+    Plane,
+    Simulation,
+    SimulationStatistics,
+    StepReport,
+    TetrahedronState,
+)
+from .tools import (
+    Anisotropy,
+    AutocageParameters,
+    DensityRegion,
+    PixelGrid,
+    SplinterImageParameters,
+    Tetrahedralization,
+    TetrahedralizeParameters,
+    TriangulateParameters,
+    Triangulation,
+    autocage,
+    extrude,
+    span_layers,
+    splinters_from_image,
+    tetrahedralize,
+    triangulate,
+)
+from .values import (
+    IDENTITY,
+    NODE_REPLACED,
+    AffineTransform,
+    ClipMode,
+    ExtrudeDirection,
+    MeshIssueKind,
+    SelfIntersectionCheck,
+    StepOutcome,
+    Vector2,
+    Vector3,
+)
+
+__version__ = "0.1.0"
+
+
+def library_version() -> str:
+    """The version of the loaded shared library, major.minor.patch."""
+    return library.load().deformable_version().decode("ascii")
+
+
+__all__ = [
+    "IDENTITY",
+    "NODE_REPLACED",
+    "AffineTransform",
+    "Anisotropy",
+    "AutocageParameters",
+    "CancelFlag",
+    "ClipMode",
+    "ConvexRegion",
+    "DeformableError",
+    "DeformedSurface",
+    "DensityRegion",
+    "DrivenVertex",
+    "ExtrudeDirection",
+    "FaceEvent",
+    "FaceHole",
+    "GlueParameters",
+    "LibraryNotFoundError",
+    "LicenseError",
+    "LicenseRequiredError",
+    "LicenseState",
+    "LicenseStatus",
+    "MaterialParameters",
+    "MaterialPreset",
+    "MaterialRegion",
+    "MeshChecks",
+    "MeshIssue",
+    "MeshIssueKind",
+    "ObjectOptions",
+    "PixelGrid",
+    "Plane",
+    "PolygonMesh",
+    "PreparationParameters",
+    "SelfIntersectionCheck",
+    "Simulation",
+    "SimulationStatistics",
+    "SkinningOptions",
+    "SplinterImageParameters",
+    "Status",
+    "StepOutcome",
+    "StepReport",
+    "SurfaceEmbedding",
+    "SurfaceEmbeddingArrays",
+    "SurfaceMesh",
+    "Tetrahedralization",
+    "TetrahedralizeParameters",
+    "TetrahedralMesh",
+    "TetrahedronState",
+    "TrialLimitExceededError",
+    "TriangleSurface",
+    "TriangulateParameters",
+    "Triangulation",
+    "Vector2",
+    "Vector3",
+    "autocage",
+    "boundary_faces",
+    "embed_surface",
+    "extrude",
+    "face_corners",
+    "library_version",
+    "license",
+    "material_region_indices",
+    "meshes_intersect",
+    "span_layers",
+    "splinters_from_image",
+    "tetrahedralize",
+    "triangulate",
+    "verify_surface",
+]

deformable/cancel_flag.py

@@ -0,0 +1,43 @@
+"""The flag another thread sets to stop a step or a tool."""
+
+from __future__ import annotations
+
+import contextlib
+import ctypes
+
+from . import native
+from .handles import OwnedHandle
+
+
+class CancelFlag(OwnedHandle):
+    """A thread-safe cancel flag, not set when created.
+
+    Library calls release the global interpreter lock, so one Python thread can set the flag while another runs
+    Simulation.step or a tool that was given it; that call stops at its next check.
+    """
+
+    _destroy_name = "deformable_cancel_flag_destroy"
+    _description = "cancel flag"
+
+    def __init__(self) -> None:
+        super().__init__("deformable_cancel_flag_create")
+
+    def set(self) -> None:
+        """Sets the flag."""
+        self._call("deformable_cancel_flag_set", 1)
+
+    def clear(self) -> None:
+        """Clears the flag."""
+        self._call("deformable_cancel_flag_set", 0)
+
+    def is_set(self) -> bool:
+        """True while the flag is set."""
+        cancelled = native.Boolean()
+        self._call("deformable_cancel_flag_is_set", ctypes.byref(cancelled))
+        return bool(cancelled.value)
+
+
+def cancel_handle(cancel: CancelFlag | None) -> contextlib.AbstractContextManager[int | None]:
+    """The handle a call takes for an optional cancel flag, NULL when there is none; the flag stays open until the
+    block ends."""
+    return contextlib.nullcontext() if cancel is None else cancel._use()

deformable/conversion.py

@@ -0,0 +1,176 @@
+"""Python values to the ctypes arrays the library borrows, and the arrays it lends back to Python values.
+
+Array inputs take any of these forms:
+
+- a sequence of groups, such as a list of (x, y, z) tuples or of Vector3;
+- a flat sequence of numbers, group after group;
+- any buffer: array.array, memoryview, bytes, or another object with the buffer protocol, flat or with one row per
+  group. A contiguous buffer that already holds the C element type is copied as it is; any other is read number by
+  number, so array.array("f") vertex data from Blender's foreach_get works as well.
+"""
+
+from __future__ import annotations
+
+import array
+import ctypes
+import numbers
+import sys
+from collections.abc import Iterable, Sequence
+from typing import Any, Callable
+
+from . import native
+from .values import AffineTransform, Vector2, Vector3
+
+UNSIGNED_32_LIMIT = 1 << 32
+
+# The buffer formats whose items have the C type's size and byte order, so the bytes can be copied as they are.
+_byte_order_prefix = "<" if sys.byteorder == "little" else ">"
+_NATIVE_FORMATS = {
+    ctypes.c_double: {"d", "@d", "=d", _byte_order_prefix + "d"},
+    ctypes.c_uint32: {"I", "@I", "=I", _byte_order_prefix + "I"},
+    ctypes.c_uint8: {"B", "@B", "=B", "<B", ">B", "c"},
+}
+
+
+def unsigned(value: int, limit: int = UNSIGNED_32_LIMIT) -> int:
+    """value as an index or count, refused when ctypes would wrap it into another number."""
+    value = int(value)
+    if not 0 <= value < limit:
+        raise ValueError(f"{value} is outside the unsigned range [0, {limit})")
+    return value
+
+
+def size(value: int) -> int:
+    """value as a size_t count."""
+    return unsigned(value, 1 << (8 * ctypes.sizeof(ctypes.c_size_t)))
+
+
+def _flatten(values: Iterable[Any]) -> list:
+    flat = []
+    for value in values:
+        if isinstance(value, numbers.Number):
+            flat.append(value)
+        elif isinstance(value, str):
+            # A one-character string iterates to itself, so it would recurse forever.
+            raise TypeError(f"expected a number or a group of numbers, not the string {value!r}")
+        else:
+            flat.extend(_flatten(value))
+    return flat
+
+
+def _buffer(values: Any) -> memoryview | None:
+    if isinstance(values, (list, tuple)):
+        return None
+    try:
+        return memoryview(values)
+    except TypeError:
+        return None
+
+
+def scalar_array(values: Any, element_type, group: int = 1, name: str = "values"):
+    """A ctypes array of element_type holding values, whose length must be a multiple of group."""
+    view = _buffer(values)
+    if view is not None and view.c_contiguous and view.format in _NATIVE_FORMATS.get(element_type, ()):
+        data = view.tobytes()
+        array = (element_type * (len(data) // ctypes.sizeof(element_type))).from_buffer_copy(data)
+    else:
+        flat = _flatten(view.tolist() if view is not None else values)
+        if element_type in (ctypes.c_uint32, ctypes.c_uint8):
+            limit = 1 << (8 * ctypes.sizeof(element_type))
+            for value in flat:
+                unsigned(value, limit)
+        array = (element_type * len(flat))(*flat)
+    if len(array) % group:
+        raise ValueError(f"{name} holds {len(array)} numbers, not a whole number of groups of {group}")
+    return array
+
+
+def grouped_array(values: Any, group_type, element_type, group: int, name: str):
+    """A ctypes array of group_type (a structure or array of group element_type values) over values."""
+    flat = scalar_array(values, element_type, group, name)
+    return (group_type * (len(flat) // group)).from_buffer(flat)
+
+
+def vector3_array(values: Any, name: str = "positions"):
+    """DeformableVector3 values."""
+    return grouped_array(values, native.Vector3, ctypes.c_double, 3, name)
+
+
+def vector2_array(values: Any, name: str = "uvs"):
+    """DeformableVector2 values."""
+    return grouped_array(values, native.Vector2, ctypes.c_double, 2, name)
+
+
+def index_array(values: Any, name: str = "indices"):
+    """uint32_t values."""
+    return scalar_array(values, ctypes.c_uint32, 1, name)
+
+
+def index_group_array(values: Any, group: int, name: str):
+    """uint32_t[group] values, such as tetrahedrons (4) or triangles (3)."""
+    return grouped_array(values, native.Index * group, ctypes.c_uint32, group, name)
+
+
+def vector3(value: Sequence[float]) -> native.Vector3:
+    """One DeformableVector3."""
+    x, y, z = value
+    return native.Vector3(x, y, z)
+
+
+def affine_transform(transform: AffineTransform) -> native.AffineTransform:
+    """One DeformableAffineTransform."""
+    linear, translation = transform
+    return native.AffineTransform(
+        native.Matrix3((native.Vector3 * 3)(*(vector3(row) for row in linear))), vector3(translation)
+    )
+
+
+def structure_array(values: Iterable[Any], element_type, convert: Callable[[Any], Any]):
+    """A ctypes array of element_type with convert applied to each value."""
+    values = list(values)
+    structures = (element_type * len(values))()
+    for index, value in enumerate(values):
+        structures[index] = convert(value)
+    return structures
+
+
+def lent_array(pointer, element_type, count: int):
+    """The count elements of element_type a library pointer lends, as a ctypes array over the library's memory."""
+    if count == 0:
+        return (element_type * 0)()
+    return ctypes.cast(pointer, ctypes.POINTER(element_type * count)).contents
+
+
+def read_scalars(pointer, element_type, count: int) -> list:
+    """count numbers of element_type lent by the library."""
+    return list(lent_array(pointer, element_type, count))
+
+
+def read_array(pointer, type_code: str, count: int) -> array.array:
+    """count numbers lent by the library, copied at once into an array.array of type_code, whose items must have the
+    C type's size. A host takes it as it is: Blender's foreach_set reads it without a per-item conversion."""
+    values = array.array(type_code)
+    if count:
+        values.frombytes(ctypes.string_at(pointer, count * values.itemsize))
+    return values
+
+
+def read_groups(pointer, element_type, count: int, group: int) -> list[tuple]:
+    """count groups of group numbers of element_type lent by the library, as tuples."""
+    flat = read_scalars(pointer, element_type, count * group)
+    return list(zip(*(flat[offset::group] for offset in range(group))))
+
+
+def read_vector3_list(pointer, count: int) -> list[Vector3]:
+    """count DeformableVector3 values lent by the library."""
+    return [Vector3._make(group) for group in read_groups(pointer, ctypes.c_double, count, 3)]
+
+
+def read_vector2_list(pointer, count: int) -> list[Vector2]:
+    """count DeformableVector2 values lent by the library."""
+    return [Vector2._make(group) for group in read_groups(pointer, ctypes.c_double, count, 2)]
+
+
+def from_vector3(value: native.Vector3) -> Vector3:
+    """A DeformableVector3 as a Vector3."""
+    return Vector3(value.x, value.y, value.z)

deformable/embedding.py

@@ -0,0 +1,159 @@
+"""Render surfaces: preparation against the rest mesh, the embedding it gives, and per-frame skinning."""
+
+from __future__ import annotations
+
+import array
+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 OwnedHandle, temporary_handle
+from .meshes import SurfaceMesh, polygon_mesh_view, read_surface_mesh, surface_mesh_view, tetrahedral_mesh_view
+from .simulation import TetrahedronState
+from .values import AffineTransform, ClipMode
+
+
+@dataclasses.dataclass(frozen=True)
+class PreparationParameters:
+    """The surface preparation settings."""
+
+    clip_mode: ClipMode | int
+    """The clip mode."""
+    uv_scale: float
+    """Scale of the planar UVs of inner and cap faces; the random offsets of inner faces are not
+    scaled."""
+    splinter_cage: Any = None
+    """None, or the splinter cage polygon mesh in the surface's space, already moved by the host's splinter
+    transform; with vertices and a clipping mode the surface takes the splinter path."""
+
+    def _native(self) -> native.PreparationParameters:
+        cage = None if self.splinter_cage is None else ctypes.pointer(polygon_mesh_view(self.splinter_cage))
+        return native.PreparationParameters(int(self.clip_mode), self.uv_scale, cage)
+
+
+@dataclasses.dataclass(frozen=True)
+class SkinningOptions:
+    """Per-frame skinning options."""
+
+    show_inner_faces: bool = False
+    """Show every inner face, exposed or not."""
+    start_splintered: bool = False
+    """With splinter data, show the cap faces from the start instead of once a tetrahedron of theirs is flagged."""
+
+
+@dataclasses.dataclass(frozen=True)
+class DeformedSurface:
+    """A skinned surface in the object space of the host's shape, as flat arrays a host hands to its mesh API as they
+    are (Blender's foreach_set takes them without a per-item conversion)."""
+
+    positions: array.array
+    """x, y and z of the deformed position of each output vertex, mapped by the inverse world transform, flat 32-bit
+    floats (array("f"))."""
+    normals: array.array
+    """x, y and z of the deformed normal of each corner, embed(p + n) - embed(p) mapped by the linear part of the
+    inverse world transform and made unit length, a zero vector left zero, flat 32-bit floats (array("f")); empty
+    without normals."""
+    hidden_faces: array.array
+    """1 for each face the host hides (an inner or cap face not shown yet), 0 for the others (array("b"))."""
+
+
+@dataclasses.dataclass(frozen=True)
+class SurfaceEmbeddingArrays:
+    """The arrays of a surface embedding."""
+
+    surface: SurfaceMesh
+    """The prepared surface in rest space: output vertices, polygons and per-corner channels."""
+    corner_flags: list[int]
+    """The flag word of each corner: bits 0-28 the controlling tetrahedron, bits 29-30 the tetrahedron face of an
+    inner face, bit 31 set on the corners of inner faces."""
+    source_faces: list[int]
+    """The input face each output face was cut from, -1 for inner and cap faces."""
+    vertex_tetrahedrons: list[int]
+    """The controlling tetrahedron of each output vertex."""
+    vertex_weights: list[tuple[float, float, float, float]]
+    """The barycentric weights of each output vertex in its tetrahedron."""
+    normal_weights: list[tuple[float, float, float, float]]
+    """The weights of p + n for each corner in its vertex's tetrahedron; none without normals."""
+    brick_tetrahedrons: list[int]
+    """The controlling tetrahedron of each brick of the splinter path; none without splinter data."""
+    vertex_cell_tetrahedrons: list[int]
+    """The cell tetrahedron each output vertex follows once its cell has broken loose; none without splinter data."""
+
+
+class SurfaceEmbedding(OwnedHandle):
+    """A prepared surface in rest space, made by embed_surface. Reading and skinning never change it, so several
+    threads may use one embedding at the same time."""
+
+    _destroy_name = "deformable_surface_embedding_destroy"
+    _description = "surface embedding"
+
+    def arrays(self) -> SurfaceEmbeddingArrays:
+        """A copy of the embedding's arrays."""
+        view = native.SurfaceEmbeddingView()
+        read_indices = conversion.read_scalars
+        # The view points into the embedding, so it is copied before close() may free it.
+        with self._use() as address:
+            check(library.load().deformable_surface_embedding_view(address, ctypes.byref(view)))
+            return SurfaceEmbeddingArrays(
+                read_surface_mesh(view.surface),
+                read_indices(view.corner_flags, ctypes.c_uint32, view.corner_flag_count),
+                read_indices(view.source_faces, ctypes.c_int32, view.source_face_count),
+                read_indices(view.vertex_tetrahedrons, ctypes.c_uint32, view.vertex_tetrahedron_count),
+                conversion.read_groups(view.vertex_weights, ctypes.c_double, view.vertex_weight_count, 4),
+                conversion.read_groups(view.normal_weights, ctypes.c_double, view.normal_weight_count, 4),
+                read_indices(view.brick_tetrahedrons, ctypes.c_uint32, view.brick_tetrahedron_count),
+                read_indices(view.vertex_cell_tetrahedrons, ctypes.c_uint32, view.vertex_cell_tetrahedron_count),
+            )
+
+    def deform(
+        self,
+        states: Sequence[TetrahedronState],
+        world_transform: AffineTransform,
+        options: SkinningOptions | None = None,
+    ) -> DeformedSurface:
+        """Skins the surface from the current tetrahedron states, one per rest tetrahedron, into the object space of
+        the host's shape: positions and unit normals are mapped by the inverse of world_transform, the shape's world
+        matrix (IDENTITY when the states are in object space).
+
+        Splinter vertices switch to their cell tetrahedron, and inner and cap faces are hidden per options.
+        """
+        options = SkinningOptions() if options is None else options
+        functions = library.load()
+        state_array = conversion.structure_array(states, native.TetrahedronState, TetrahedronState._native)
+        transform = conversion.affine_transform(world_transform)
+        skinning = native.SkinningOptions(bool(options.show_inner_faces), bool(options.start_splintered))
+        with temporary_handle("deformable_deformed_surface_destroy") as deformed:
+            check(functions.deformable_deformed_surface_create(ctypes.byref(deformed)))
+            self._call(
+                "deformable_surface_embedding_deform",
+                state_array,
+                len(state_array),
+                ctypes.byref(transform),
+                ctypes.byref(skinning),
+                deformed,
+            )
+            view = native.DeformedSurfaceView()
+            check(functions.deformable_deformed_surface_view(deformed, ctypes.byref(view)))
+            return DeformedSurface(
+                conversion.read_array(view.positions, "f", 3 * view.position_count),
+                conversion.read_array(view.normals, "f", 3 * view.normal_count),
+                conversion.read_array(view.hidden_faces, "b", view.face_count),
+            )
+
+
+def embed_surface(rest: Any, surface: SurfaceMesh, parameters: PreparationParameters) -> SurfaceEmbedding:
+    """Prepares a render surface against the rest tetrahedral mesh: clip mode, inner faces with random planar UVs ×
+    uv_scale, the splinter path when a splinter cage is given, then the barycentric embedding."""
+    handle = native.Handle()
+    check(
+        library.load().deformable_embed_surface(
+            ctypes.byref(tetrahedral_mesh_view(rest)),
+            ctypes.byref(surface_mesh_view(surface)),
+            ctypes.byref(parameters._native()),
+            ctypes.byref(handle),
+        )
+    )
+    return SurfaceEmbedding._adopt(handle)