@funpixel/tools 0.0.0-stage → 0.1.0

package/bench/handlers/author_motion.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`author_motion` — new clips on a rigged humanoid, built from a checked spec.
+
+A caller never writes motion code: it sends DATA — a kind from a fixed set and a
+few dials — and code that already shipped builds the clip. Every dial has a
+range the kind was tuned within; a value outside it is REFUSED with the field
+named, never clamped, because a clip that measures fine and looks wrong is worse
+than no clip. The model's own clips are kept; a new name that collides with one
+is refused. Every clip is built on the model's own stance (its idle's first
+frame, `base_clip`), starts and ends there, and keys the whole body.
+
+Kinds (the dials and their ranges are `SPECS` below):
+  wave       one arm up, the forearm swinging side to side
+  nod        the head dipping forward, once or a few times
+  hop        a small jump in place: crouch, lift, land, settle (the hips move)
+  strike     a wind-up, a fast reach forward and a recovery, with the body leaning in
+  flinch     a quick recoil back and a return
+  celebrate  both arms thrown up, the body bouncing
+
+Poses are made in world terms (`humanoid.turn`/`toward`), so the same spec
+reads the same on any humanoid rig the slots are found on. A one-shot starts
+and ends at rest, so it blends from and back to any clip.
+"""
+import json
+import math
+import os
+import re
+
+import bpy
+from mathutils import Matrix
+
+from . import humanoid, scene
+
+# Frames a second the clips are keyed at: the scene's, read when a model is
+# imported, so the model's own clips keep their timing on export.
+FPS = 24
+MAX_MOTIONS = 12
+NAME = re.compile(r"^[a-z][a-z0-9_]{0,31}$")
+
+# kind → dial → (low, high, default), whether it takes a side, and the slots it needs
+# (a rig without one is refused for that kind). One file, `motion_specs.json`, which
+# the Tools API checks a request against at submit too.
+with open(os.path.join(os.path.dirname(os.path.abspath(__file__)), "motion_specs.json")) as _f:
+    _KINDS = json.load(_f)["kinds"]
+SPECS = {k: {d: tuple(r) for d, r in v["dials"].items()} for k, v in _KINDS.items()}
+SIDED = {k for k, v in _KINDS.items() if v["sided"]}
+NEEDS = {k: tuple(v["needs"]) for k, v in _KINDS.items()}
+
+
+def check(i, m):
+    """The spec with its defaults, or a ValueError naming the field."""
+    where = "motions[%d]" % i
+    if not isinstance(m, dict):
+        raise ValueError("%s must be an object" % where)
+    kind = m.get("kind")
+    if kind not in SPECS:
+        raise ValueError("%s.kind must be one of %s" % (where, ", ".join(sorted(SPECS))))
+    allowed = set(SPECS[kind]) | {"kind", "name"} | ({"side"} if kind in SIDED else set())
+    extra = sorted(set(m) - allowed)
+    if extra:
+        raise ValueError("%s.%s is not a %s dial; it takes %s" % (where, extra[0], kind, ", ".join(sorted(allowed - {"kind"}))))
+    out = {"kind": kind, "name": m.get("name") or kind}
+    if not NAME.match(out["name"]):
+        raise ValueError("%s.name must be lowercase letters, digits or _ (1-32)" % where)
+    for dial, (lo, hi, default) in SPECS[kind].items():
+        v = m.get(dial, default)
+        if not isinstance(v, (int, float)) or isinstance(v, bool) or not (lo <= v <= hi):
+            raise ValueError("%s.%s is %r; it must be %s-%s" % (where, dial, v, lo, hi))
+        out[dial] = v
+    if kind in SIDED:
+        side = m.get("side", "right")
+        if side not in ("left", "right"):
+            raise ValueError('%s.side must be "left" or "right"' % where)
+        out["side"] = side
+    return out
+
+
+def _slot(s, spec, part):
+    """`upper`/`fore` resolve to the spec's side."""
+    if part in ("upper", "fore"):
+        return s.get(("l_" if spec.get("side") == "left" else "r_") + part)
+    return s.get(part)
+
+
+# The pose every clip starts from, ends on and is built on: bone name → basis.
+# The first frame of the model's idle when it has one (arms down, weight on
+# both feet), else the rest pose. Every bone is keyed, so a clip played alone
+# holds the whole body in that stance rather than dropping the rest of it to
+# the bind pose (a T-pose).
+BASE = {}
+
+
+class Keyer:
+    """Key a clip pose by pose: each pose starts from the base and keys every bone."""
+
+    def __init__(self, arm, action, bones):
+        self.arm = arm
+        arm.animation_data.action = action
+
+    def pose(self, t, build):
+        for pb in self.arm.pose.bones:
+            pb.rotation_mode = "QUATERNION"
+            pb.matrix_basis = BASE.get(pb.name, Matrix())
+        humanoid.update()
+        build()
+        frame = round(t * FPS)
+        for pb in self.arm.pose.bones:
+            pb.keyframe_insert("rotation_quaternion", frame=frame)
+            pb.keyframe_insert("location", frame=frame)
+
+
+def _base(arm, clip):
+    """The stance to build on: `clip`'s first frame, or the rest pose."""
+    BASE.clear()
+    action = next((a for a in bpy.data.actions if a.name.split("|")[-1] == clip), None) if clip else None
+    if action is None:
+        return None
+    ad = arm.animation_data or arm.animation_data_create()
+    ad.action = action
+    if hasattr(ad, "action_slot") and len(action.slots):
+        ad.action_slot = action.slots[0]
+    bpy.context.scene.frame_set(int(action.frame_range[0]))
+    for pb in arm.pose.bones:
+        BASE[pb.name] = pb.matrix_basis.copy()
+    ad.action = None
+    return action.name
+
+
+def _wave(arm, s, spec, fwd, up, left):
+    upper, fore = _slot(s, spec, "upper"), _slot(s, spec, "fore")
+    out = left if spec["side"] == "left" else -left
+    lift, sw = math.radians(spec["lift_deg"]), math.radians(spec["swing_deg"])
+    k = Keyer(arm, bpy.data.actions.new(spec["name"]), [upper, fore])
+    T, n = spec["seconds"], spec["swings"]
+
+    def raised(side_swing):
+        def build():
+            # Out and up: straight up alone could swing the arm through the body.
+            humanoid.toward(arm, upper, fwd, lift, up + out * 0.6)
+            humanoid.toward(arm, fore, fwd, abs(side_swing), out * (1 if side_swing > 0 else -1))
+        return build
+
+    k.pose(0.0, lambda: None)
+    k.pose(T * 0.2, raised(sw))
+    for i in range(n):
+        k.pose(T * (0.2 + 0.6 * (i + 0.5) / n), raised(-sw if i % 2 == 0 else sw))
+    k.pose(T * 0.8, raised(sw))
+    k.pose(T, lambda: None)
+
+
+def _nod(arm, s, spec, fwd, up, left):
+    head = s["head"]
+    depth = math.radians(spec["depth_deg"])
+    k = Keyer(arm, bpy.data.actions.new(spec["name"]), [head])
+    T, n = spec["seconds"], spec["times"]
+    k.pose(0.0, lambda: None)
+    for i in range(n):
+        k.pose(T * (i + 0.5) / n, lambda: humanoid.toward(arm, head, left, depth, fwd - up * 0.5))
+        k.pose(T * (i + 1) / n, lambda: None)
+
+
+def _hop(arm, s, spec, fwd, up, left):
+    hips = s["hips"]
+    # `height` and `crouch` are shares of the body's height: its meshes' extent
+    # (a bone's tail can point anywhere; a head bone's often runs out past the face).
+    box = scene.world_bounds(scene.mesh_objects())
+    height = (box["max"][2] - box["min"][2]) if box else 1.0
+
+    def lift(share):
+        def build():
+            delta = humanoid.to_arm(arm, up * share * height)
+            hips.matrix = Matrix.Translation(delta) @ hips.matrix
+            humanoid.update()
+        return build
+
+    k = Keyer(arm, bpy.data.actions.new(spec["name"]), [hips])
+    T = spec["seconds"]
+    k.pose(0.0, lambda: None)
+    k.pose(T * 0.2, lift(-spec["crouch"]))
+    k.pose(T * 0.5, lift(spec["height"]))
+    k.pose(T * 0.8, lift(-spec["crouch"]))
+    k.pose(T, lambda: None)
+
+
+def _strike(arm, s, spec, fwd, up, left):
+    upper, spine = _slot(s, spec, "upper"), s["spine"]
+    reach, lean = math.radians(spec["reach_deg"]), math.radians(spec["lean_deg"])
+    T, w = spec["seconds"], spec["windup_share"]
+    k = Keyer(arm, bpy.data.actions.new(spec["name"]), [upper, spine])
+
+    def pose(arm_share, lean_share):
+        def build():
+            if lean_share:
+                humanoid.toward(arm, spine, left, abs(lean) * abs(lean_share), fwd * (1 if lean_share > 0 else -1))
+            humanoid.toward(arm, upper, left, reach * abs(arm_share), (fwd + up * 0.3) * (1 if arm_share > 0 else -1))
+        return build
+
+    k.pose(0.0, lambda: None)
+    k.pose(T * w, pose(-0.5, -0.5))          # wind-up: the arm drawn back, the body back
+    k.pose(T * (w + 0.12), pose(1.0, 1.0))   # the strike: fast, the body leaning in
+    k.pose(T * (w + 0.3), pose(0.8, 0.7))    # follow-through
+    k.pose(T, lambda: None)
+
+
+def _flinch(arm, s, spec, fwd, up, left):
+    spine = s["spine"]
+    lean = math.radians(spec["lean_deg"])
+    k = Keyer(arm, bpy.data.actions.new(spec["name"]), [spine, s.get("head")])
+    T = spec["seconds"]
+    k.pose(0.0, lambda: None)
+    k.pose(T * 0.25, lambda: humanoid.toward(arm, spine, left, lean, -fwd))
+    k.pose(T * 0.55, lambda: humanoid.toward(arm, spine, left, lean * 0.4, -fwd))
+    k.pose(T, lambda: None)
+
+
+def _celebrate(arm, s, spec, fwd, up, left):
+    lu, ru, hips = s["l_upper"], s["r_upper"], s.get("hips")
+    lift = math.radians(spec["lift_deg"])
+    k = Keyer(arm, bpy.data.actions.new(spec["name"]), [lu, ru, hips])
+    T, n = spec["seconds"], spec["bounces"]
+
+    def up_pose(bounce):
+        def build():
+            humanoid.toward(arm, lu, fwd, lift, up + left * 0.6)
+            humanoid.toward(arm, ru, fwd, lift, up - left * 0.6)
+            if hips is not None and bounce:
+                hips.matrix = Matrix.Translation(humanoid.to_arm(arm, up * 0.04)) @ hips.matrix
+                humanoid.update()
+        return build
+
+    k.pose(0.0, lambda: None)
+    for i in range(n):
+        k.pose(T * (0.15 + 0.7 * (2 * i + 1) / (2 * n)), up_pose(True))
+        k.pose(T * (0.15 + 0.7 * (2 * i + 2) / (2 * n)), up_pose(False))
+    k.pose(T, lambda: None)
+
+
+BUILD = {"wave": _wave, "nod": _nod, "hop": _hop, "strike": _strike, "flinch": _flinch, "celebrate": _celebrate}
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    out_path = args.get("out_path") or ""
+    motions = args.get("motions")
+    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(motions, list) or not motions or len(motions) > MAX_MOTIONS:
+        raise ValueError("motions must list 1-%d specs" % MAX_MOTIONS)
+    specs = [check(i, m) for i, m in enumerate(motions)]
+
+    global FPS
+    scene.import_model(path, args.get("format") or "")
+    sc = bpy.context.scene
+    FPS = sc.render.fps / (sc.render.fps_base or 1.0)
+    arm = scene.armature_object()
+    if arm is None:
+        raise ValueError("the model has no armature: author_motion animates a rig, it does not make one")
+    have = {a.name.split("|")[-1] for a in bpy.data.actions}
+    names = [sp["name"] for sp in specs]
+    for i, n in enumerate(names):
+        if n in have or names.index(n) != i:
+            raise ValueError("motions[%d].name %r is already a clip on this model; name it something else" % (i, n))
+    s = humanoid.slots(arm)
+    for i, sp in enumerate(specs):
+        missing = [p for p in NEEDS[sp["kind"]] if _slot(s, sp, p) is None]
+        if missing:
+            raise ValueError("motions[%d]: a %s needs the %s bone(s), which this rig does not name" % (i, sp["kind"], ", ".join(missing)))
+
+    for a in bpy.data.actions:
+        a.use_fake_user = True
+    bpy.context.view_layer.objects.active = arm
+    ad = arm.animation_data or arm.animation_data_create()
+    for t in ad.nla_tracks:
+        t.mute = True
+    base = _base(arm, args.get("base_clip", "idle"))
+    fwd, up, left = humanoid.frame(arm, s)
+    made = []
+    for sp in specs:
+        BUILD[sp["kind"]](arm, s, sp, fwd, up, left)
+        act = bpy.data.actions[sp["name"]]
+        act.use_fake_user = True
+        start, end = (float(x) for x in act.frame_range)
+        made.append({"name": act.name, "kind": sp["kind"], "seconds": (end - start) / FPS, "fcurves": len(act.fcurves)})
+    humanoid.reset([pb for pb in arm.pose.bones])
+    ad.action = None
+
+    bpy.ops.object.select_all(action="SELECT")
+    scene.export_glb(out_path)
+    return {
+        "out_path": out_path,
+        "clips": made,
+        "slots": sorted(s),
+        "built_on": base or "rest pose",
+        "specs": specs,
+        "bytes_after": os.path.getsize(out_path),
+    }

