sand3d 1.6.1__py3-none-any.whl

sand3d/__init__.py

@@ -0,0 +1,118 @@
+"""sand3d — the vocabulary an LLM writes 3D assets in.
+
+    import sand3d as s3d
+
+One flat surface: every verb is `s3d.<verb>`. Millimetres, unless the program
+sets another unit with `s3d.units`; `export` scales to metres. A program records
+`s3d.__version__`, `s3d.fingerprint()` and `s3d.units()` with what it built.
+"""
+import functools
+import hashlib
+import pathlib
+import sys
+
+from . import _core, _guard
+
+from .assembly import Handle, assembly, attach, empty_scene, export, group, units
+from .edit import (chamfer, copy, cut, delete, dent, fillet, hole, intersect, join, merge, pocket, scale, seat, shell,
+                   soften, split)
+from .parts import gear, knurl, thread
+from .frames import Frame, along, at, bbox, grid, local, ring, snap, transform
+from .materials import material, resolve as _resolve
+from .joints import joint, placed_again as _placed_again, placed_on as _placed_on, pose
+from .profile import Path as _Path, Placed as _Placed, arc, circle, ellipse, mirror, offset, poly, polygon, rect, slot, spline, station, stroke, superellipse, tangent_arc, text, wrap
+from .solids import body, box, cone, cylinder, dome, extrude, helix, loft, revolve, sphere, sweep, torus, tube, wedge, wire
+
+# x-release-please-start-version
+__version__ = "1.6.1"
+# x-release-please-end
+
+__all__ = [
+    # profiles
+    "rect", "circle", "ellipse", "slot", "polygon", "poly", "arc", "tangent_arc", "spline", "superellipse",
+    "station", "text", "offset", "stroke", "wrap", "mirror",
+    # solids, paths
+    "extrude", "revolve", "sweep", "loft", "body", "wire", "helix",
+    "box", "cylinder", "tube", "cone", "sphere", "wedge", "torus", "dome",
+    # edits
+    "cut", "join", "intersect", "split", "delete", "copy", "hole", "pocket", "merge", "scale",
+    "fillet", "chamfer", "soften", "shell", "dent",
+    # frames, placement
+    "Frame", "bbox", "local", "at", "transform", "grid", "ring", "along", "snap",
+    # parts
+    "gear", "knurl", "thread",
+    # materials
+    "material",
+    # articulation
+    "joint", "pose", "seat",
+    # assembly
+    "group", "assembly", "attach", "Handle", "export", "empty_scene", "units", "fingerprint",
+]
+
+
+def _verb(fn):
+    """`fn`, fixing the program's unit the moment it is called — even if it raises
+    before measuring anything: the unit is set before the first verb — and checking what
+    the program hands it (`_guard`)."""
+    name = fn.__name__
+    positional = fn.__code__.co_varnames[:fn.__code__.co_argcount]
+
+    @functools.wraps(fn)
+    def verb(*args, **kwargs):
+        _core.settled = True
+        line = sys._getframe(1).f_lineno
+        _guard.calls.append((name, line, set(positional[:len(args)]) | set(kwargs)))
+        try:
+            _guard.begin(name, args, kwargs)
+            result = fn(*args, **kwargs)
+        finally:
+            _guard.calls.pop()
+        if _core.dressed and not _guard.calls:
+            _resolve()                   # every mesh wears its nearest material, whatever the verb rebuilt
+        if name in ("at", "transform", "station"):
+            for placed in result if isinstance(result, list) else [result]:
+                if isinstance(placed, (_Placed, _Path)):
+                    _guard.watch(placed, line)
+        if name in ("at", "extrude"):
+            on = kwargs["on"] if "on" in kwargs else (args[positional.index("on")]
+                                                     if len(args) > positional.index("on") else None)
+            _placed(result, on)
+            if name == "at" and on is None:
+                _placed_again(result)
+        if name == "transform":
+            _placed_again(result)
+        return result
+    return verb
+
+
+def _placed(result, on):
+    """Remember, on what `at` or `extrude` placed on a frame read on a part, that part:
+    `pose` refuses to leave it behind."""
+    if on is None:
+        return
+    if isinstance(result, Handle):
+        result = result.root
+    if isinstance(result, list):
+        if isinstance(on, (list, tuple)) and len(on) == len(result):
+            for r, f in zip(result, on):
+                _placed(r, f)
+        return
+    _placed_on(result, on)
+
+
+for _name in __all__:
+    if _name not in ("units", "empty_scene", "fingerprint") and not isinstance(globals()[_name], type):
+        globals()[_name] = _verb(globals()[_name])
+del _name
+
+
+def fingerprint():
+    """Digest of the source.
+
+    A digest of the library's source: what a program run records beside `__version__`."""
+    root = pathlib.Path(__file__).resolve().parent
+    digest = hashlib.sha256()
+    for path in sorted(root.rglob("*.py")):
+        digest.update(path.relative_to(root).as_posix().encode() + b"\0")
+        digest.update(path.read_bytes() + b"\0")
+    return digest.hexdigest()[:16]

