@funpixel/tools 0.0.0-stage → 0.1.1

package/bench/handlers/fit_rig.py

@@ -0,0 +1,273 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`fit_rig` — graft a donor armature onto an unrigged mesh.
+
+A direct port of `tallow/tools/blender-fit-rig.py`, whose opening line states the
+problem better than a summary would:
+
+    Vendors' riggers refuse a figure whose limbs read as one mass (the Founder's
+    cupped hands and long robe). Blender does not care: import Ilse's repaired
+    rig, scale it to the target's height, seat it at the target's hips, and
+    parent the target mesh to it with automatic (bone-heat) weights.
+
+THE FALLBACK IS THE POINT, not a safety net. Bone heat *silently* gives up on a
+generated mesh because it is not a closed manifold, leaving vertices with no
+weight at all — and an unweighted vertex renders in the bind pose, so the
+character tears or stands still while the rest of it moves. Nothing downstream
+sees this. The script's own words:
+
+    Bone heat gives up on a generated mesh (it is not a closed manifold). Fall
+    back to the nearest two bone segments, weighted by inverse squared distance:
+    crude, but a wax figure that moves stiffly is the brief.
+
+So this verb MEASURES the unweighted fraction, reports it either way, and falls
+back past the 5% threshold the script used. The constants below are the
+script's, not re-derived: they shipped a game.
+
+BONE NAMES ARE PRESERVED. The donor's names ride through untouched so a runtime
+`borrowClips` can bind by NAME at load. Renaming them "tidily" would break
+exactly that.
+"""
+import os
+
+import bpy
+import mathutils
+from mathutils import Vector
+
+from . import scene
+
+# Past this share of unweighted vertices, bone heat has failed and the fallback
+# takes over. The script's threshold, and it shipped.
+BONE_HEAT_FAILURE_FRACTION = 0.05
+
+# A second bone contributes only when it is genuinely comparable. Beyond this
+# ratio the nearest bone owns the vertex alone — the script's 1.6.
+SECOND_BONE_CUTOFF = 1.6
+
+# Guards the inverse-square division for a vertex sitting exactly on a bone.
+EPSILON = 1e-6
+
+# A raw generation can arrive lying down. The script stands it up when one
+# horizontal extent exceeds the vertical by this much.
+LYING_DOWN_RATIO = 1.3
+
+
+def _biggest_mesh(objects=None):
+    """The character is the big one.
+
+    `blender-fix-leg.py` explains why this is not arbitrary: "the file also
+    carries a 42-vertex icosphere (a rigger's marker); the character is the big
+    one." Picking the first mesh would pick the marker.
+    """
+    pool = objects if objects is not None else bpy.data.objects
+    meshes = [o for o in pool if o.type == "MESH"]
+    if not meshes:
+        raise ValueError("no mesh found")
+    return max(meshes, key=lambda o: len(o.data.vertices))
+
+
+def _bounds(obj):
+    pts = [obj.matrix_world @ Vector(c) for c in obj.bound_box]
+    lo = Vector((min(p.x for p in pts), min(p.y for p in pts), min(p.z for p in pts)))
+    hi = Vector((max(p.x for p in pts), max(p.y for p in pts), max(p.z for p in pts)))
+    return lo, hi
+
+
+def _stand_up(target):
+    """Rotate a model that arrived lying along X or Y so it is Z-up.
+
+    "A raw generation can arrive Z-forward" — and a character fitted to a rig
+    while lying down is weighted against the wrong axis, so this must happen
+    BEFORE the fit, not as a cosmetic fix afterwards.
+    """
+    lo, hi = _bounds(target)
+    size = hi - lo
+    if size.y > size.z * LYING_DOWN_RATIO or size.x > size.z * LYING_DOWN_RATIO:
+        axis = "X" if size.x >= size.y else "Y"
+        target.rotation_euler = (
+            (1.5708, 0, 0) if axis == "Y" else (0, 1.5708, 0)
+        )
+        bpy.ops.object.transform_apply(rotation=True)
+        return axis
+    return ""
+
+
+def _nearest_bone_weights(target, arm):
+    """Weight every vertex to its nearest two deform-bone SEGMENTS.
+
+    Distance to a bone is distance to its segment, not to its head: a long bone
+    is close along its whole length, and using the head alone weights a thigh
+    to the hip.
+    """
+    segs = []
+    for b in arm.data.bones:
+        if not b.use_deform:
+            continue
+        head = arm.matrix_world @ b.head_local
+        tail = arm.matrix_world @ b.tail_local
+        segs.append((b.name, head, tail))
+    if len(segs) < 2:
+        raise ValueError(
+            "the donor rig has %d deform bones; the fallback needs at least 2" % len(segs)
+        )
+
+    for g in list(target.vertex_groups):
+        target.vertex_groups.remove(g)
+    groups = {name: target.vertex_groups.new(name=name) for name, _, _ in segs}
+
+    mw = target.matrix_world
+    for v in target.data.vertices:
+        p = mw @ v.co
+        best = []
+        for name, head, tail in segs:
+            q, _ = mathutils.geometry.intersect_point_line(p, head, tail)
+            span = (tail - head).length
+            # Clamp to the segment: the infinite line's nearest point can lie
+            # past the bone's end, which would weight a foot to a shin bone
+            # extended through the floor.
+            f = (
+                0.0
+                if span == 0
+                else max(0.0, min(1.0, (q - head).dot(tail - head) / (span * span)))
+            )
+            closest = head + (tail - head) * f
+            best.append(((p - closest).length, name))
+        best.sort()
+        (d0, n0), (d1, n1) = best[0], best[1]
+        w0 = 1.0 / (d0 * d0 + EPSILON)
+        w1 = 1.0 / (d1 * d1 + EPSILON)
+        if d1 > d0 * SECOND_BONE_CUTOFF:
+            w1 = 0.0
+        total = w0 + w1
+        groups[n0].add([v.index], w0 / total, "REPLACE")
+        if w1:
+            groups[n1].add([v.index], w1 / total, "REPLACE")
+    return len(segs)
+
+
+def _unweighted_count(mesh_obj, deform_names):
+    """Vertices with no weight to any DEFORM bone.
+
+    Weight to a control bone does not move a vertex, so counting "has any
+    group" would report a bound mesh where there is none.
+    """
+    name_by_index = {g.index: g.name for g in mesh_obj.vertex_groups}
+    deform_indices = {i for i, n in name_by_index.items() if n in deform_names}
+    return sum(
+        1
+        for v in mesh_obj.data.vertices
+        if not any(g.group in deform_indices and g.weight > 0.0 for g in v.groups)
+    )
+
+
+def run(args):
+    target_path = args.get("model_path") or ""
+    donor_path = args.get("donor_path") or ""
+    out_path = args.get("out_path") or ""
+    if not target_path or not os.path.isfile(target_path):
+        raise ValueError("model_path does not exist")
+    if not donor_path or not os.path.isfile(donor_path):
+        raise ValueError("donor_path does not exist")
+    if not out_path:
+        raise ValueError("out_path is required — this verb writes a new model")
+
+    # ── the donor rig ───────────────────────────────────────────────────────
+    scene.import_model(donor_path, args.get("donor_format") or "")
+    donor_objs = set(bpy.data.objects)
+    arm = next((o for o in donor_objs if o.type == "ARMATURE"), None)
+    if arm is None:
+        raise ValueError("the donor file contains no armature")
+
+    donor_mesh = _biggest_mesh(donor_objs)
+    d_lo, d_hi = _bounds(donor_mesh)
+    donor_height = d_hi.z - d_lo.z
+    if donor_height <= 0:
+        raise ValueError("the donor mesh has no height to scale against")
+
+    # Drop the donor's own mesh (and its marker icosphere); keep the armature
+    # and its actions — those are what the target is here to borrow.
+    for o in list(donor_objs):
+        if o.type == "MESH":
+            bpy.data.objects.remove(o, do_unlink=True)
+
+    deform_names = {b.name for b in arm.data.bones if b.use_deform}
+    if not deform_names:
+        raise ValueError("the donor armature has no deform bones")
+
+    # ── the target mesh ─────────────────────────────────────────────────────
+    before = set(bpy.data.objects)
+    fmt = args.get("format") or ""
+    target_fmt = fmt or scene.sniff(target_path)
+    scene.import_into_current(target_path, target_fmt)
+    new = [o for o in bpy.data.objects if o not in before]
+    target = _biggest_mesh(new)
+
+    # Apply transforms so the mesh's own coordinates ARE world coordinates —
+    # everything below measures in world space.
+    bpy.ops.object.select_all(action="DESELECT")
+    target.select_set(True)
+    bpy.context.view_layer.objects.active = target
+    if target.parent:
+        bpy.ops.object.parent_clear(type="CLEAR_KEEP_TRANSFORM")
+    bpy.ops.object.transform_apply(location=True, rotation=True, scale=True)
+
+    stood_up = _stand_up(target)
+
+    t_lo, t_hi = _bounds(target)
+    size = t_hi - t_lo
+    target_height = size.z
+    if target_height <= 0:
+        raise ValueError("the target mesh has no height to fit against")
+
+    # Feet on the ground, centred.
+    target.location -= Vector(
+        ((t_lo.x + t_hi.x) / 2, (t_lo.y + t_hi.y) / 2, t_lo.z)
+    )
+    bpy.ops.object.transform_apply(location=True)
+
+    # ── fit the rig ─────────────────────────────────────────────────────────
+    s = target_height / donor_height
+    arm.scale = (s, s, s)
+    bpy.ops.object.select_all(action="DESELECT")
+    arm.select_set(True)
+    bpy.context.view_layer.objects.active = arm
+    bpy.ops.object.transform_apply(scale=True)
+    a_lo, a_hi = _bounds(arm)
+    arm.location -= Vector(((a_lo.x + a_hi.x) / 2, (a_lo.y + a_hi.y) / 2, a_lo.z))
+    bpy.ops.object.transform_apply(location=True)
+
+    # ── bone heat, then measure ─────────────────────────────────────────────
+    bpy.ops.object.select_all(action="DESELECT")
+    target.select_set(True)
+    arm.select_set(True)
+    bpy.context.view_layer.objects.active = arm
+    bpy.ops.object.parent_set(type="ARMATURE_AUTO")
+
+    total_verts = len(target.data.vertices)
+    unweighted = _unweighted_count(target, deform_names)
+    fraction = (unweighted / total_verts) if total_verts else -1.0
+    method = "bone_heat"
+    bones_used = len(deform_names)
+
+    if total_verts and unweighted > total_verts * BONE_HEAT_FAILURE_FRACTION:
+        bones_used = _nearest_bone_weights(target, arm)
+        method = "nearest_bone"
+        unweighted = _unweighted_count(target, deform_names)
+        fraction = unweighted / total_verts
+
+    # ── export mesh + armature + the donor's actions ────────────────────────
+    bpy.ops.object.select_all(action="DESELECT")
+    target.select_set(True)
+    arm.select_set(True)
+    scene.export_glb(out_path, selected_only=True)
+
+    return {
+        "out_path": out_path,
+        "weighting_method": method,
+        "unweighted_vertices": unweighted,
+        "unweighted_fraction": fraction,
+        "total_vertices": total_verts,
+        "bones_used": bones_used,
+        "scale_applied": s,
+        "stood_up_from_axis": stood_up,
+        "clips_borrowed": [a.name for a in bpy.data.actions],
+    }

package/bench/handlers/fracture.py

@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`fracture` — pre-break a prop into Voronoi shards that keep their UVs (b10).
+
+One studio's smashing game broke pre-fractured pieces, and its prep script
+did it this way (research 12 §3 #12): seeds inside the bounds, one cell per
+seed, each cell cut out of the whole mesh by repeated `bisect_plane` against
+every other seed, the cut holes filled — "so every shard carries its piece of
+the pattern". A cell is the half-space intersection that makes it Voronoi: the
+plane between seeds i and j keeps the side nearer i.
+
+UVs ARE KEPT because the surface is never rebuilt: `bisect_plane` splits the
+existing faces and interpolates their corners' UVs, and everything on a cell's
+side survives exactly as authored. The cap over a cut is NEW geometry — its own
+vertices, never welded to the surface (see `decimate.py` for what welding
+does) — and each cap corner takes the UV of the surface point it was cut from,
+so the break shows the edge of the pattern rather than a blank.
+
+STATIC PROPS ONLY. A skinned mesh is refused: shards of a character follow no
+bone. And the source must already be at a phone budget
+(`MAX_SOURCE_TRIANGLES`): every cell cuts the whole mesh once per other seed,
+so the work is pieces² × triangles. Decimate first.
+"""
+import os
+import random
+
+import bmesh
+import bpy
+from mathutils import Vector
+
+from . import scene
+
+MAX_SOURCE_TRIANGLES = 20_000
+MIN_PIECES, MAX_PIECES, DEFAULT_PIECES = 2, 32, 8
+
+# Seeds stay this far inside the bounds on every side, so no cell is a sliver
+# along the outside of the model.
+SEED_MARGIN = 0.1
+
+
+def _joined_mesh(meshes):
+    """One bmesh of every mesh in world space, materials kept by name."""
+    bm = bmesh.new()
+    materials = []
+    for o in meshes:
+        index = {}
+        for i, slot in enumerate(o.material_slots):
+            if slot.material is not None and slot.material not in materials:
+                materials.append(slot.material)
+            index[i] = materials.index(slot.material) if slot.material in materials else 0
+        mesh = o.data.copy()
+        mesh.transform(o.matrix_world)
+        for p in mesh.polygons:
+            p.material_index = index.get(p.material_index, 0)
+        bm.from_mesh(mesh)
+        bpy.data.meshes.remove(mesh)
+    return bm, materials
+
+
+def _cap(bm, cut_edges, normal, eps, uv, mark):
+    """Fill the hole one cut left with new, unwelded faces, marked `mark`.
+
+    Filled after EVERY cut, not once at the end: a closed surface cut by a plane
+    leaves a closed loop, and filling it keeps the cell closed, so the next cut
+    meets a closed surface again. Filled once at the end, each plane's share of
+    the hole is an open arc bounded by the OTHER planes' cuts, and a fill of an
+    open arc makes nothing — measured: 0 cap triangles on every shard of a
+    closed sphere, until the fill moved here.
+
+    One new vertex per distinct position: the loop is closed even where the
+    surface was split at a UV seam (two vertices, one place). A source mesh
+    that is not closed (an open bottom) leaves an open loop, and that cut stays
+    open — reported through the cap count, never papered over.
+    """
+    made = {}
+    source_uv = {}
+    material = 0
+
+    def new_vert(v):
+        key = tuple(round(c / eps) for c in v.co)
+        if key not in made:
+            made[key] = bm.verts.new(v.co)
+            if uv is not None and v.link_loops:
+                source_uv[made[key]] = v.link_loops[0][uv].uv.copy()
+        return made[key]
+
+    new_edges = []
+    for e in cut_edges:
+        a, b = new_vert(e.verts[0]), new_vert(e.verts[1])
+        if a is b or bm.edges.get((a, b)) is not None:
+            continue
+        new_edges.append(bm.edges.new((a, b)))
+        if e.link_faces:
+            material = e.link_faces[0].material_index
+    if not new_edges:
+        return
+    filled = bmesh.ops.triangle_fill(bm, use_beauty=True, use_dissolve=False, edges=new_edges)
+    faces = [g for g in filled["geom"] if isinstance(g, bmesh.types.BMFace)]
+    for f in faces:
+        f[mark] = 1
+        f.material_index = material
+        f.normal_update()
+        # The cap faces out of the cell, along the plane's normal.
+        if f.normal.dot(normal) < 0:
+            f.normal_flip()
+        if uv is not None:
+            for loop in f.loops:
+                if loop.vert in source_uv:
+                    loop[uv].uv = source_uv[loop.vert]
+    # Cap edges the fill could not use (an open loop) would export as lines.
+    for e in new_edges:
+        if e.is_valid and not e.link_faces:
+            bm.edges.remove(e)
+    for v in list(made.values()):
+        if v.is_valid and not v.link_edges:
+            bm.verts.remove(v)
+
+
+def _cell(source, seeds, i, eps):
+    """Cell i: the source cut by the plane between seed i and every other seed.
+
+    Returns the cell and how many of its triangles are cap (a later cut can
+    remove part of an earlier cap, so they are counted at the end, by mark).
+    """
+    bm = source.copy()
+    uv = bm.loops.layers.uv.active
+    mark = bm.faces.layers.int.new("fp_cap")
+    p = seeds[i]
+    for j, q in enumerate(seeds):
+        if j == i or not bm.faces:
+            continue
+        normal = (q - p).normalized()
+        geom = bm.verts[:] + bm.edges[:] + bm.faces[:]
+        cut = bmesh.ops.bisect_plane(
+            bm, geom=geom, plane_co=(p + q) / 2, plane_no=normal, clear_outer=True
+        )
+        edges = [
+            e
+            for e in cut["geom_cut"]
+            if isinstance(e, bmesh.types.BMEdge) and e.is_valid and e.is_boundary
+        ]
+        _cap(bm, edges, normal, eps, uv, mark)
+    bmesh.ops.triangulate(bm, faces=bm.faces[:])
+    caps = sum(1 for f in bm.faces if f[mark])
+    bm.faces.layers.int.remove(mark)
+    return bm, caps
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    out_path = args.get("out_path") or ""
+    if not path or not os.path.isfile(path):
+        raise ValueError("model_path does not exist")
+    if not out_path:
+        raise ValueError("out_path is required — this verb writes a new model")
+    pieces = scene.clamp_int(args.get("pieces"), DEFAULT_PIECES, MIN_PIECES, MAX_PIECES)
+    seed = int(args.get("seed") or 0)
+
+    scene.import_model(path, args.get("format") or "")
+    meshes = scene.mesh_objects()
+    if not meshes:
+        raise ValueError("the file imported but contains no mesh")
+    skinned = [o.name for o in meshes if scene.is_skinned(o)]
+    if skinned:
+        raise ValueError(
+            "mesh '%s' is skinned to an armature; fracture is for static props — "
+            "shards of a rigged mesh follow no bone" % skinned[0]
+        )
+    source_tris = sum(scene.triangles(o) for o in meshes)
+    if source_tris > MAX_SOURCE_TRIANGLES:
+        raise ValueError(
+            "the model has %d triangles (max %d to fracture); decimate it to a phone "
+            "budget first" % (source_tris, MAX_SOURCE_TRIANGLES)
+        )
+
+    source, materials = _joined_mesh(meshes)
+    lo = Vector([min(v.co[k] for v in source.verts) for k in range(3)])
+    hi = Vector([max(v.co[k] for v in source.verts) for k in range(3)])
+    size = hi - lo
+    eps = max(size.length * 1e-5, 1e-7)
+    rng = random.Random(seed)
+    seeds = [
+        Vector(
+            [lo[k] + size[k] * (SEED_MARGIN + (1 - 2 * SEED_MARGIN) * rng.random()) for k in range(3)]
+        )
+        for _ in range(pieces)
+    ]
+    uv_name = source.loops.layers.uv.active
+
+    for o in list(bpy.data.objects):
+        bpy.data.objects.remove(o, do_unlink=True)
+
+    shards = []
+    for i in range(pieces):
+        bm, cap_tris = _cell(source, seeds, i, eps)
+        if not bm.faces:
+            bm.free()
+            continue  # a seed whose cell holds none of the surface
+        centre = sum((v.co for v in bm.verts), Vector()) / len(bm.verts)
+        for v in bm.verts:
+            v.co -= centre
+        name = "shard_%03d" % len(shards)
+        mesh = bpy.data.meshes.new(name)
+        bm.to_mesh(mesh)
+        bm.free()
+        for m in materials:
+            mesh.materials.append(m)
+        obj = bpy.data.objects.new(name, mesh)
+        obj.location = centre
+        bpy.context.scene.collection.objects.link(obj)
+        shards.append(
+            {
+                "name": name,
+                "triangles": len(mesh.polygons),
+                "cap_triangles": cap_tris,
+                "centre": list(centre),
+                "has_uv": uv_name is not None and len(mesh.uv_layers) > 0,
+            }
+        )
+    source.free()
+    if len(shards) < 2:
+        raise ValueError(
+            "only %d of %d cells held any of the model; try another seed" % (len(shards), pieces)
+        )
+
+    scene.export_glb(out_path)
+    return {
+        "out_path": out_path,
+        "pieces_requested": pieces,
+        "source_triangles": source_tris,
+        "shards": shards,
+        "uv_kept": uv_name is not None and all(s["has_uv"] for s in shards),
+        "external_images_dropped": scene.EXTERNAL_IMAGES_DROPPED,
+    }

package/bench/handlers/humanoid.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The humanoid skeleton as the motion verbs see it: named SLOTS found by bone
+name under the common conventions, and poses made in WORLD terms.
+
+Two rigs name the same bone `LeftArm`, `mixamorig:LeftArm`, `upper_arm.L` or
+`UpperArm_L`; `normalise` folds them to one key. Two rigs also disagree about
+which local axis bends an elbow, so nothing here rotates a bone about a local
+axis: `turn` rotates it about a WORLD axis around its head, and `toward` picks
+the sign by measuring where the bone's tail goes — "raise the arm" is "the
+hand ends higher", whatever the rig's axes.
+"""
+import re
+
+import bpy
+from mathutils import Matrix, Quaternion, Vector
+
+# Slot → normalised bone names, first match wins.
+SLOTS = {
+    "hips": ("hips", "pelvis", "root"),
+    "spine": ("spine", "spine1", "spine01", "chest", "torso"),
+    "chest": ("spine2", "spine02", "chest", "upperchest", "spine1"),
+    "neck": ("neck", "neck1", "neck01"),
+    "head": ("head",),
+    "l_upper": ("leftarm", "upperarml", "arml", "lupperarm", "leftupperarm"),
+    "l_fore": ("leftforearm", "forearml", "lowerarml", "lforearm", "leftlowerarm"),
+    "r_upper": ("rightarm", "upperarmr", "armr", "rupperarm", "rightupperarm"),
+    "r_fore": ("rightforearm", "forearmr", "lowerarmr", "rforearm", "rightlowerarm"),
+    "l_thigh": ("leftupleg", "thighl", "upperlegl", "leftupperleg", "lthigh"),
+    "r_thigh": ("rightupleg", "thighr", "upperlegr", "rightupperleg", "rthigh"),
+    "l_shin": ("leftleg", "shinl", "lowerlegl", "calfl", "leftlowerleg"),
+    "r_shin": ("rightleg", "shinr", "lowerlegr", "calfr", "rightlowerleg"),
+}
+
+
+def normalise(name):
+    """`mixamorig:Left_Arm` → `leftarm`; `upper_arm.L` → `upperarml`."""
+    tail = name.split(":")[-1].split("|")[-1]
+    return re.sub(r"[^a-z0-9]", "", tail.lower())
+
+
+def slots(arm):
+    """Slot → pose bone for every slot this rig has."""
+    by = {}
+    for pb in arm.pose.bones:
+        by.setdefault(normalise(pb.name), pb)
+    out = {}
+    for slot, names in SLOTS.items():
+        for n in names:
+            if n in by:
+                out[slot] = by[n]
+                break
+    return out
+
+
+def world_rot(arm):
+    return arm.matrix_world.to_quaternion()
+
+
+def reset(bones):
+    for pb in bones:
+        pb.rotation_mode = "QUATERNION"
+        pb.rotation_quaternion = Quaternion()
+        pb.location = Vector()
+
+
+def update():
+    bpy.context.view_layer.update()
+
+
+def turn(arm, pb, axis_world, angle):
+    """Rotate `pb` by `angle` about a world axis through its head, on top of its pose."""
+    w = world_rot(arm)
+    axis = (w.inverted() @ Vector(axis_world)).normalized()
+    head = pb.matrix.to_translation()
+    rot = Matrix.Rotation(angle, 4, axis)
+    pb.matrix = Matrix.Translation(head) @ rot @ Matrix.Translation(-head) @ pb.matrix
+    update()
+
+
+def tail_world(arm, pb):
+    return arm.matrix_world @ pb.tail
+
+
+def toward(arm, pb, axis_world, angle, want_world):
+    """`turn` by ±`angle`, whichever moves the tail further along `want_world`."""
+    before = pb.matrix.copy()
+    start = tail_world(arm, pb)
+    turn(arm, pb, axis_world, angle)
+    plus = (tail_world(arm, pb) - start).dot(Vector(want_world))
+    pb.matrix = before
+    update()
+    turn(arm, pb, axis_world, -angle)
+    minus = (tail_world(arm, pb) - start).dot(Vector(want_world))
+    if plus > minus:
+        pb.matrix = before
+        update()
+        turn(arm, pb, axis_world, angle)
+
+
+def frame(arm, s):
+    """The body's frame in world terms: (forward, up, left). A glTF character
+    faces +Z, which Blender's importer turns into -Y; the arms say which side
+    is left when both are found."""
+    up = Vector((0.0, 0.0, 1.0))
+    forward = Vector((0.0, -1.0, 0.0))
+    left = forward.cross(up) * -1.0
+    if "l_upper" in s and "r_upper" in s:
+        lx = (arm.matrix_world @ s["l_upper"].head).x
+        rx = (arm.matrix_world @ s["r_upper"].head).x
+        if lx < rx:
+            left = -left
+            forward = -forward
+    return forward, up, left
+
+
+def to_arm(arm, v):
+    """A world-space offset in the armature's own space, its scale included: an imported
+    rig often sits under a 0.01 object scale, where 1 cm of world is 1 unit."""
+    return arm.matrix_world.to_3x3().inverted() @ Vector(v)