Subagent: Model export and lens shot

agent
Claude Code subagent (model-lens)
model
claude-opus-5-5
harness
Claude Code
started
2026-11-10 11:09 UTC
took
63 min · 142 turns

user

+0:00
<teammate-message teammate_id="team-lead" summary="Model export and lens shot"> You are helping finish one character ("Wren") in the lowmarch repo, a code-built anime character pipeline whose target renderer is a painted three.js page. Work ONLY in the git worktree `~/Projects/lowmarch-fable52` (branch `fable52`). Your job has two parts: (A) a script that exports the built character as a standalone, rigged 3D model file that an ordinary perspective-camera renderer can load; (B) a script that shoots one perspective picture of her through the project's existing "Flattice" lens patch, to show the model is camera-ready.

Hard rules

  • Edit files only under ~/Projects/lowmarch-fable52. Create only new files under tools/whole/ (suggested: export_model.py, lens_shot.py, patch_lens_flattice.py as a copy) and scratch output under review/out/whole-lens/ (git-ignored). Do NOT edit tools/whole/build.py, tools/whole/shoot.py or any existing repo file; if you need a change there, say so in your report. Do not commit.
  • [redacted: private path]/ is read-only data: copy from it, never write or edit in place. Never run tools/cage.py. Never touch [redacted: private path] or any other repo.
  • Headless only: no windows on the desktop. Browser work via headless Chromium only (/snap/bin/chromium --headless=new --use-angle=swiftshader --enable-unsafe-swiftshader --ignore-gpu-blocklist ..., as tools/whole/shoot.py does; note snap Chromium cannot read or write under /tmp or hidden dirs, so keep its files under the worktree). Playwright is at [redacted: private path] if you need it; keep page-side code as plain .js evaluated as text. Blender only with -b (you probably don't need it). No Windows programs, nothing under /mnt/c, no installs, no full test suite, no ssh, no network uploads, never push. Don't contact other sessions; don't use led, cw, tracker.
  • The Yin/Yang rigs and FE8 references in the data dir are off limits: don't open them, don't show them.
  • Run python with OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1, python3 without -I.

Context

  • Read first: tools/whole/build.py and tools/whole/shoot.py (short; they build the character "wren" plus an enemy soldier into a site folder and shoot composed frames from a patched scratch copy of the painted page), tools/export_glb.py (export_skinned writes the skinned GLB with skeleton and animation clips; scene_info writes what the painted page needs per material role), review/vroid-02/build.py character() and wrap_json (the site stores each model as <name>.glb.json = {"glb": base64}), and how review/vroid-02/index.html loads a character and assigns its shader materials (search loadCharacter, KIND, scene_info roles). Also read docs/map.md and the "Research: the flat lattice" section and "Flattice in the armory renderer" paragraphs of [redacted: private path].
  • A built test site for you exists: review/out/whole-lens/site (wren.glb.json, mob_soldier.glb.json, plains.glb.json, camera.json, index.html). The character's costume and clips will change later today; your scripts will be re-run on the final build by path, so take the site dir and character name as arguments and hard-code nothing about today's costume (material names, piece counts).
  • Shoot the existing painted page with: WHOLE_SITE=review/out/whole-lens/site python3 tools/whole/shoot.py tools/whole/frame.json OUT.png (7 s). You may import helpers from tools/whole/shoot.py in your own script, or copy what you need.

Part A: tools/whole/export_model.py SITE_DIR NAME OUT.glb

  • Produce one standalone binary .glb of the character from the site's <name>.glb.json, valid glTF 2.0, that loads in a stock loader (three.js GLTFLoader, Blender's importer) with no knowledge of this project: skinned meshes, the skeleton, the animation clips, and sensible standard materials. Find out what export_skinned already writes for materials and textures. Where a material would load blank or wrong in a stock viewer, set standard glTF material fields from what the site knows (camera.json -> the character's info.roles, palette colours, the embedded face/hair/eye textures): baseColorFactor or baseColorTexture, doubleSided where hair or cloth needs it, alpha mode for lashes and other cut-outs, low metallic except steel and gold. Keep the project's own data too (role names and palette ramps in extras), so the painted shader can be rebuilt on top later.
  • Check node names, scale (metres), up axis (+Y) and facing, and note them. Humanoid bone names are VRoid's (J_Bip_C_Hips...).
  • Validate, headless: (1) parse the GLB yourself and report counts (meshes, primitives, triangles, materials, textures, joints, animations with names and durations, file size); (2) load it with three.js GLTFLoader in headless Chromium under a PerspectiveCamera with the file's own standard materials and a simple light (not the project's painted shader), play one clip to a mid frame, and save a screenshot review/out/whole-lens/model_check.png. three.js is loaded from https://cdn.jsdelivr.net/npm/three@0.160.0/ in the project's pages; use the same. Look at the screenshot with the Read tool and fix what is visibly broken (missing pieces, black or white materials, inside-out faces, exploded skinning).
  • If Blender 5.2 ([redacted: private path] -b) imports the file without error in a quick --python-expr check, say so; skip it if it takes more than a few minutes.
  • Decide and say whether GLB or VRM is the better fit; I expect GLB (VRM would need the humanoid/meta extensions and MToon to be worth it), but check whether the source body's VRM humanoid mapping could be carried over cheaply as an extras block.

