@funpixel/tools 0.0.0-stage → 0.1.1

package/bench/handlers/lod.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`lod` — a chain of levels of detail from one model (plan b8).
+
+LOD1..LODn, each `ratio` of the triangles of the SOURCE to the power of its
+level (0.5 → 50%, 25%, 12.5%). The source itself is LOD0: the caller already
+has it, so it is not sent back.
+
+Each level is cut from the level before it, not from the source: collapse is
+the expensive part, and a coarser level decimated from a finer one keeps the
+same silhouette priorities the finer one chose, so the levels pop less when an
+engine switches between them.
+
+Every level goes through `decimate.reduce_to`, so it inherits the verb's
+guarantees: no weld (UV seams stay open boundaries), skin influences held to
+the SOURCE's maximum, shape keys refused, and a refusal with the numbers when a
+level would leave vertices unweighted.
+
+The chain STOPS at `min_triangles` rather than cutting below it: a level that
+is a silhouette is not a level anyone draws. Fewer levels than asked is an
+answer (`stopped_at_floor`), not an error.
+"""
+import os
+
+from . import decimate
+from . import scene
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    out_dir = args.get("out_dir") or ""
+    if not path or not os.path.isfile(path):
+        raise ValueError("model_path does not exist")
+    if not out_dir or not os.path.isdir(out_dir):
+        raise ValueError("out_dir is required — this verb writes new models")
+    levels = scene.clamp_int(args.get("levels"), 3, 1, 4)
+    ratio = float(args.get("ratio") or 0.5)
+    if not 0.05 <= ratio <= 0.95:
+        raise ValueError("ratio must be 0.05–0.95, got %s" % ratio)
+    floor = scene.clamp_int(args.get("min_triangles"), 100, 1, 200000)
+
+    scene.import_model(path, args.get("format") or "")
+    meshes = scene.mesh_objects()
+    if not meshes:
+        raise ValueError("the file imported but contains no mesh")
+    skin = decimate.skin_of(meshes, scene.armature_object())
+    source = sum(scene.triangles(o) for o in meshes)
+    uv_source = decimate.uv_split_vertices(meshes)
+    if source <= floor:
+        raise ValueError(
+            "the model has %d triangles, already at or below the floor of %d: "
+            "there is nothing to make a lower level from" % (source, floor)
+        )
+
+    out = []
+    stopped = False
+    for level in range(1, levels + 1):
+        target = int(round(source * ratio**level))
+        if target < floor:
+            stopped = True
+            break
+        limited = decimate.reduce_to(meshes, target, skin)
+        out_path = os.path.join(out_dir, "lod%d.glb" % level)
+        scene.export_glb(out_path)
+        triangles = sum(scene.triangles(o) for o in meshes)
+        out.append(
+            {
+                "level": level,
+                "out_path": out_path,
+                "target_triangles": target,
+                "triangles": triangles,
+                "ratio_of_source": triangles / source,
+                "uv_split_vertices": decimate.uv_split_vertices(meshes),
+                "vertices_influence_limited": limited,
+            }
+        )
+    return {
+        "triangles_source": source,
+        "uv_split_vertices_source": uv_source,
+        "levels": out,
+        "stopped_at_floor": stopped,
+        "max_influences": max((s[1] for s in skin.values()), default=0),
+        "external_images_dropped": scene.EXTERNAL_IMAGES_DROPPED,
+    }

package/bench/handlers/merge_clips.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`merge_clips` — one rigged model with every clip in it, each under its bare name.
+
+A rig-and-animate run hands back the rigged model and one FILE per clip, each a
+whole copy of the mesh and skeleton carrying a single action. A game wants one
+file: load it once and play `walk`, `idle` or `death` by name. The copies'
+skeletons are the rigged model's (the same bone names), so an action keyed on one
+plays on the other. This verb imports each clip file next to the model, keeps its
+action under the name the caller gives, and throws the copy away.
+
+Refused, never approximated:
+  * a clip file with no action that moves a bone;
+  * an action keyed on bones the model does not have (it was rigged differently —
+    the clip would play on nothing and look like a frozen character).
+
+The model's own actions are dropped first (a rigged model often carries an
+unnamed default take); they are listed in `dropped`.
+"""
+import os
+import re
+
+import bpy
+
+from . import scene
+
+NAME = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
+MAX_CLIPS = 16
+
+
+def _bones_keyed(action):
+    out = set()
+    for fc in action.fcurves:
+        if 'pose.bones["' in fc.data_path:
+            out.add(fc.data_path.split('"')[1])
+    return out
+
+
+def _bind(action, arm):
+    """Point the action's slot at our armature (Blender 4.4+ plays an action
+    through a slot, and the exporter only writes a clip its armature can play)."""
+    slots = getattr(action, "slots", None)
+    if slots is not None and len(slots):
+        try:
+            slots[0].name_display = arm.name
+        except (AttributeError, TypeError):
+            pass
+    ad = arm.animation_data or arm.animation_data_create()
+    ad.action = action
+    if hasattr(ad, "action_slot") and slots is not None and len(slots):
+        ad.action_slot = slots[0]
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    out_path = args.get("out_path") or ""
+    clips = args.get("clips") 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")
+    if not isinstance(clips, list) or not clips or len(clips) > MAX_CLIPS:
+        raise ValueError("clips must list 1-%d {name, path} entries" % MAX_CLIPS)
+    names = [c.get("name") or "" for c in clips]
+    for n in names:
+        if not NAME.match(n):
+            raise ValueError("clip name %r must be lowercase letters, digits or _" % n)
+    if len(set(names)) != len(names):
+        raise ValueError("clip names must be unique")
+
+    scene.import_model(path, args.get("format") or "")
+    arm = scene.armature_object()
+    if arm is None:
+        raise ValueError("the model has no armature: there is nothing to play clips on")
+    bones = {b.name for b in arm.data.bones}
+    keep = set(bpy.data.objects)
+
+    dropped = []
+    for a in list(bpy.data.actions):
+        dropped.append(a.name)
+        bpy.data.actions.remove(a)
+
+    merged = []
+    for c in clips:
+        clip_path = c.get("path") or ""
+        if not os.path.isfile(clip_path):
+            raise ValueError("clip %s: file does not exist" % c["name"])
+        before = set(bpy.data.actions)
+        scene.import_into_current(clip_path, "")
+        new = [a for a in bpy.data.actions if a not in before]
+        moving = [a for a in new if _bones_keyed(a)]
+        if not moving:
+            raise ValueError("clip %s: its file carries no action that moves a bone" % c["name"])
+        action = max(moving, key=lambda a: len(a.fcurves))
+        stray = sorted(_bones_keyed(action) - bones)
+        if stray:
+            raise ValueError(
+                "clip %s keys %d bones the model does not have (e.g. %s): it was rigged "
+                "differently" % (c["name"], len(stray), ", ".join(stray[:3]))
+            )
+        for a in new:
+            if a is not action:
+                bpy.data.actions.remove(a)
+        action.name = c["name"]
+        action.use_fake_user = True
+        for o in [o for o in bpy.data.objects if o not in keep]:
+            bpy.data.objects.remove(o, do_unlink=True)
+        start, end = (float(x) for x in action.frame_range)
+        merged.append({"name": action.name, "frames": end - start, "fcurves": len(action.fcurves)})
+
+    # The copies' meshes, materials and images are orphans now.
+    bpy.data.orphans_purge(do_local_ids=True, do_linked_ids=True, do_recursive=True)
+    for m in merged:
+        _bind(bpy.data.actions[m["name"]], arm)
+
+    bpy.ops.object.select_all(action="SELECT")
+    scene.export_glb(out_path)
+    return {
+        "out_path": out_path,
+        "clips": merged,
+        "dropped": dropped,
+        "bytes_after": os.path.getsize(out_path),
+    }

