@funpixel/tools 0.0.0-stage → 0.1.1

package/bench/handlers/render.py

@@ -0,0 +1,239 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`render_turntable` — photograph a model so the author can SEE it.
+
+THE FEEDBACK LOOP, and the reason it ships with the first repair verb rather
+than after. `inspect_game`'s module doc records the failure this prevents, one
+layer up: the model "made 10 file writes and edits and saw the running game
+ZERO times … That is not a missing check; it is a missing FEEDBACK LOOP, and no
+amount of advice given in advance substitutes for one."
+
+A rig is exactly the same shape. `unweighted_fraction` says how much of the mesh
+is bound; it cannot say the character is lying on its side, inside out, or
+invisible. Numbers and a picture answer different questions, and the repair
+verbs are not trustworthy without both.
+
+MEASURED (Blender 4.5.3 LTS, `-b`, 2026-09-16): `BLENDER_EEVEE_NEXT` is the ONLY
+engine registered headless on this build — `BLENDER_EEVEE` and
+`BLENDER_WORKBENCH` are absent from the enum entirely, so the obvious "fall back
+to Workbench when EEVEE needs a GPU" is code that could never run. EEVEE Next
+renders offscreen without a display. Verified, not assumed; re-probe with
+`tests/fixtures/engine_probe.py` if a Blender upgrade changes the set. Blender 5
+renamed it back to `BLENDER_EEVEE`, so the engine comes from
+`scene.render_engine()`, which picks from what this bpy offers.
+"""
+import math
+import os
+
+import bpy
+import numpy as np
+from mathutils import Vector
+
+from . import scene
+
+# A proof sheet, not a beauty render. Small and few: this is looked at by a model
+# and a reviewer, and every extra frame is wall-clock on a path that already
+# costs a process spawn.
+DEFAULT_FRAMES = 4
+MAX_FRAMES = 12
+DEFAULT_SIZE = 512
+MAX_SIZE = 1024
+
+# The contact sheet (plan b4): four across, each cell at most this many pixels,
+# so twelve 1024 px frames make a 1024x768 sheet rather than a 4096x3072 one.
+SHEET_COLUMNS = 4
+SHEET_CELL_MAX = 256
+
+
+def _clear_lights_and_cameras():
+    for obj in list(bpy.data.objects):
+        if obj.type in {"LIGHT", "CAMERA"}:
+            bpy.data.objects.remove(obj, do_unlink=True)
+
+
+def _neutral_stage():
+    """Three-point-ish lighting on a mid-grey world.
+
+    Neutral on purpose. A dramatic key light flatters a bad mesh and hides the
+    thing we are looking for — a limb on backwards, a face with no material. The
+    stage must not have opinions.
+    """
+    world = bpy.data.worlds.new("Stage")
+    world.use_nodes = True
+    bg = world.node_tree.nodes.get("Background")
+    if bg is not None:
+        bg.inputs["Color"].default_value = (0.18, 0.18, 0.19, 1.0)
+        bg.inputs["Strength"].default_value = 1.0
+    bpy.context.scene.world = world
+
+    for name, loc, energy in (
+        ("Key", (4.0, -4.0, 5.0), 900.0),
+        ("Fill", (-5.0, -2.0, 2.0), 300.0),
+        ("Rim", (0.0, 5.0, 4.0), 500.0),
+    ):
+        light = bpy.data.lights.new(name, type="AREA")
+        light.energy = energy
+        light.size = 6.0
+        obj = bpy.data.objects.new(name, light)
+        obj.location = loc
+        # Point each lamp at the origin; the model is centred there below.
+        direction = Vector((0.0, 0.0, 1.0)) - Vector(loc)
+        obj.rotation_euler = direction.to_track_quat("-Z", "Y").to_euler()
+        bpy.context.collection.objects.link(obj)
+
+
+def _frame_subject(meshes):
+    """Centre the subject on the origin and return the radius to frame it.
+
+    Bounds come from the WORLD box of every mesh. For a skinned mesh this is the
+    rest pose, which is what we want: the turntable proves the asset, not one
+    frame of an animation.
+    """
+    bounds = scene.world_bounds(meshes)
+    if bounds is None:
+        raise ValueError("nothing to render")
+    lo = Vector(bounds["min"])
+    hi = Vector(bounds["max"])
+    centre = (lo + hi) / 2.0
+    size = hi - lo
+
+    # Move every root object so the subject sits on the origin. Roots only —
+    # moving a parented mesh as well would double the translation.
+    for obj in bpy.data.objects:
+        if obj.parent is None and obj.type in {"MESH", "ARMATURE", "EMPTY"}:
+            obj.location -= centre
+
+    radius = max(size.x, size.y, size.z)
+    # A degenerate or single-point model would put the camera inside itself.
+    return max(radius, 1e-3), size
+
+
+def _add_camera():
+    cam_data = bpy.data.cameras.new("Turntable")
+    cam_data.lens = 50.0
+    cam = bpy.data.objects.new("Turntable", cam_data)
+    bpy.context.collection.objects.link(cam)
+    bpy.context.scene.camera = cam
+    return cam
+
+
+def _place(cam, angle_rad, radius, elevation=0.28):
+    """Orbit at a fixed elevation, always looking at the origin.
+
+    Distance is derived from the subject's own size, so a 0.2 m prop and a 2 m
+    character both fill the frame. A fixed distance would render one as a speck
+    and clip the other.
+    """
+    dist = radius * 2.6
+    cam.location = (
+        math.sin(angle_rad) * dist,
+        -math.cos(angle_rad) * dist,
+        radius * elevation + radius * 0.55,
+    )
+    direction = Vector((0.0, 0.0, 0.0)) - cam.location
+    cam.rotation_euler = direction.to_track_quat("-Z", "Y").to_euler()
+
+
+def _configure_render(size):
+    sc = bpy.context.scene
+    sc.render.engine = scene.render_engine()
+    sc.render.resolution_x = size
+    sc.render.resolution_y = size
+    sc.render.resolution_percentage = 100
+    sc.render.image_settings.file_format = "PNG"
+    # Alpha OFF: a transparent background makes an invisible model look exactly
+    # like a correct one with nothing behind it, which is the failure this verb
+    # exists to reveal. The grey world must be visible.
+    sc.render.film_transparent = False
+
+
+def _contact_sheet(paths, cell, out):
+    """Every orbit frame on one PNG, in orbit order, left to right then down.
+
+    Blender's pixel rows run bottom-up, so the first row of the sheet is written
+    at the TOP of the buffer. The frames are byte PNGs and the sheet is one too:
+    the values are copied, never colour-managed twice.
+    """
+    columns = min(len(paths), SHEET_COLUMNS)
+    rows = (len(paths) + columns - 1) // columns
+    width, height = columns * cell, rows * cell
+    sheet = np.zeros((height, width, 4), dtype=np.float32)
+    sheet[..., 3] = 1.0
+    for i, path in enumerate(paths):
+        img = bpy.data.images.load(path)
+        img.scale(cell, cell)
+        px = np.empty(cell * cell * 4, dtype=np.float32)
+        img.pixels.foreach_get(px)
+        bpy.data.images.remove(img)
+        row, col = divmod(i, columns)
+        y0 = (rows - 1 - row) * cell
+        sheet[y0 : y0 + cell, col * cell : (col + 1) * cell] = px.reshape(cell, cell, 4)
+    out_img = bpy.data.images.new("ContactSheet", width, height, alpha=False)
+    out_img.pixels.foreach_set(sheet.ravel())
+    out_img.filepath_raw = out
+    out_img.file_format = "PNG"
+    out_img.save()
+    if not os.path.exists(out):
+        raise RuntimeError("the contact sheet was not written")
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    if not path or not os.path.isfile(path):
+        raise ValueError("model_path does not exist")
+
+    out_dir = args.get("out_dir") or ""
+    if not out_dir or not os.path.isdir(out_dir):
+        raise ValueError("out_dir does not exist")
+
+    frames = scene.clamp_int(args.get("frames"), DEFAULT_FRAMES, 1, MAX_FRAMES)
+    size = scene.clamp_int(args.get("size"), DEFAULT_SIZE, 64, MAX_SIZE)
+
+    scene.import_model(path, args.get("format") or "")
+    meshes = scene.mesh_objects()
+    if not meshes:
+        raise ValueError("the file imported but contains no mesh")
+    # The importer leaves a rigged model playing one of its clips; the turntable
+    # proves the asset, so it is shown in its rest pose, not mid-attack.
+    for arm in (o for o in bpy.data.objects if o.type == "ARMATURE"):
+        if arm.animation_data is not None:
+            arm.animation_data.action = None
+            for track in arm.animation_data.nla_tracks:
+                track.mute = True
+        for pb in arm.pose.bones:
+            pb.matrix_basis.identity()
+
+    _clear_lights_and_cameras()
+    _neutral_stage()
+    radius, extent = _frame_subject(meshes)
+    cam = _add_camera()
+    _configure_render(size)
+
+    written = []
+    for i in range(frames):
+        angle = (2.0 * math.pi * i) / frames
+        _place(cam, angle, radius)
+        out = os.path.join(out_dir, "turn_%02d.png" % i)
+        bpy.context.scene.render.filepath = out
+        bpy.ops.render.render(write_still=True)
+        if not os.path.exists(out):
+            raise RuntimeError("render produced no file for frame %d" % i)
+        written.append({"path": out, "angle_deg": round(math.degrees(angle), 2)})
+
+    # A front elevation, straight on. The one view a human reads fastest for
+    # "is this the right way up and does it look like the thing it claims".
+    _place(cam, 0.0, radius, elevation=0.0)
+    front = os.path.join(out_dir, "front.png")
+    bpy.context.scene.render.filepath = front
+    bpy.ops.render.render(write_still=True)
+
+    sheet = os.path.join(out_dir, "contact_sheet.png")
+    _contact_sheet([f["path"] for f in written], min(size, SHEET_CELL_MAX), sheet)
+
+    return {
+        "frames": written,
+        "front": front,
+        "contact_sheet": sheet,
+        "engine": bpy.context.scene.render.engine,
+        "size": size,
+        "subject_extent": [extent.x, extent.y, extent.z],
+    }

package/bench/handlers/render_views.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`render_views` — a model from a fixed set of views, with a lettered grid
+(plan g3). Read-only.
+
+`skin`: front, back, left, right, then the face and each hand close up — the
+regions where skin reads or fails to. `retexture`: the four sides, the
+pictures a new look is painted over. Each view is the model's own base
+colour under a soft headlight on a magenta key, drawn by `raster` so each
+pixel is a known point of the mesh; each comes twice, plain and gridded.
+
+`fidelity`: 48 orthographic views of the model squared to its principal axes
+(8 yaws x 3 heights x 2 orientations, `views.fidelity_cameras`), its flat base
+colour on a transparent ground and no grid — what `funtools fidelity` scores
+reference views against.
+"""
+import os
+
+import numpy as np
+
+from . import scene, sheet, texels, views
+
+
+def prepare(args, before_arrays=None):
+    """Import the model and compute its arrays, slots and view cameras.
+    `before_arrays` runs after the import (apply_texture unwraps UVs there)."""
+    path = args.get("model_path") or ""
+    if not path or not os.path.isfile(path):
+        raise ValueError("model_path does not exist")
+    scene.import_model(path, args.get("format") or "")
+    meshes = scene.mesh_objects()
+    if not meshes:
+        raise ValueError("the file imported but contains no mesh")
+    if before_arrays is not None:
+        before_arrays()
+    model = views.Model(meshes)
+    if len(model.tris) > 150_000:
+        raise ValueError("%d triangles: decimate to 150,000 or fewer first (optimize_model)"
+                         % len(model.tris))
+    if model.height <= 1e-4:
+        raise ValueError("the model has no height to frame")
+    cams, located_by = views.cameras(model, args.get("view_set") or "", scene.armature_object())
+    all_slots = texels.slots(model)
+    return model, cams, located_by, all_slots, texels.slot_lookup(model, all_slots)
+
+
+# Workbench's object outline colour in the owner's fidelity renders (FID_OUTLINE).
+INK = np.array([0.07, 0.06, 0.05], dtype=np.float32)
+
+
+def _ink(model, tri, zbuf, size, rgb, alpha):
+    """The ink look (FID_OUTLINE, Workbench's object outline): a one-pixel line where
+    one object meets another or nothing, drawn on the FARTHER side — outside the silhouette,
+    and behind a nearer object."""
+    owner = np.where(tri >= 0, model.owner[np.maximum(tri, 0)], -1).reshape(size, size)
+    depth = np.where(tri >= 0, zbuf, np.inf).reshape(size, size)
+    line = np.zeros((size, size), dtype=bool)
+    for dy, dx in ((0, 1), (0, -1), (1, 0), (-1, 0)):
+        o = np.roll(owner, (dy, dx), axis=(0, 1))
+        d = np.roll(depth, (dy, dx), axis=(0, 1))
+        line |= (o != owner) & (o >= 0) & (d < depth)
+    line[[0, -1], :] = False
+    line[:, [0, -1]] = False
+    rgb = rgb.copy()
+    rgb[line] = INK
+    alpha = alpha.copy()
+    alpha[line] = 1.0
+    return rgb, alpha
+
+
+def run(args):
+    out_dir = args.get("out_dir") or ""
+    if not out_dir or not os.path.isdir(out_dir):
+        raise ValueError("out_dir does not exist")
+    fidelity = args.get("view_set") == "fidelity"
+    size = scene.clamp_int(args.get("size"), views.FIDELITY_SIZE if fidelity else 768, 256, 1024)
+    model, cams, located_by, _, lookup = prepare(args)
+    if fidelity:
+        align = args.get("align", True) is not False
+        cams = views.fidelity_cameras(model, align=align, roll=bool(args.get("roll")))
+        located_by = "axes" if align else "own"
+    outline = fidelity and bool(args.get("outline"))
+    out = []
+    for cam in cams:
+        zbuf, tri, bary = views.depth_view(model, cam, size)
+        if fidelity:
+            rgb, coverage = texels.shade_view(model, cam, size, lookup, zbuf, tri, bary, lit=False)
+            alpha = (tri >= 0).reshape(size, size).astype(np.float32)
+            if outline:
+                rgb, alpha = _ink(model, tri, zbuf, size, rgb, alpha)
+            plain = os.path.join(out_dir, "%s.png" % cam["name"])
+            sheet.write_png(rgb, plain, alpha=alpha)
+            out.append({"name": cam["name"], "png": plain, "grid_png": "", "coverage": coverage,
+                        "yaw": cam["yaw"], "elevation": cam["elevation"], "flipped": cam["flipped"]})
+            continue
+        rgb, coverage = texels.shade_view(model, cam, size, lookup, zbuf, tri, bary)
+        plain = os.path.join(out_dir, "view_%s.png" % cam["name"])
+        gridded = os.path.join(out_dir, "grid_%s.png" % cam["name"])
+        sheet.write_png(rgb, plain)
+        sheet.write_png(sheet.grid(rgb, views.GRID), gridded)
+        out.append({"name": cam["name"], "png": plain, "grid_png": gridded, "coverage": coverage})
+    return {"views": out, "grid": views.GRID, "located_by": located_by, "size": size}