Part B: tools/whole/lens_shot.py SITE_DIR SPEC.json OUT.png

  • Copy [redacted: private path]/trials/face-shading-2026-10-30/scripts/patch_lens_flattice.py into tools/whole/ (keep its docstring, add one line saying where it was copied from and what you changed). It patches a scratch copy of a built page so tiles can take a perspective lens (mm on a 36 mm frame) and flat (Flattice, 0..1; 0.85 is the tested value; whole-figure flattening was the recommended start for scenes). It was written against the armory build of the same index.html; make it apply to this site (the patch targets may need small adjustments; tools/whole/shoot.py applies its own string patches to the same page, and yours must compose with those since the shot needs the duel sheet's tiles, per-fighter clips, placement and sky from shoot.py).
  • Produce one perspective shot of her in the painted renderer through that lens: the same battle moment as tools/whole/frame.json, as a three-quarter medium shot (roughly knees up, camera at chest height, 35 to 50 mm), 1920x1080, with Flattice on. Also make the same shot with flat: 0 so the two can be compared, as review/out/whole-lens/lens_flat.png and lens_noflat.png. Look at both with the Read tool; report honestly what the lens and the squash do and what breaks (outlines under perspective, z-fighting on the head at high flatten, the ground, the cast chin shadow, which assumes an orthographic walk).
  • The spec format should extend shoot.py's (same keys, plus lens, flat, camera distance or framing). Document it in the docstring.

Deliver

The new files, the check pictures, and a report: what is in the model file and what is not (the painted look lives in the page's shader, not in the file; say exactly what a renderer gets), counts and size, axis and scale, what you changed in the lens patch, what the perspective shots show and what is broken, wall time per step (reading, export, validation, lens patch, shots), and any change you need in build.py or shoot.py. Write code and comments in the repo's terse style, no em dashes. </teammate-message>

agent

+0:03
  • Bashdate +%s && wc -l tools/whole/build.py tools/whole/shoot.py tools/export_glb.py review/vroid-02/build.py review/vroid-02/index.html docs/map.md && ls tools/whole review/out/whole-lens/site && ls -la review/out/whole-lens/site && cat tools/whole/frame.json

    command

    date +%s && wc -l tools/whole/build.py tools/whole/shoot.py tools/export_glb.py review/vroid-02/build.py review/vroid-02/index.html docs/map.md && ls tools/whole review/out/whole-lens/site && ls -la review/out/whole-lens/site && cat tools/whole/frame.json

    result, 84 lines

    1794308981
       137 tools/whole/build.py
       108 tools/whole/shoot.py
       567 tools/export_glb.py
       391 review/vroid-02/build.py
      1737 review/vroid-02/index.html
        69 docs/map.md
      3009 total
    review/out/whole-lens/site:
    camera.json
    checks.json
    index.html
    mob_soldier.glb.json
    plains.glb.json
    wren.glb.json
    
    tools/whole:
    build.py
    frame.json
    notes
    __pycache__
    shoot.py
    total 11304
    drwx------ 2 severian severian    4096 Nov 10 19:08 .
    drwx------ 3 severian severian    4096 Nov 10 19:08 ..
    -rw------- 1 severian severian   33818 Nov 10 19:08 camera.json
    -rw------- 1 severian severian    2829 Nov 10 19:08 checks.json
    -rw------- 1 severian severian  111378 Nov 10 19:08 index.html
    -rw------- 1 severian severian 5148099 Nov 10 19:08 mob_soldier.glb.json
    -rw------- 1 severian severian  333939 Nov 10 19:08 plains.glb.json
    -rw------- 1 severian severian 5926727 Nov 10 19:08 wren.glb.json
    {
     "w": 1920,
     "h": 1080,
     "scale": 2,
     "size": 2.3,
     "pitch": 7,
     "yaw": 0,
     "centre": [
      -0.07,
      1.02,
      0
     ],
     "place": {
      "wren": {
       "pos": [
        -0.9,
        0,
        0
       ],
       "yaw": 62
      },
      "mob_soldier": {
       "pos": [
        1.3,
        0,
        0
       ],
       "yaw": -70
      }
     },
     "clips": {
      "wren": [
       "attack",
       0.4
      ],
      "mob_soldier": [
       "idle",
       0.0
      ]
     },
     "key": {
      "wren": [
       0.85,
       0.42,
       0.3
      ]
     },
     "sky": [
      "#8fb4d6",
      "#c9dde6",
      "#eef0e2"
     ]
    }
  • Bashcat tools/whole/build.py tools/whole/shoot.py && cat docs/map.md && ls tools/whole/notes

    command

    cat tools/whole/build.py tools/whole/shoot.py && cat docs/map.md && ls tools/whole/notes

    result, 314 lines

    """One whole character on a current armory body: dressed by the old costume kit, rigged with the battle clips,
    built into a painted-renderer site of its own.
    
      OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 python3 tools/whole/build.py [BODY [NAME...]]
          -> review/out/whole/site/ (git-ignored). BODY: an armory body (default arm_f_slender).
          NAME: rebuild only these (wren, mob_soldier); the others stay as last built.
    
    Reads the cached cage body; never rebuilds one. Nothing in cage's cache key is touched.
    One numpy thread matters: measured 2026-11-10, her build took 84 s with the default threads (most of it system
    time) and 22 to 25 s with one. The soldier took 513 s with the default threads; not re-measured with one.
    Then: python3 tools/whole/shoot.py tools/whole/frame.json OUT.png (7 s a frame).
    """
    import json
    import os
    import shutil
    import sys
    import time
    
    os.environ.setdefault("LOWMARCH_SITE", "whole")
    HERE = os.path.dirname(os.path.abspath(__file__))
    ROOT = os.path.dirname(os.path.dirname(HERE))
    sys.path[:0] = [os.path.join(ROOT, "review", "vroid-02"), HERE]
    import build  # noqa: E402  (puts tools/ and art/cast on the path)
    import outfit  # noqa: E402
    import terrain  # noqa: E402
    import clips  # noqa: E402
    import numpy as np  # noqa: E402
    import cast  # noqa: E402
    from cast import CAST  # noqa: E402
    
    NAME = "wren"
    BODY = sys.argv[1] if len(sys.argv) > 1 else "arm_f_slender"
    
    
    def smooth_plate(pc, under, rounds=60, every=1, clear=0.006):
        """A breastplate as one rigid shell: its inside smoothed with its rims held, then kept
        `clear` off it. On this body the kit's plate came out moulded to the bust, with the bodice showing through."""
        pos, tri = pc["pos"].copy(), pc["tri"]
        n = len(pos)
        rim = np.zeros(n, bool)
        for loop in pc.get("loops", []):
            rim[np.asarray(loop)] = True
        e = np.concatenate([tri[:, [0, 1]], tri[:, [1, 2]], tri[:, [2, 0]], tri[:, [1, 0]], tri[:, [2, 1]], tri[:, [0, 2]]])
        deg = np.maximum(np.bincount(e[:, 0], minlength=n), 1)[:, None]
        for k in range(rounds):
            acc = np.zeros_like(pos)
            np.add.at(acc, e[:, 0], pos[e[:, 1]])
            pos[~rim] = (acc / deg)[~rim]
            if k % every == every - 1 or k == rounds - 1:
                d, cp, ti = under.query(pos)
                low = (~rim) & (d < clear)
                pos[low] = cp[low] + under.fn[ti[low]] * clear
        pc["pos"] = pos
        pc["nrm"] = outfit.vertex_normals(pos, tri)
        return pc
    
    
    def dress(fit):
        """Elaine's knight dress, minus her kit hair: the body keeps the VRoid hair its head came with."""
        out = []
        for pc in outfit.knight_dress(fit):
            m = pc["material"]
            if pc.get("role") == "hair" or "bun" in m or "braid" in m or "ribbon" in m or "HAIR" in m.upper():
                continue
            out.append(pc)
        by = {pc["material"]: pc for pc in out}
        plate, bodice = by.get("OUTFIT_breastplate"), by.get("OUTFIT_bodice")
        if PLATE_FIX and plate is not None and bodice is not None:
            smooth_plate(plate, outfit.Surface(bodice["pos"], bodice["tri"]))
        return out
    
    
    PLATE_FIX = os.environ.get("PLATE_FIX", "1") == "1"
    outfit.COSTUMES["whole_knight"] = dress
    src, ela = CAST[BODY], CAST["elaine"]
    HAIR, EYE = cast.HAIRS["auburn"], cast.EYES["amber"]
    # her own colours (not Elaine's blonde and blue, which was drawn after another studio's character): auburn hair,
    # one deep teal cloth, warm steel, a cream hem
    CAST[NAME] = dict(src, label="Wren", costume="whole_knight", stance="sword",
                      shape=dict(src["shape"], rest={"Fcl_BRW_Angry": 0.3}),
                      colors=dict(src["colors"], A=HAIR[0], B=HAIR[1], C=HAIR[2], D=HAIR[3], E=HAIR[4], r=EYE[0], s=EYE[1], t=EYE[2],
                                  K="#0f2e2c", L="#17474a", M="#1f6064", P="#4a9a96", Q="#0f111b", R="#1b1e2c", S="#2a2e42", T="#41465e"),
                      paint=dict(ela["paint"], signature="#1d5b5e", doublet="#1c2026", heraldry="#efe6d2", steel="#c3c6cc",
                                 gold="#c29a4a", hair=HAIR[2], grain=dict(signature=0.015)))
    # her stance: "sword" is the kit's one-handed clips; "longsword" is tools/whole/clips2h.py (both hands on the grip)
    STANCE = os.environ.get("WHOLE_STANCE", "sword")
    CAST[NAME]["stance"] = STANCE
    _kit_clips = clips.clips
    
    
    def _clips(vrm, shape=None, stance="sword"):
        if stance == "longsword":
            import clips2h
            return clips2h.clips(vrm, shape)
        return _kit_clips(vrm, shape, stance)
    
    
    clips.clips = _clips
    FOE = "mob_soldier"                                     # the enemy across from her: the old kit's soldier, as built
    build.LABELS = {NAME: "Wren", FOE: "Soldier"}
    _model_path = build.model_path
    build.model_path = lambda name, c: _model_path(BODY if name == NAME else name, CAST[BODY] if name == NAME else c)
    _plains = terrain.plains
    terrain.plains = lambda **kw: _plains(**dict(dict(width=9.0, depth=3.2, tufts=70, stones=9), **kw))   # room for two and a wide frame
    # where each stands on the stage (metres). Yaw 90 faces screen right in profile and -90 screen left; nearer 0 turns
    # the front toward the camera. The frame spec's own "place" overrides this without a rebuild.
    PLACE = {NAME: dict(pos=[-0.9, 0, 0.0], yaw=62), FOE: dict(pos=[1.3, 0, 0.0], yaw=-70)}
    
    if __name__ == "__main__":
        t0 = time.time()
        os.makedirs(build.OUT, exist_ok=True)
        want = [n for n in (NAME, FOE) if not sys.argv[2:] or n in sys.argv[2:]]
        entries, chk = [], {}
        old = json.load(open(f"{build.OUT}/camera.json")) if os.path.exists(f"{build.OUT}/camera.json") else {}
        prev = {c["name"]: c for c in old.get("characters", [])}
        for n in (NAME, FOE):
            if n not in want:
                entries.append(prev[n])
                continue
            t1 = time.time()
            r = build.character((n, None))
            print(f"{n}.glb {r['size'] / 1e6:.1f} MB, {time.time() - t1:.0f}s")
            print("  " + r["checks"]["summary"])
            for item in r["checks"]["through"]:
                print("    ! " + item["text"])
            entries.append(dict(name=n, label=build.LABELS[n], info=r["info"], cams=r["cams"]))
            chk[n] = r["checks"]
        build.scenery(NAME)
        cam = entries[0]["cams"]["battle"]
        out = dict(characters=entries,
                   duel=dict(order=dict(player=NAME, opponent=FOE), place=PLACE,
                             cam=dict(cam, pivot_px=[cam["w"] // 2, cam["pivot_px"][1]]), clip="idle"),
                   lineup=dict(order=[], spacing=0.95))
        json.dump(out, open(f"{build.OUT}/camera.json", "w"), indent=1, default=build.as_list)
        json.dump(chk, open(f"{build.OUT}/checks.json", "w"), indent=1)
        shutil.copy(os.path.join(ROOT, "review", "vroid-02", "index.html"), build.OUT)
        print(f"-> {build.OUT}  {time.time() - t0:.0f}s")
    """Shoot one composed battle frame from the built site (tools/whole/build.py), headless, in the painted renderer.
    
      python3 tools/whole/shoot.py SPEC.json OUT.png
    
    Works on a patched scratch copy of the site: the page in the repo is not changed. The patch lets the duel sheet take
    its tiles from the URL, pose each fighter with a clip and time of their own, move the key light, and paint a sky.
    SPEC: w, h (pixels), scale, size (metres of height in frame), pitch, yaw (the stage's turn), centre [x, y, z],
    clips {name: [clip, seconds]}, place {name: {pos, yaw}}, key [x, y, z] or {name: [x, y, z]} (optional), sky [top, bottom] (optional), hide [...].
    """
    import base64
    import io
    import json
    import os
    import re
    import shutil
    import socket
    import subprocess
    import sys
    import tempfile
    import time
    import urllib.parse
    
    from PIL import Image
    
    ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
    SITE = os.environ.get("WHOLE_SITE", os.path.join(ROOT, "review", "out", "whole", "site"))
    
    PATCHES = [
        # tiles from the URL
        ("function holdPose(clip, t) {",
         'if (params.get("tiles")) DUEL_ROWS.splice(0, DUEL_ROWS.length, ...JSON.parse(params.get("tiles")));\n'
         "function holdPose(clip, t) {"),
        # a clip and a time per fighter
        ("    const a = c.actions[clip] || c.actions.idle;\n    a.reset(); a.setEffectiveWeight(1); a.play(); a.time = t; c.mixer.update(0);",
         "    const own = clip && typeof clip === 'object' ? (clip[c.name] || ['idle', 0]) : [clip, t];\n"
         "    if (own[0] === 'ref') continue;\n"
         "    const a = c.actions[own[0]] || c.actions.idle;\n    a.reset(); a.setEffectiveWeight(1); a.play(); a.time = own[1]; c.mixer.update(0);"),
        # the key light, and a centre for the frame
        ("      frameAt(centre, h, tw_, th_, pitch);",
         "      if (tile.centre) centre = new THREE.Vector3(...tile.centre);\n"
         "      if (tile.key) active().forEach(c => {            // one key for all, or one per fighter by name\n"
         "        const kv = Array.isArray(tile.key) ? tile.key : tile.key[c.name]; if (!kv) return;\n"
         "        const k = new THREE.Vector3(...kv).normalize();\n"
         "        [...c.meshes, ...c.cloths.map(cl => cl.display)].forEach(o => { const m = o && o.userData.mats && o.userData.mats.painted;\n"
         "          if (m && m.uniforms.uKind.value !== 6) m.uniforms.uKey.value.copy(k); }); });\n"
         "      frameAt(centre, h, tw_, th_, pitch);"),
        # where each fighter stands, from the URL
        ("        const pl = CAM.duel.place[c.name];",
         '        const pl = (params.get("place") ? JSON.parse(params.get("place")) : CAM.duel.place)[c.name];'),
        # a sky behind the tile
        ("      ctx.drawImage(R.domElement, x, y0, tw_, th_);",
         "      if (tile.sky) { const g = ctx.createLinearGradient(0, y0, 0, y0 + th_);\n"
         "        tile.sky.forEach((c, i) => g.addColorStop(i / (tile.sky.length - 1), c));\n"
         "        ctx.fillStyle = g; ctx.fillRect(x, y0, tw_, th_); }\n"
         "      ctx.drawImage(R.domElement, x, y0, tw_, th_);"),
    ]
    
    
    def patched_site():
        d = tempfile.mkdtemp(prefix="whole_site_")
        for f in os.listdir(SITE):
            if f != "index.html":
                os.symlink(os.path.join(SITE, f), os.path.join(d, f))
        s = open(os.path.join(SITE, "index.html")).read()
        for old, new in PATCHES:
            if s.count(old) != 1:
                raise SystemExit(f"patch target not found once: {old[:60]!r}")
            s = s.replace(old, new)
        open(os.path.join(d, "index.html"), "w").write(s)
        return d
    
    
    def shoot(spec, out):
        scale = spec.get("scale", 2)
        tile = dict(clip=spec["clips"], t=0, yaw=spec.get("yaw", 0), pitch=spec.get("pitch", 6), size=spec.get("size", 2.3),
                    label="", **{k: spec[k] for k in ("centre", "key", "sky", "hide") if k in spec})
        rows = [dict(label="", tw=spec["w"] // scale, th=spec["h"] // scale, tiles=[tile])]
        site = patched_site()
        s = socket.socket()
        s.bind(("127.0.0.1", 0))
        port = s.getsockname()[1]
        s.close()
        server = subprocess.Popen([sys.executable, "-m", "http.server", str(port), "--bind", "127.0.0.1", "--directory", site],
                                  stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
        try:
            time.sleep(0.5)
            url = f"http://127.0.0.1:{port}/index.html?sheet=duel&scale={scale}&tiles={urllib.parse.quote(json.dumps(rows))}"
            if spec.get("place"):
                url += f"&place={urllib.parse.quote(json.dumps(spec['place']))}"
            r = subprocess.run([os.environ.get("CHROMIUM", "/snap/bin/chromium"), "--headless=new", "--use-angle=swiftshader",
                                "--enable-unsafe-swiftshader", "--ignore-gpu-blocklist", "--window-size=1280,900",
                                "--virtual-time-budget=600000", "--dump-dom", url], capture_output=True, text=True, timeout=900)
            m = re.search(r'id="sheetOut"[^>]*>[redacted: data-URI prefix]([A-Za-z0-9+/=]+)<', r.stdout)
            if not m:
                err = re.search(r'id="sheetOut"[^>]*>([^<]*)<', r.stdout)
                raise SystemExit("FAILED " + (err.group(1)[:400] if err else r.stderr[-800:]))
            im = Image.open(io.BytesIO(base64.b64decode(m.group(1))))
            gap, head = 6, 30                                   # the sheet's margins: crop to the one tile
            im.crop((gap, gap + head, gap + spec["w"], gap + head + spec["h"])).convert("RGB").save(out)
        finally:
            server.terminate()
            shutil.rmtree(site, ignore_errors=True)
    
    
    if __name__ == "__main__":
        t0 = time.time()
        shoot(json.load(open(sys.argv[1])), sys.argv[2])
        print(sys.argv[2], f"{time.time() - t0:.0f}s")
    # Map of the repo
    
    What's current, what's stale, where the big files are. Checked 2026-11-08 at `c4f1015`. Nothing was moved or deleted.
    "Live" means the armory build or the first-session kit reaches it. Reach was read from imports, including the
    `__import__` calls in `outfit.py`, not from running every path.
    
    ## Docs
    
    | File | Status |
    |---|---|
    | `handbook.md` | **Start here** |
    | `map.md`, `todos-2026-11-08.md` | Current; suggestions only |
    | `portrait-guide.md` | Detail log, 40 lessons. True when written, some since contradicted; marks are in the handbook |
    | `vroid.md` | Current. Says 54 expression shapes at the top; the files carry 57 (2.14) and 56 (older). Licence: see #1443 |
    | `anthro.md` | Current for bodies |
    | `proportions.md` | Bodies current; face ratios are reported, not held, since lesson 30 |
    | `makehuman.md` | Current: references for the cage |
    | `study.md` | Current; one clause is guessed (handbook, Things that don't bend) |
    | `quaternius.md` | Stale: a spike that lost (lesson 21) |
    
    ## Tools
    
    **First-session kit (new):** `tools/session/` (`frame.py`, `rows.py`, `smoke.sh`, `smoke_spec.json`), `review/frame/index.html`.
    
    **Render scripts (copied in 11-08 from `[redacted: private path]/kit`, which still has the originals):** `tools/shots/`:
    `arm_shoot.py` (ran 11-08), `variant_build.py`, `all14.sh`, `all14_sheet.py`, `expr_build_tiles.py`, `expr_page.html`. Only
    `all14.sh` changed, to find its own folder.
    
    | Status | Files |
    |---|---|
    | Live: the armory | `cage`, `heads`, `fit`, `proportions`, `anthro`, `makehuman`, `collide`, `vroid_portrait`, `vrm`, `export_glb`, `poses`, `rig`, `fitting`; `review/vroid-02/build.py`, `sheets.py`, `index.html`; `art/cast/cast.py`, `expressions.txt` |
    | Live checks | `lash_check`, `lash_shots`, `checks`, `regress`, `review/vroid-02/snapshot.py` (keeps the baseline `regress` reads), `review/vroid-02/duel_check.py` (build imports `chars_for` from it), `hair_check` (standalone, nothing imports it) |
    | Kept for later: costumes and motion on old bases, reached from the build | `outfit`, `plates`, `gear`, `mobs`, `hair`, `clips`, `duel`, `terrain`, `saber_study` (benchmark, not for the game). Not unused: the armory's inspection shorts come from `mobs.underwear` and the hair texture from `hair` |
    | Spike that lost, still imported by the build | `mass`, `quaternius` |
    | Pixel era, abandoned; still imported | `head3d`, `pix`, `vecpix`, `study` |
    | Blocked | `tools/winvroid` (V.dll, #1105) |
    | Looks dead: nothing imports it | `features.py`, `compare.py` (study side-by-sides) |
    | Looks dead: old one-off tests, nothing imports them | `review/vroid-02/`: `battle_test`, `closeup_test`, `costume_test`, `fit_test`, `pose_test`, `mouths` |
    | Stale pages | `review/rowan-01/`, `art/portraits/rowan*`, `art/templates/`, `review/vroid-02/base_spike_notes.html`, `mh_workshop_notes.html` |
    
    `vroid_portrait.py` is named for the abandoned pixel renderer, but the build still uses its `Portrait` class. Don't edit it
    lightly: it's in cage's cache key, and so are the other cache-key files listed in the handbook.
    
    **Scripts that live outside the repo:**
    
    - `[redacted: private path]/kit/`: the benchmark's kit, including `front_sheet.py`, `build_expr.sh`, `blind_sheet.py`, `terra_review.sh`.
    - `[redacted: private path]/trials/*/scripts` and loose scripts there, such as `patch_lens_flattice.py` (a perspective lens for the painted page). Copy one in if it's needed again.
    
    ## Big files
    
    The repo's tracked files are small: `.git` is 5 MB. Everything below is outside git.
    
    | Where | Size | What |
    |---|---|---|
    | `[redacted: private path]/vroid/lowmarch_bodies` | 14 GB | Built bodies and heads; holds cage's cache (`fits.json`). The bulk of everything |
    | `[redacted: private path]/vroid/samples_2_14` | 466 MB | The 26 VRoid samples |
    | `[redacted: private path]/makehuman` | 1.7 GB | MakeHuman data |
    | `[redacted: private path]/trials` | 1.9 GB | Sheets and shots; `combined-2026-10-31` is 1.8 GB |
    | `[redacted: private path]/tools` | 1.5 GB | Portable Blender 4.5, tar included. Unused since the spike |
    | `[redacted: private path]/winvroid` | 803 MB | VRoid driver data |
    | `[redacted: private path]/refs3d`, `study`, `quaternius`, `blender-base-meshes`, `refs`, `anthro` | 1.2 GB together | Study and spike data. References stay out of the repo |
    | `[redacted: private path]/sessions` | new | First-session folders from `rows.py` |
    | `[redacted: private path]/work` | 4.9 GB | Benchmark builds; `e` is 3 GB. Transcripts and judging keep the benchmark's record |
    | `review/out/` (git-ignored) | 1.1 GB | `versions` 410 MB, `vroid-02` 249, `base-spike` 206, `armory` 115, `mh-workshop` 89, `frozen` 14 |
    | `[redacted: private path]` | | Blender 5.2.3, unused by the pipeline |
    
    If space is ever needed, the safest candidates to discuss are the Blender 4.5 tar, `review/out/versions` and
    `review/out/base-spike`. Nothing has been removed. Ask first, and check `[redacted: private path]/README.md`: the
    benchmark's raw material is being kept for a blog post (#1141).
  • Bashcat tools/export_glb.py

    command

    cat tools/export_glb.py

    result, 54 lines

    <persisted-output>
    Output too large (31KB). Full output saved to: [redacted: private path]/tool-results/bu5i6w1hv.txt
    
    Preview (first 2KB):
    """Export a composed character (VRoid base + our shapes, costume, props, scenery) to GLB for the
    browser 3D viewer.
    
    Each primitive becomes a mesh named by its group (body, hair, costume pieces, sword, terrain) so
    the viewer can toggle and x-ray them. Face, eye, line, brow, mouth and hair keep VRoid's textures
    (downscaled) for alpha and detail; everything else gets the character's palette colour. The model
    is turned to face +z, the direction a default three.js camera looks from.
    """
    import io
    import math
    import json
    import struct
    
    import numpy as np
    from PIL import Image
    
    FLIP = np.array([-1.0, 1.0, -1.0])
    TEXTURED = ("face", "iris", "white", "highlight", "line", "brow", "mouth", "hair")
    ROLE_TONE = {"face": "5", "body": "4", "shadow": "3", "hair": "D", "brow": "B", "coat": "M", "cape": "W", "metal": "8",
                 "signature": "M", "doublet": "S", "heraldry": "N",
                 "steel": "8", "gold": "H", "leather": "v", "boot": "v", "glove": "x", "cloth": "M",
                 "grass": "c", "dirt": "f", "stone": "l", "mouth": "2", "line": "o", "iris": "s", "white": "w",
                 "highlight": "w"}
    
    
    def group_of(p, role):
        if p.get("world"):
            return "terrain"
        if p.get("group"):
            return p["group"]
        if role in ("face", "body", "shadow", "iris", "white", "highlight", "line", "brow", "mouth"):
            return "body"
        if role == "hair":
            return "hair"
        name = p["material"].replace("OUTFIT_", "")
        for key in ("trim", "edge", "hem", "placket", "buckle", "clasp"):
            if key in name:
                return "trim"
        for key in ("pauldron", "cape", "collar", "tunic", "tails", "belt", "trousers", "boots", "gloves"):
            if name.startswith(key):
                return key
        if name in ("blade", "guard", "grip", "pommel", "fuller"):
            return "sword"
        return "costume"
    
    
    def skin_ramp(h):
        """A skin tone's lit, shade and deep-shade colours from its lit colour. The shade is darker and a little more
    ...
    </persisted-output>