package/bench/handlers/mirror_limb.py

@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`mirror_limb` — rebuild a limb the auto-rigger missed, across X.
+
+A port of `tallow/tools/blender-fix-leg.py`, whose header is the whole case for
+the verb:
+
+    The rigger found the right leg (hip, knee, foot) but only a hip on the left:
+    the long coat hid the knee and the foot. So the left leg's vertices hang off
+    one bone and the character walks on one leg while the other drags.
+
+An auto-rigger finds what it can SEE. A coat, a cloak, a pair of cupped hands —
+anything that makes two limbs read as one mass — and the rig comes back
+asymmetric. The model loads, the skeleton looks plausible, and the character
+drags a leg.
+
+THREE PHASES, IN ORDER, AND THE ORDER MATTERS:
+  1. BONES    — mirror the source chain's heads/tails/rolls across X.
+  2. WEIGHTS  — re-weight each destination-side vertex from its mirror TWIN.
+  3. CURVES   — mirror the animation, half a cycle out of phase for a walk.
+
+Weights before curves because a curve on a bone nothing is weighted to moves
+nothing; bones before weights because there is nothing to weight to otherwise.
+
+THE HAND KEEPS WHAT IT HAS. The script guards vertices already weighted to an
+arm — "a hand or a sleeve keeps what it has: the candle is in that hand" — and
+that guard is why this verb can run on a character holding something without
+destroying the grip.
+
+GENERALISED FROM THE SCRIPT: the bone names are caller-supplied rather than
+hardcoded to one vendor's `tripo::` chain, because the next broken rig will not
+use those names. Everything else is the script's, including the 0.004 midline
+epsilon, the 0.03 twin-search radius and the 0.3 already-weighted threshold —
+those shipped a game.
+"""
+import os
+
+import bpy
+from mathutils import Vector, kdtree
+
+from . import scene
+
+# Vertices nearer the midline than this belong to neither side: mirroring them
+# would fight itself across the seam.
+MIDLINE_EPSILON = 0.004
+
+# How far from a vertex's mirrored position a twin may sit and still count. A
+# generated mesh is not perfectly symmetric, so this is slack, not precision.
+TWIN_RADIUS = 0.03
+
+# A vertex already carrying this much weight from a guarded group is doing a
+# job — holding a candle — and keeps what it has.
+GUARDED_WEIGHT = 0.3
+
+# Vertices above the hip line are torso, not limb.
+HIP_MARGIN = 0.03
+
+
+def _mirror(v):
+    return Vector((-v.x, v.y, v.z))
+
+
+def _mirror_value(path, index, value):
+    """Flip the components that change sign under an X mirror.
+
+    A quaternion mirrors on its Y and Z components (indices 2 and 3); a location
+    mirrors on X; an XYZ euler mirrors on its Y and Z angles, because a rotation
+    ABOUT X survives a reflection THROUGH X while the other two reverse.
+    Everything else passes through.
+
+    Getting this wrong produces an animation that plays confidently backwards on
+    one side only — a knee that bends outward — which renders, exports, and is
+    wrong. The euler case is NOT in `blender-fix-leg.py`: that rig was
+    quaternion throughout, so the gap only appears on a rig that is not.
+    """
+    if path.endswith("rotation_quaternion"):
+        return -value if index in (2, 3) else value
+    if path.endswith("rotation_euler"):
+        return -value if index in (1, 2) else value
+    if path.endswith("location"):
+        return -value if index == 0 else value
+    return value
+
+
+def _mirror_bones(arm, source, dest):
+    """Phase 1: mirror the source chain onto the destination side."""
+    bpy.context.view_layer.objects.active = arm
+    bpy.ops.object.mode_set(mode="EDIT")
+    eb = arm.data.edit_bones
+
+    missing = [n for n in source if n not in eb]
+    if missing:
+        bpy.ops.object.mode_set(mode="OBJECT")
+        raise ValueError(
+            "source bones not found: %s (the rig has %d bones)"
+            % (", ".join(missing), len(arm.data.bones))
+        )
+    if dest[0] not in eb:
+        bpy.ops.object.mode_set(mode="OBJECT")
+        raise ValueError(
+            "the destination root %r must already exist — this verb mirrors a "
+            "PARTIAL limb, it does not graft a whole new one" % dest[0]
+        )
+
+    # The root exists but points wrong: re-aim it from its mirror.
+    root_src, root_dst = eb[source[0]], eb[dest[0]]
+    root_dst.tail = _mirror(root_src.tail)
+    root_dst.roll = -root_src.roll
+
+    made = []
+    for i in range(1, len(source)):
+        src = eb[source[i]]
+        name = dest[i]
+        b = eb.get(name) or eb.new(name)
+        b.head = _mirror(src.head)
+        b.tail = _mirror(src.tail)
+        b.roll = -src.roll
+        # Parent to the previous DESTINATION bone, so the chain hangs together
+        # on its own side rather than reaching across the body.
+        b.parent = eb[dest[i - 1]]
+        b.use_connect = src.use_connect
+        b.use_deform = True
+        made.append(name)
+
+    bpy.ops.object.mode_set(mode="OBJECT")
+    return made
+
+
+def _mirror_weights(arm, mesh, source, dest, guard_prefixes):
+    """Phase 2: re-weight each destination-side vertex from its mirror twin.
+
+    Works below the hip line only, and leaves already-weighted vertices alone —
+    "the candle is in that hand".
+    """
+    vg = mesh.vertex_groups
+    for name in dest:
+        if vg.get(name) is None:
+            vg.new(name=name)
+
+    index_to_name = {g.index: g.name for g in vg}
+    name_to_index = {g.name: g.index for g in vg}
+    guarded = {
+        i
+        for i, n in index_to_name.items()
+        if any(p.lower() in n.lower() for p in guard_prefixes)
+    }
+
+    hip_z = (arm.matrix_world @ arm.data.bones[dest[0]].head_local).z
+    mw = mesh.matrix_world
+    verts = mesh.data.vertices
+    world = [mw @ v.co for v in verts]
+
+    # The SOURCE side sits at negative X once mirrored; build a lookup of its
+    # vertices so each destination vertex can find its twin.
+    src_indices = [
+        i
+        for i, w in enumerate(world)
+        if w.x < -MIDLINE_EPSILON and w.z < hip_z + HIP_MARGIN
+    ]
+    if not src_indices:
+        raise ValueError(
+            "no source-side vertices below the hip line — is the model mirrored "
+            "the other way, or not standing upright?"
+        )
+
+    tree = kdtree.KDTree(len(src_indices))
+    for k, i in enumerate(src_indices):
+        tree.insert(world[i], k)
+    tree.balance()
+
+    def flipped(name):
+        for s, d in zip(source, dest):
+            if name == s:
+                return d
+        return name
+
+    changed = skipped = 0
+    for i, w in enumerate(world):
+        if not (w.x > MIDLINE_EPSILON and w.z < hip_z + HIP_MARGIN):
+            continue
+        # A hand or a sleeve keeps what it has.
+        if sum(g.weight for g in verts[i].groups if g.group in guarded) > GUARDED_WEIGHT:
+            skipped += 1
+            continue
+        _, k, dist = tree.find(Vector((-w.x, w.y, w.z)))
+        if k is None or dist > TWIN_RADIUS:
+            skipped += 1
+            continue
+        twin = verts[src_indices[k]]
+        for g in list(verts[i].groups):
+            vg[g.group].remove([i])
+        for g in twin.groups:
+            name = flipped(index_to_name[g.group])
+            if name not in name_to_index:
+                name_to_index[name] = vg.new(name=name).index
+            vg[name_to_index[name]].add([i], g.weight, "REPLACE")
+        changed += 1
+    return changed, skipped
+
+
+def _match_rotation_modes(arm, source, dest):
+    """Give each destination bone its source's rotation mode.
+
+    CAUGHT BY THE GAIT PROBE, and invisible without one: a mirrored
+    `rotation_euler` curve written onto a bone whose `rotation_mode` is
+    QUATERNION is **silently ignored by the evaluator**. The curves exist, the
+    count is right, the file exports, and the leg does not move — which is the
+    exact defect this verb exists to repair, reproduced by the repair.
+
+    Measured on the fixture: source bones XYZ, destination QUATERNION (Blender's
+    default for a bone nobody set), left-leg amplitude 0.0000 against the right
+    leg's 1.0000.
+    """
+    changed = []
+    for s, d in zip(source, dest):
+        src_pb = arm.pose.bones.get(s)
+        dst_pb = arm.pose.bones.get(d)
+        if src_pb is None or dst_pb is None:
+            continue
+        if dst_pb.rotation_mode != src_pb.rotation_mode:
+            dst_pb.rotation_mode = src_pb.rotation_mode
+            changed.append(d)
+    return changed
+
+
+def _mirror_curves(source, dest):
+    """Phase 3: mirror the animation onto the destination chain.
+
+    A walk is mirrored HALF A CYCLE out of phase: both legs swinging together
+    is a hop, not a gait, and it is the single most visible tell of a mirrored
+    rig.
+    """
+    total = 0
+    per_action = []
+    for act in bpy.data.actions:
+        start, end = act.frame_range
+        length = max(1.0, end - start)
+        half = length / 2 if "walk" in act.name.lower() else 0.0
+
+        # Drop whatever the destination chain had: the mirrored source is the
+        # whole chain, and leaving the old curves would blend two animations.
+        for fc in [
+            f for f in act.fcurves if any('"%s"' % n in f.data_path for n in dest)
+        ]:
+            act.fcurves.remove(fc)
+
+        n = 0
+        for fc in [
+            f for f in act.fcurves if any('"%s"' % n2 in f.data_path for n2 in source)
+        ]:
+            path = fc.data_path
+            for s, d in zip(source, dest):
+                path = path.replace('"%s"' % s, '"%s"' % d)
+            new_fc = act.fcurves.new(
+                path, index=fc.array_index, action_group=path.split('"')[1]
+            )
+            pts = sorted(
+                (
+                    (
+                        ((kp.co.x - start + half) % length) + start,
+                        _mirror_value(path, fc.array_index, kp.co.y),
+                    )
+                    for kp in fc.keyframe_points
+                ),
+                key=lambda p: p[0],
+            )
+            # Keep the cycle closed: the last point wraps to the first frame.
+            if half and pts and pts[0][0] > start + 1e-6:
+                pts.insert(0, (start, pts[-1][1]))
+            new_fc.keyframe_points.add(len(pts))
+            for kp, (x, y) in zip(new_fc.keyframe_points, pts):
+                kp.co = (x, y)
+                kp.interpolation = "LINEAR"
+            new_fc.update()
+            n += 1
+        total += n
+        per_action.append(
+            {
+                "action": act.name,
+                "curves_mirrored": n,
+                "phase_shift": float(half),
+                "length": float(length),
+            }
+        )
+    return total, per_action
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    out_path = args.get("out_path") or ""
+    source = args.get("source_bones") or []
+    dest = args.get("dest_bones") 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")
+    if not isinstance(source, list) or not isinstance(dest, list):
+        raise ValueError("source_bones and dest_bones must be lists")
+    if len(source) < 2 or len(source) != len(dest):
+        raise ValueError(
+            "source_bones and dest_bones must be the same length and at least 2; "
+            "got %d and %d" % (len(source), len(dest))
+        )
+
+    scene.import_model(path, args.get("format") or "")
+    arm = scene.armature_object()
+    if arm is None:
+        raise ValueError("the model has no armature — there is no limb to mirror")
+
+    meshes = scene.mesh_objects()
+    if not meshes:
+        raise ValueError("the file imported but contains no mesh")
+    # The character is the big one; a rigger's marker icosphere is not.
+    mesh = max(meshes, key=lambda o: len(o.data.vertices))
+
+    bones_added = _mirror_bones(arm, source, dest)
+    # BEFORE the curves: a mirrored euler curve on a quaternion-mode bone is
+    # silently ignored, and the leg does not move. See _match_rotation_modes.
+    modes_fixed = _match_rotation_modes(arm, source, dest)
+    changed, skipped = _mirror_weights(
+        arm, mesh, source, dest, args.get("guard_prefixes") or []
+    )
+    curves, per_action = _mirror_curves(source, dest)
+
+    bpy.ops.object.select_all(action="SELECT")
+    scene.export_glb(out_path)
+
+    return {
+        "out_path": out_path,
+        "bones_added": bones_added,
+        "vertices_reweighted": changed,
+        "vertices_skipped": skipped,
+        "curves_mirrored": curves,
+        "rotation_modes_matched": modes_fixed,
+        "actions": per_action,
+    }

package/bench/handlers/motion_specs.json

@@ -0,0 +1,11 @@
+{
+  "//": "author_motion's kinds: each dial's [low, high, default], the range the kind was tuned within. ONE file: the bench reads it (author_motion.py) and the Tools API checks a request against it at submit (tools_api::motion).",
+  "kinds": {
+    "wave": { "sided": true, "needs": ["upper", "fore"], "dials": { "seconds": [0.8, 3.0, 1.6], "lift_deg": [60, 160, 130], "swings": [1, 5, 3], "swing_deg": [10, 40, 25] } },
+    "nod": { "sided": false, "needs": ["head"], "dials": { "seconds": [0.4, 2.0, 0.8], "times": [1, 3, 2], "depth_deg": [5, 30, 20] } },
+    "hop": { "sided": false, "needs": ["hips"], "dials": { "seconds": [0.4, 1.2, 0.6], "height": [0.03, 0.25, 0.12], "crouch": [0.0, 0.12, 0.05] } },
+    "strike": { "sided": true, "needs": ["upper", "spine"], "dials": { "seconds": [0.3, 1.5, 0.6], "windup_share": [0.2, 0.5, 0.35], "reach_deg": [40, 110, 80], "lean_deg": [0, 25, 12] } },
+    "flinch": { "sided": false, "needs": ["spine"], "dials": { "seconds": [0.2, 0.8, 0.4], "lean_deg": [5, 30, 20] } },
+    "celebrate": { "sided": false, "needs": ["l_upper", "r_upper"], "dials": { "seconds": [0.8, 3.0, 1.5], "lift_deg": [100, 170, 150], "bounces": [1, 4, 2] } }
+  }
+}