sand3d/_core.py

@@ -0,0 +1,319 @@
+"""What every verb shares: making a named object from a bmesh, and reading one back.
+
+Nothing here is public. No function reads `bpy.context.active_object` or the
+selection; the scene collection is the only context a verb touches.
+"""
+import math
+
+import bpy  # before bmesh, which the bpy module only provides once loaded
+import bmesh
+from mathutils import Matrix, Vector, geometry
+
+
+#: Custom property holding the name a program gave an object (Blender may suffix ob.name).
+NAME = "s3d_name"
+
+
+# ---------------------------------------------------------------- the program's unit
+
+#: Millimetres in one unit of a program, by the names `units` takes.
+UNITS = {"mm": 1.0, "cm": 10.0, "m": 1000.0}
+#: The program's unit, and its size in millimetres.
+UNIT, MM = "mm", 1.0
+#: Whether a verb has measured anything in the unit since the scene was emptied: it is fixed then.
+settled = False
+#: Whether the program has set a material since the scene was emptied (`materials`).
+dressed = False
+
+
+def mm(x):
+    """`x` millimetres in the program's unit: every tolerance is written in millimetres."""
+    global settled
+    settled = True
+    return x / MM
+
+
+def mm2(x):
+    """`x` square millimetres in the program's unit squared."""
+    global settled
+    settled = True
+    return x / (MM * MM)
+
+
+def in_mm(x):
+    """A length of the program in millimetres: where a decision rounds or compares."""
+    global settled
+    settled = True
+    return x * MM
+
+
+def triangulate(points, edges, output_type, eps):
+    """Blender's constrained Delaunay triangulation of 2D `points`, `eps` in millimetres.
+    It runs in millimetres: points on one circle (a rounded corner) are told apart by
+    float noise, and a program in another unit must meet the same noise. The output
+    points come back in the program's unit."""
+    size = in_mm(1.0)
+    out = geometry.delaunay_2d_cdt([Vector((p[0] * size, p[1] * size)) for p in points], edges, [],
+                                   output_type, eps)
+    return ([Vector((v.x / size, v.y / size)) for v in out[0]], *out[1:])
+
+
+def world(ob):
+    """`ob`'s placement in the scene, from its own and its parents' placements — no
+    depsgraph, so it is current the moment `at` has run.
+
+    Blender keeps a placement as location, Euler angles and scale, in single
+    precision: a quarter turn comes back with 7.5e-8 where 0 was meant, and a face
+    laid on another drifts off it by microns — enough for an exact boolean to see two
+    planes and leave a sliver. Entries within 1e-6 of a whole number are snapped to it —
+    a whole millimetre for the translation."""
+    m = ob.matrix_parent_inverse @ ob.matrix_basis
+    return snapped(world(ob.parent) @ m if ob.parent else Matrix(m))
+
+
+def snapped(m):
+    """`m` with its entries within 1e-6 of a whole number snapped to it — a whole
+    millimetre for the translation (`world`)."""
+    for row in range(4):
+        for col in range(4):
+            size = in_mm(1.0) if col == 3 and row < 3 else 1.0
+            v = m[row][col] * size
+            if abs(v - round(v)) < 1e-6:
+                m[row][col] = round(v) / size
+    return m
+
+
+def unknown(owner, kind, missing, known):
+    """The message for names `missing` among the `kind` ("edge", "face") names `known` of
+    `owner`, with what a program most likely meant."""
+    message = f"{owner} has no {kind} named {missing}; its {kind} names: {known}"
+    plain = {k for k in known if "." not in k}      # what the edges are, not who made them
+    first = missing[0].split(".")[-1]
+    if first in ("start", "end") and {"top", "bottom"} <= plain:
+        return message + (". extrude names its caps top and bottom; start and end are a sweep's, a loft's or a "
+                          "partial revolve's")
+    if first in ("top", "bottom") and {"start", "end"} <= plain:
+        return message + (". A sweep, a loft or a partial revolve names its caps start and end; top and bottom "
+                          "are an extrude's")
+    if first == "side" and kind == "edge" and {"top", "bottom"} <= plain and "side" not in plain:
+        return message + (". Its outline turns smoothly all round (a rounded rectangle, a circle): no corner "
+                          "makes a side edge")
+    import difflib
+    near = difflib.get_close_matches(missing[0], known, n=1, cutoff=0.6)
+    if near:
+        return message + f". Did you mean {near[0]!r}?"
+    if first in ("vertical", "horizontal", "outer", "inner", "edge", "edges", "corner", "corners", "upper", "lower"):
+        return message + (f". {kind.capitalize()}s go by the names their maker gave them, not by direction: "
+                          + ("an extrude's walls meet at side" if kind == "edge" else "an extrude's walls are side"))
+    return message
+
+
+def mm_tree(ob, matrix):
+    """A BVH of `ob`'s mesh placed by `matrix`, in millimetres: Blender's BVH pads its boxes
+    in its own units, which breaks ties — search it with points times `in_mm(1.0)`."""
+    from mathutils.bvhtree import BVHTree
+    size = in_mm(1.0)
+    bm = bmesh.new()
+    bm.from_mesh(ob.data)
+    bm.transform(matrix)
+    if size != 1.0:
+        bmesh.ops.scale(bm, vec=(size,) * 3, verts=bm.verts)
+    tree = BVHTree.FromBMesh(bm)
+    bm.free()
+    return tree
+
+
+def given_name(ob):
+    return ob.get(NAME, ob.name)
+
+
+def link(ob):
+    """Put `ob` in the scene, where the exporter and the depsgraph see it."""
+    bpy.context.scene.collection.objects.link(ob)
+    return ob
+
+
+#: Face tags that name a cap. An edge bounding such a face carries its name;
+#: an edge between two other surfaces carries the verb's own kind (`side` for an
+#: extrude, `rim` for a revolve, `seam` for a sweep or a loft).
+CAPS = ("top", "bottom", "start", "end")
+#: Prefixes of the mesh attributes that hold provenance tags: one per domain,
+#: because a mesh attribute's name is unique across domains.
+FACE_TAG, EDGE_TAG = "s3d_face:", "s3d_edge:"
+#: Internal face attribute: which smooth surface a face belongs to.
+SURFACE = "s3d~surface"
+
+
+class Builder:
+    """A solid under construction: faces carry a surface id and provenance tags.
+
+    `finish` names the edges. An edge is a real edge when its two faces belong to
+    different surfaces; it carries the cap names of the faces it bounds, or the
+    verb's `kind` when it runs between two walls. Every tag also exists qualified
+    by the object's name (`plate.top`), so a join keeps them apart.
+
+    Adding a bmesh layer invalidates Python references to its elements, so every
+    layer is made up front, and `finish` assigns by index once all exist.
+    """
+
+    TAGS = ("side",) + CAPS
+
+    def __init__(self, name):
+        self.name = name
+        self.bm = bmesh.new()
+        self.surface = self.bm.faces.layers.int.new(SURFACE)
+        self.layers = {t: self.bm.faces.layers.bool.new(FACE_TAG + t) for t in self.TAGS}
+
+    def vert(self, co):
+        return self.bm.verts.new(co)
+
+    def face(self, verts, surface, tags):
+        """A face through `verts` (outward by the right-hand rule), or None if degenerate."""
+        verts = [v for i, v in enumerate(verts) if v is not verts[i - 1]]
+        if len(verts) < 3 or len(set(verts)) < len(verts):
+            return None
+        try:
+            f = self.bm.faces.new(verts)
+        except ValueError:  # the face exists already
+            return None
+        f[self.surface] = surface
+        for tag in tags:
+            f[self.layers[tag]] = True
+        f.smooth = True
+        return f
+
+    def dissolve(self, faces):
+        """Merge each cap's triangles into as few faces as its holes allow."""
+        faces = set(f for f in faces if f is not None and f.is_valid)
+        inner = [e for e in self.bm.edges if len(e.link_faces) == 2
+                 and all(f in faces for f in e.link_faces)
+                 and e.link_faces[0][self.surface] == e.link_faces[1][self.surface]]
+        if inner:
+            bmesh.ops.dissolve_edges(self.bm, edges=inner, use_verts=False, use_face_split=False)
+
+    def finish(self, kind, rim=False):
+        """The object. `rim`: every real edge also takes `kind`, save those bounding a
+        start or end cap (a revolve's circles are rims whatever faces they bound)."""
+        bm, name = self.bm, self.name
+        bm.faces.index_update()
+        bm.edges.index_update()
+        face_tags = [{t for t, lay in self.layers.items() if f[lay]} for f in bm.faces]
+        surfaces = [f[self.surface] for f in bm.faces]
+        edge_tags = []
+        for e in bm.edges:
+            fs = [f.index for f in e.link_faces]
+            if len(fs) == 2 and surfaces[fs[0]] == surfaces[fs[1]]:
+                edge_tags.append(None)
+                continue
+            tags = {t for i in fs for t in face_tags[i] if t in CAPS}
+            if not tags or (rim and not tags & {"start", "end"}):
+                tags.add(kind)
+            edge_tags.append(tags)
+        for t in self.TAGS:  # by name each time: removing a layer invalidates the other handles
+            bm.faces.layers.bool.remove(bm.faces.layers.bool[FACE_TAG + t])
+        bm.faces.layers.int.remove(bm.faces.layers.int[SURFACE])
+        write_tags(bm, name, face_tags, edge_tags)
+        bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
+        mesh = bpy.data.meshes.new(name)
+        bm.to_mesh(mesh)
+        bm.free()
+        ob = link(bpy.data.objects.new(name, mesh))
+        ob[NAME] = name
+        return ob
+
+
+def write_tags(bm, name, face_tags, edge_tags):
+    """Write provenance onto `bm` by element index: tag sets per face and per edge
+    (None for an edge that is no real edge), each tag plain and qualified by `name`.
+    Real edges are marked sharp, faces smooth."""
+    def qualified(tags):
+        return set(tags) | {f"{name}.{t}" for t in tags if "." not in t} if name else set(tags)
+    face_tags = [qualified(t) for t in face_tags]
+    edge_tags = [None if t is None else qualified(t) for t in edge_tags]
+    for t in sorted({t for tags in face_tags for t in tags}):
+        if bm.faces.layers.bool.get(FACE_TAG + t) is None:
+            bm.faces.layers.bool.new(FACE_TAG + t)
+    for t in sorted({t for tags in edge_tags if tags for t in tags}):
+        if bm.edges.layers.bool.get(EDGE_TAG + t) is None:
+            bm.edges.layers.bool.new(EDGE_TAG + t)
+    flayers = {lay.name[len(FACE_TAG):]: lay for lay in bm.faces.layers.bool.values()
+               if lay.name.startswith(FACE_TAG)}
+    elayers = {lay.name[len(EDGE_TAG):]: lay for lay in bm.edges.layers.bool.values()
+               if lay.name.startswith(EDGE_TAG)}
+    for f, tags in zip(bm.faces, face_tags):
+        for t in tags:
+            f[flayers[t]] = True
+        f.smooth = True
+    for e, tags in zip(bm.edges, edge_tags):
+        for t in tags or ():
+            e[elayers[t]] = True
+        e.smooth = tags is None
+
+
+def new_object(name, bm):
+    """A mesh object named `name` from `bm`, its normals pointing out. Frees `bm`."""
+    bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
+    mesh = bpy.data.meshes.new(name)
+    bm.to_mesh(mesh)
+    bm.free()
+    return link(bpy.data.objects.new(name, mesh))
+
+
+def extent(ob, axis):
+    """The size of `ob`'s own mesh along an axis (0, 1, 2), before any placement."""
+    values = [v.co[axis] for v in ob.data.vertices]
+    return max(values) - min(values)
+
+
+def bridge(bm, a, b):
+    """Faces between two rings of vertices; a ring of one vertex is a pole."""
+    n = max(len(a), len(b))
+    for k in range(n):
+        if len(a) == 1:
+            bm.faces.new((a[0], b[(k + 1) % n], b[k]))
+        elif len(b) == 1:
+            bm.faces.new((a[k], a[(k + 1) % n], b[0]))
+        else:
+            bm.faces.new((a[k], a[(k + 1) % n], b[(k + 1) % n], b[k]))
+
+
+#: Chord tolerance of every circle and arc, in millimetres, and the bounds on the
+#: number of segments a full turn gets: a circle up to 10 mm gets 24, of 30 mm 39,
+#: and anything from 84 mm the cap. A function of the radius in millimetres only, so a
+#: verb's mesh depends on nothing but its arguments and the unit.
+CHORD = 0.05
+TURN_MIN, TURN_MAX = 24, 64
+
+
+def segments(r, sweep=360.0):
+    """How many straight pieces an arc of radius `r` sweeping `sweep` degrees gets."""
+    r = abs(in_mm(r))
+    if r <= CHORD:
+        per_turn = TURN_MIN
+    else:
+        per_turn = math.ceil(math.pi / math.acos(1 - CHORD / r))
+        per_turn = min(max(per_turn, TURN_MIN), TURN_MAX)
+    return max(1, math.ceil(per_turn * abs(sweep) / 360.0 - 1e-9))
+
+
+def add_tags(bm, face_add, edge_add):
+    """Add names to elements of `bm` by index: {face index: tags}, {edge index: tags}.
+    Edges that gain a name become sharp."""
+    for t in sorted({t for tags in face_add.values() for t in tags}):
+        if bm.faces.layers.bool.get(FACE_TAG + t) is None:
+            bm.faces.layers.bool.new(FACE_TAG + t)
+    for t in sorted({t for tags in edge_add.values() for t in tags}):
+        if bm.edges.layers.bool.get(EDGE_TAG + t) is None:
+            bm.edges.layers.bool.new(EDGE_TAG + t)
+    bm.faces.ensure_lookup_table()
+    bm.edges.ensure_lookup_table()
+    for i, tags in face_add.items():
+        f = bm.faces[i]
+        for t in tags:
+            f[bm.faces.layers.bool[FACE_TAG + t]] = True
+    for i, tags in edge_add.items():
+        e = bm.edges[i]
+        for t in tags:
+            e[bm.edges.layers.bool[EDGE_TAG + t]] = True
+        e.smooth = False
+    bm.normal_update()