package/bench/handlers/bake_emissive.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`bake_emissive` — make only the bright parts of a texture glow (plan b10).
+
+joydle's `prep_static.py` baked "an emissive mask from V or S·V smoothstep, so
+only neon, lanterns and windows glow" (research 12 §3 #13). A whole material
+set emissive glows everywhere, and a bloom pass then washes the model out —
+their night market also found that an emissive boost of 3.5 "blew out the
+bloom" (§2.1), which is why `strength` is capped on the Rust side.
+
+For each material whose base colour is an image: read the pixels, score each
+one by brightness (`value` = max(R,G,B)) or by coloured brightness
+(`saturation_value` = S·V, which leaves white walls and grey skies dark and
+lights neon), smoothstep the score between `low` and `high`, and write
+base colour × mask as a new emissive image wired into the Principled BSDF. The
+glTF export carries it as `emissiveTexture`, with
+`KHR_materials_emissive_strength` when strength is above 1.
+
+`coverage` — the share of the texture that glows (mask > 0.5) — is reported per
+material, because a threshold that lights 60% of a facade is a mistake a
+caller should see in the numbers before they see it in the game.
+"""
+import os
+
+import bpy
+import numpy as np
+
+from . import scene
+
+MAX_PIXELS = 4096 * 4096
+
+
+def _base_image_node(mat):
+    """(Principled BSDF, the image node feeding its Base Color) or (bsdf, None)."""
+    if not mat.use_nodes:
+        return None, None
+    bsdf = next((n for n in mat.node_tree.nodes if n.type == "BSDF_PRINCIPLED"), None)
+    if bsdf is None:
+        return None, None
+    base = bsdf.inputs.get("Base Color")
+    if base is None or not base.is_linked:
+        return bsdf, None
+    node = base.links[0].from_node
+    # The glTF importer can put a colour-factor mix between the image and the
+    # BSDF; walk back through it to the image.
+    for _ in range(3):
+        if node.type == "TEX_IMAGE":
+            return bsdf, node
+        linked = [i for i in node.inputs if i.is_linked]
+        if not linked:
+            break
+        node = linked[0].links[0].from_node
+    return bsdf, None
+
+
+def _mask(rgb, metric, low, high):
+    v = rgb.max(axis=1)
+    if metric == "saturation_value":
+        mn = rgb.min(axis=1)
+        s = np.where(v > 1e-6, (v - mn) / np.maximum(v, 1e-6), 0.0)
+        score = s * v
+    else:
+        score = v
+    t = np.clip((score - low) / max(high - low, 1e-6), 0.0, 1.0)
+    return t * t * (3.0 - 2.0 * t)
+
+
+def _bake(mat, bsdf, src, metric, low, high, strength):
+    img = src.image
+    w, h = img.size
+    px = np.empty(w * h * 4, dtype=np.float32)
+    img.pixels.foreach_get(px)
+    px = px.reshape(-1, 4)
+    mask = _mask(px[:, :3], metric, low, high)
+    out = np.empty_like(px)
+    out[:, :3] = px[:, :3] * mask[:, None]
+    out[:, 3] = 1.0
+
+    emissive = bpy.data.images.new(img.name + "_emissive", w, h, alpha=False)
+    emissive.colorspace_settings.name = img.colorspace_settings.name
+    emissive.pixels.foreach_set(out.ravel())
+    emissive.pack()
+
+    node = mat.node_tree.nodes.new("ShaderNodeTexImage")
+    node.image = emissive
+    # Same UVs as the base colour: link whatever feeds its Vector input.
+    vec = src.inputs.get("Vector")
+    if vec is not None and vec.is_linked:
+        mat.node_tree.links.new(vec.links[0].from_socket, node.inputs["Vector"])
+    mat.node_tree.links.new(node.outputs["Color"], bsdf.inputs["Emission Color"])
+    bsdf.inputs["Emission Strength"].default_value = strength
+    return float((mask > 0.5).mean()), w, h
+
+
+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")
+    metric = args.get("metric") or "saturation_value"
+    if metric not in ("value", "saturation_value"):
+        raise ValueError("metric must be 'value' or 'saturation_value'")
+    low, high = float(args["low"]), float(args["high"])
+    strength = float(args["strength"])
+    if not (0.0 <= low < high <= 1.0) or not (0.0 < strength <= 4.0):
+        raise ValueError("need 0 <= low < high <= 1 and 0 < strength <= 4")
+
+    scene.import_model(path, args.get("format") or "")
+    if not scene.mesh_objects():
+        raise ValueError("the file imported but contains no mesh")
+
+    baked, skipped = [], []
+    for mat in list(bpy.data.materials):
+        bsdf, src = _base_image_node(mat)
+        if bsdf is None:
+            skipped.append({"name": mat.name, "reason": "no Principled BSDF"})
+        elif src is None or src.image is None or src.image.size[0] == 0:
+            skipped.append({"name": mat.name, "reason": "no base-colour texture"})
+        elif src.image.size[0] * src.image.size[1] > MAX_PIXELS:
+            skipped.append({"name": mat.name, "reason": "texture larger than 4096²"})
+        else:
+            coverage, w, h = _bake(mat, bsdf, src, metric, low, high, strength)
+            baked.append({"name": mat.name, "coverage": coverage, "width": w, "height": h})
+    if not baked:
+        raise ValueError(
+            "no material has a base-colour texture to bake from (%d skipped)" % len(skipped)
+        )
+
+    scene.export_glb(out_path)
+    return {
+        "out_path": out_path,
+        "materials": baked,
+        "skipped": skipped,
+        "external_images_dropped": scene.EXTERNAL_IMAGES_DROPPED,
+    }