package/bench/handlers/retarget_clips.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`retarget_clips` — play another character's clips on this character's rig.
+
+A donor model carries clips; the target is a rigged humanoid without them (or
+with others). Bones are matched by name under the common conventions
+(`humanoid.normalise`: `mixamorig:LeftArm`, `LeftArm` and `left_arm` are one
+bone), so two rigs from the same rig run — every 3D library character — match
+bone for bone, and a mapped rig from elsewhere matches where the names agree.
+
+Each frame is carried over as MOTION, not as numbers: for every matched bone the
+donor's turn away from its own rest pose, in world terms, is applied to the
+target bone's rest pose. Bone rolls and rest poses may differ; the motion still
+reads the same. The hips' travel is scaled by the ratio of the two rigs' hip
+heights, so a short character's walk takes short steps. A target bone with no
+match holds its rest pose relative to its parent.
+
+Refused: no armature on either side; fewer than half the target's limbs
+matched (it is a different kind of body); a clip name the target already has.
+The caller is told which bones matched and which did not.
+
+Feet are NOT locked: a rig with other proportions can slide. Run `audit_clips`
+on the result — its `foot_slide_m` is the honest number.
+"""
+import os
+import re
+
+import bpy
+from mathutils import Quaternion, Vector
+
+from . import humanoid, scene
+
+NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_]{0,31}$")
+LIMBS = ("hips", "spine", "head", "l_upper", "r_upper", "l_fore", "r_fore", "l_thigh", "r_thigh", "l_shin", "r_shin")
+
+
+def _bare(name):
+    """`Armature|Walk` → `Walk`; Blender's `.001` for a second import of a name, dropped."""
+    return re.sub(r"\.\d{3}$", "", name.split("|")[-1])
+
+
+def _order(arm):
+    """Pose bones parents first."""
+    out, seen = [], set()
+
+    def visit(pb):
+        if pb.name in seen:
+            return
+        if pb.parent is not None:
+            visit(pb.parent)
+        seen.add(pb.name)
+        out.append(pb)
+
+    for pb in arm.pose.bones:
+        visit(pb)
+    return out
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    donor_path = args.get("donor_path") or ""
+    out_path = args.get("out_path") or ""
+    wanted = args.get("clips") or []
+    for p, what in ((path, "model_path"), (donor_path, "donor_path")):
+        if not p or not os.path.isfile(p):
+            raise ValueError("%s does not exist" % what)
+    if not out_path:
+        raise ValueError("out_path is required — this verb writes a new model")
+    if not isinstance(wanted, list) or any(not isinstance(c, str) or not NAME.match(c) for c in wanted):
+        raise ValueError("clips must be clip names (letters, digits, _)")
+
+    scene.import_model(path, args.get("format") or "")
+    target = scene.armature_object()
+    if target is None:
+        raise ValueError("the model has no armature: rig it first (rig_model)")
+    keep = set(bpy.data.objects)
+    own = {_bare(a.name) for a in bpy.data.actions}
+    for a in bpy.data.actions:
+        a.use_fake_user = True
+    before = set(bpy.data.actions)
+    scene.import_into_current(donor_path, "")
+    donor = next((o for o in bpy.data.objects if o.type == "ARMATURE" and o not in keep), None)
+    if donor is None:
+        raise ValueError("the donor has no armature: there is nothing to carry over")
+    clips = [a for a in bpy.data.actions if a not in before]
+    if wanted:
+        by = {_bare(a.name): a for a in clips}
+        missing = [c for c in wanted if c not in by]
+        if missing:
+            raise ValueError("the donor has no clip %s; it has %s" % (", ".join(missing), ", ".join(sorted(by))))
+        clips = [by[c] for c in wanted]
+    if not clips:
+        raise ValueError("the donor carries no clips")
+    taken = [_bare(a.name) for a in clips if _bare(a.name) in own]
+    if taken:
+        raise ValueError("the model already has clip(s) %s; drop them from `clips`" % ", ".join(taken))
+
+    donor_by = {humanoid.normalise(pb.name): pb for pb in donor.pose.bones}
+    pairs = {pb.name: donor_by.get(humanoid.normalise(pb.name)) for pb in target.pose.bones}
+    ts, ds = humanoid.slots(target), humanoid.slots(donor)
+    limbs = [s for s in LIMBS if s in ts]
+    matched_limbs = [s for s in limbs if s in ds and getattr(pairs.get(ts[s].name), "name", None) == ds[s].name]
+    if len(limbs) < 4 or len(matched_limbs) * 2 < len(limbs):
+        raise ValueError(
+            "only %d of the model's %d limbs have a bone of the same name on the donor (%s): "
+            "it is not the same kind of body" % (len(matched_limbs), len(limbs), ", ".join(matched_limbs) or "none")
+        )
+
+    wt, wd = target.matrix_world.to_quaternion(), donor.matrix_world.to_quaternion()
+    rest_t = {pb.name: pb.bone.matrix_local.to_quaternion() for pb in target.pose.bones}
+    rest_d = {pb.name: pb.bone.matrix_local.to_quaternion() for pb in donor.pose.bones}
+    hips_t, hips_d = ts.get("hips"), ds.get("hips")
+    scale = 1.0
+    if hips_t is not None and hips_d is not None:
+        ht = (target.matrix_world @ hips_t.bone.head_local).z
+        hd = (donor.matrix_world @ hips_d.bone.head_local).z
+        scale = ht / hd if hd > 1e-6 else 1.0
+    # World back into the target's armature space, scale included (an imported
+    # rig often sits under a 0.01 object scale).
+    to_target = target.matrix_world.to_3x3().inverted()
+    order = _order(target)
+    sc = bpy.context.scene
+    tad = target.animation_data or target.animation_data_create()
+    dad = donor.animation_data or donor.animation_data_create()
+    for t in list(dad.nla_tracks) + list(tad.nla_tracks):
+        t.mute = True
+
+    made = []
+    for clip in clips:
+        dad.action = clip
+        if hasattr(dad, "action_slot") and len(clip.slots):
+            dad.action_slot = clip.slots[0]
+        name = _bare(clip.name)
+        clip.name = "__donor_" + name  # frees the bare name for the result
+        out = bpy.data.actions.new(name)
+        out.use_fake_user = True
+        tad.action = out
+        start, end = (int(round(x)) for x in clip.frame_range)
+        for f in range(start, end + 1):
+            sc.frame_set(f)
+            pose = {}
+            for pb in order:
+                src = pairs.get(pb.name)
+                parent = pb.parent
+                if src is not None:
+                    delta = wd @ src.matrix.to_quaternion() @ rest_d[src.name].inverted() @ wd.inverted()
+                    pose[pb.name] = wt.inverted() @ delta @ wt @ rest_t[pb.name]
+                elif parent is not None:
+                    pose[pb.name] = pose[parent.name] @ rest_t[parent.name].inverted() @ rest_t[pb.name]
+                else:
+                    pose[pb.name] = rest_t[pb.name]
+                local = rest_t[pb.name] if parent is None else rest_t[parent.name].inverted() @ rest_t[pb.name]
+                parent_pose = Quaternion() if parent is None else pose[parent.name]
+                pb.rotation_mode = "QUATERNION"
+                pb.rotation_quaternion = local.inverted() @ parent_pose.inverted() @ pose[pb.name]
+                pb.keyframe_insert("rotation_quaternion", frame=f)
+            if hips_t is not None and hips_d is not None and hips_t.parent is None:
+                moved = donor.matrix_world.to_3x3() @ (hips_d.matrix.to_translation() - hips_d.bone.head_local)
+                local = rest_t[hips_t.name].inverted() @ (to_target @ (moved * scale))
+                hips_t.location = Vector(local)
+                hips_t.keyframe_insert("location", frame=f)
+        made.append({"name": out.name, "frames": end - start + 1})
+
+    # The donor, its clips and its meshes are not part of the result.
+    for a in [a for a in bpy.data.actions if a not in before and a.name not in {m["name"] for m in made}]:
+        bpy.data.actions.remove(a)
+    for o in [o for o in bpy.data.objects if o not in keep]:
+        bpy.data.objects.remove(o, do_unlink=True)
+    bpy.data.orphans_purge(do_local_ids=True, do_linked_ids=True, do_recursive=True)
+    tad.action = None
+    for pb in target.pose.bones:
+        pb.rotation_quaternion = Quaternion()
+        pb.location = Vector()
+
+    bpy.ops.object.select_all(action="SELECT")
+    scene.export_glb(out_path)
+    unmatched = sorted(n for n, d in pairs.items() if d is None)
+    return {
+        "out_path": out_path,
+        "clips": made,
+        "limbs_matched": matched_limbs,
+        "bones_matched": sum(1 for d in pairs.values() if d is not None),
+        "bones_unmatched": unmatched[:32],
+        "hip_scale": scale,
+        "bytes_after": os.path.getsize(out_path),
+    }