sand3d/_guard.py

@@ -0,0 +1,181 @@
+"""What a program does wrong with an object, said by the next verb that meets it.
+
+- An object a verb used up (the tools of `cut`, `join`, `intersect`; what `merge`
+  takes after the first), or one `delete` removed, names the verb and the program
+  line that did it.
+- The same object passed twice to a verb that takes objects says that `at` moves an
+  object, it does not copy it.
+- A profile or a path `at` placed and nothing used is the commonest silent mistake:
+  `s3d.at(p, x=100)` alone on its line. CPython frees the value at the end of the
+  statement; its `__del__` arms an error that the next verb raises.
+
+Nothing here touches geometry. `begin` runs at the entry of every public verb.
+"""
+import keyword
+import weakref
+
+import bpy
+
+from . import _core
+
+#: Objects removed while a program may still hold them: id of the Python object -> (it, message).
+_gone = {}
+#: The public verbs running: [(verb, the program line that called it, the parameters it wrote)].
+calls = []
+#: The error a freed, unused `at()` result armed.
+pending = None
+#: `at()` results not used yet.
+_watched = weakref.WeakSet()
+
+#: Why a verb uses up what it takes.
+REASONS = {"cut": "a tool is consumed by the boolean", "join": "a tool is consumed by the boolean",
+           "intersect": "a tool is consumed by the boolean", "merge": "an object merged into the first is used up",
+           "at": "at with a list of frames uses the object up and returns one copy per frame: use the list it returns"}
+#: Keywords 1.0.0 took away, by verb, and what to write instead.
+REMOVED = {
+    "at": {"mirror": "at: mirror= is gone in 1.0 — the image across a plane of the parent is "
+                     "s3d.transform(ob, mirror=\"x\"), on s3d.copy(ob) to keep the original"},
+    "mirror": {"axis": "mirror: axis= is gone in 1.0 — the letter is the coordinate that changes sign: "
+                       "s3d.mirror(p, \"x\") is the old axis=\"y\""},
+    "hole": {"at": "hole: at= is on= in 1.0 — s3d.hole(ob, d, on=frames or points); on= is the one word for where"},
+    "join": {"at": "join: at= is gone in 1.0 — place one copy per frame with at, and join the list: "
+                   "s3d.join(ob, s3d.at(tool, on=[frames]))"},
+    "cut": {"at": "cut: at= is gone in 1.0 — place one copy per frame with at, and cut the list: "
+                  "s3d.cut(ob, s3d.at(tool, on=[frames]))"},
+    "loft": {"closed": "loft: closed= is loop= in 1.0 — loop=True joins the last section back to the first, a ring "
+                       "with no ends; without it, the two ends of a loft are capped"},
+}
+#: Verbs whose objects must all be different, from which argument on.
+DISTINCT = {"cut": 0, "join": 0, "intersect": 0, "merge": 0, "group": 1, "assembly": 1, "attach": 2, "at": 0, "transform": 0}
+
+
+def reset():
+    """A new scene: nothing is used up or pending any more, and what the last program
+    placed and still holds can be freed without a word."""
+    global pending
+    for value in list(_watched):
+        value._s3d_used = True
+    _watched.clear()
+    _gone.clear()
+    pending = None
+
+
+def removed(ob):
+    """Whether `ob` is a Blender object that has been removed from the file."""
+    if not isinstance(ob, bpy.types.ID):
+        return False
+    try:
+        ob.name
+    except ReferenceError:
+        return True
+    return False
+
+
+def _code(name):
+    """A name as a program would write the object in a call: itself if it can be a variable."""
+    return name if name.isidentifier() and not keyword.iskeyword(name) else repr(name)
+
+
+def given(verb, names, inside=None):
+    """Which of `names` the program wrote in its call to `verb`, if `verb` is the public
+    verb running; for a call from inside the library, `inside` (all of them by default)."""
+    if calls and calls[-1][0] == verb:
+        return set(names) & calls[-1][2]
+    return set(names) if inside is None else set(inside)
+
+
+def using_up(obs, target):
+    """Record that the verb running uses `obs` up on `target` — before it does: whichever
+    way it goes, the program's objects are gone after it."""
+    if not calls or calls[0][0] not in REASONS:
+        return
+    verb, line = calls[0][:2]
+    for ob in _items(obs):
+        if isinstance(ob, bpy.types.Object) and not removed(ob):
+            name = _core.given_name(ob)
+            copy = name if _code(name) == name else "..."
+            keep = "" if verb == "at" else f" To keep it, pass s3d.copy({copy}) to {verb} instead."
+            _gone[id(ob)] = (ob, f"{name!r} was used up by {verb}({_code(_core.given_name(target))}, ...) on line "
+                                 f"{line}; {REASONS[verb]}.{keep}")
+
+
+def deleting(ob):
+    """Record that the program deletes `ob` with `delete`."""
+    if calls and calls[0][0] == "delete":
+        name = _core.given_name(ob)
+        _gone[id(ob)] = (ob, f"{name!r} was deleted by delete({_code(name)}) on line {calls[0][1]}.")
+
+
+def watch(value, line):
+    """Watch an `at()` result: if it is freed unused, the next verb says so."""
+    value._s3d_from = line
+    value._s3d_used = False
+    _watched.add(value)
+    return value
+
+
+def use(value):
+    """`value` was used: no error if it is freed now."""
+    if getattr(value, "_s3d_used", True) is False:
+        value._s3d_used = True
+
+
+def freed(value):
+    """Called by `__del__`: arm the error if an `at()` result goes unused."""
+    global pending
+    if getattr(value, "_s3d_used", True) is False and pending is None:
+        pending = _unused(value)
+
+
+def _unused(value):
+    from .profile import Placed
+    kind = "profile" if isinstance(value, Placed) else "path"
+    return f"at() on line {value._s3d_from} placed a {kind} that nothing used; write p = s3d.at(p, ...)"
+
+
+def _items(args):
+    """The objects, placed profiles and paths a call was given: lists opened (not points),
+    a handle by its root."""
+    from .assembly import Handle
+    from .profile import Path, Placed
+    for a in args:
+        if isinstance(a, (bpy.types.ID, Placed, Path)):
+            yield a
+        elif isinstance(a, Handle):
+            yield a.root
+        elif isinstance(a, (list, tuple)) and not (a and isinstance(a[0], (int, float))):
+            yield from _items(a)
+
+
+def begin(verb, args, kwargs):
+    """At the entry of a public verb: raise what is pending, refuse what is gone or passed
+    twice, and mark what it is given as used."""
+    global pending
+    for keyword, message in REMOVED.get(verb, {}).items():
+        if keyword in kwargs:
+            raise TypeError(message)
+    if pending is not None:
+        message, pending = pending, None
+        raise ValueError(f"{verb}: {message}")
+    for item in _items(list(args) + list(kwargs.values())):
+        if isinstance(item, bpy.types.ID):
+            if verb != "delete" and removed(item):
+                gone = _gone.get(id(item))
+                raise ValueError(f"{verb}: {gone[1]}" if gone else f"{verb}: an object given was removed from the scene")
+        else:
+            use(item)
+    if verb == "export":
+        unused = sorted((v._s3d_from, _unused(v)) for v in list(_watched) if v._s3d_used is False)
+        if unused:
+            raise ValueError(f"{verb}: {unused[0][1]}")
+    if verb in DISTINCT:
+        obs = [o for o in _items(args[DISTINCT[verb]:]) if isinstance(o, bpy.types.Object)]
+        seen = {}
+        for o in obs:
+            seen[o.as_pointer()] = seen.get(o.as_pointer(), 0) + 1
+        for o in obs:
+            if seen[o.as_pointer()] > 1:
+                name = _core.given_name(o)
+                at = name if _code(name) == name else "..."
+                raise ValueError(f"{verb}: {name!r} is passed {seen[o.as_pointer()]} times; at moves an object, it "
+                                 f"does not copy it: s3d.at({at}, on=s3d.ring(...)) places one copy per frame")