From cd7684f4b7669f79c6a805de0706c4db378a7c4f Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 18:50:25 +0100 Subject: [PATCH 1/3] Render the Classic portrait capture headlessly scripts/portrait-capture renders the bald 1.12 human male with classic-wow-model-viewer in headless Chromium, framed like the portrait camera, with alpha matted from black and white renders. The capture lives on the NAS next to the other proof portraits. --- .gitignore | 1 + DEVELOPMENT.md | 20 ++++- scripts/portrait-capture/capture.mjs | 89 ++++++++++++++++++++++ scripts/portrait-capture/package-lock.json | 42 ++++++++++ scripts/portrait-capture/package.json | 14 ++++ scripts/portrait-capture/page.html | 37 +++++++++ 6 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 scripts/portrait-capture/capture.mjs create mode 100644 scripts/portrait-capture/package-lock.json create mode 100644 scripts/portrait-capture/package.json create mode 100644 scripts/portrait-capture/page.html diff --git a/.gitignore b/.gitignore index e4ecbca..03226df 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ UnitFrames_Media/Libs/ /.build/ /.proof/ /.proof-art/ +/scripts/portrait-capture/node_modules/ diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 706c455..ef4a293 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -288,7 +288,7 @@ stands in a picture for the unit the model shows, keeping the model's alpha, model alpha and dead/ghost desaturation. Proof renders Forever's **Classic** experience preset (original "SD" character models) by default; `UF_PROOF_PRESET=enhanced` renders the HD one. For each preset it first looks -for an in-game capture of the default portrait, +for a capture of the default portrait, `/-.png` (`Pet`/`Monster` for non-players), in the private folder `UF_PROOF_PORTRAITS` (default `nas:/volume1/Game/unit-frames/proof-portraits`, fetched over `ssh` into `.proof-art/portraits/`; also a local folder or an @@ -296,6 +296,24 @@ HTTPS URL; skipped when `CI` is set or `UF_PROOF_ART_FETCH=0`). Captures are Blizzard art: keep them in that folder, never in the repo. Without a capture it falls back to Blizzard's static HD portrait (`Interface\CharacterFrame\TemporaryPortrait-Male-`) from the mirror. + +`scripts/portrait-capture` renders the Classic captures: the 1.12 character +model through [classic-wow-model-viewer](https://github.com/JollyGrin/turtle-wow-model-viewer) +(MIT, three.js) in Playwright's headless Chromium shell (SwiftShader), framed +like `SetPortraitZoom(1)`, bald (hairstyle geoset 1, as the library's default +hair leaves a scalp gap), on a transparent background matted from a black and +a white render. It needs Node, ImageMagick and a headless shell under +`~/.cache/ms-playwright` (`npx playwright install chromium-headless-shell`, +or `CHROME=`). The model files come from the library's demo CDN +(`--cdn` or `PORTRAIT_CDN` for another), so render once and store the result +with the other captures: + +```sh +cd scripts/portrait-capture && npm ci +node capture.mjs human male /tmp/Male-Human.png # --hair N, --size 256 +ssh nas 'cat > /volume1/Game/unit-frames/proof-portraits/classic/Male-Human.png' < /tmp/Male-Human.png +rm -rf ../../.proof-art/portraits # re-fetch on the next proof run +``` Previews always show the player's own model (the portrait driver's sample is `"player"`), so every sample portrait is the mocked Human. `player-dead`, `focus-portrait` and `pet-portrait` cover the portraits that are off by diff --git a/scripts/portrait-capture/capture.mjs b/scripts/portrait-capture/capture.mjs new file mode 100644 index 0000000..0a245e1 --- /dev/null +++ b/scripts/portrait-capture/capture.mjs @@ -0,0 +1,89 @@ +import { chromium } from "playwright-core"; +import { execFileSync } from "node:child_process"; +import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs"; +import { homedir, tmpdir } from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const ROOT = path.dirname(fileURLToPath(import.meta.url)); +const VIEWER = "classic-wow-model-viewer/dist/index.js"; +const DEFAULT_CDN = "https://jollygrin.github.io/turtle-wow-model-viewer"; +const BROWSERS = path.join(homedir(), ".cache", "ms-playwright"); +const TYPES = { ".js": "text/javascript", ".html": "text/html" }; + +const usage = () => { + console.error("usage: node capture.mjs [--hair N] [--size N] [--cdn URL]"); + process.exit(1); +}; + +const parseArgs = (argv) => { + const [race, gender, out, ...rest] = argv; + if (!race || !gender || !out) usage(); + const options = { race, gender, out, hair: 1, size: 256, cdn: process.env.PORTRAIT_CDN ?? DEFAULT_CDN }; + for (let index = 0; index < rest.length; index += 2) { + const key = rest[index].replace(/^--/, ""); + if (!(key in options) || rest[index + 1] === undefined) usage(); + options[key] = ["hair", "size"].includes(key) ? Number(rest[index + 1]) : rest[index + 1]; + } + return options; +}; + +const findChrome = () => { + if (process.env.CHROME) return process.env.CHROME; + const shells = existsSync(BROWSERS) ? readdirSync(BROWSERS).filter((name) => name.startsWith("chromium_headless_shell-")).sort() : []; + for (const shell of shells.reverse()) { + for (const build of readdirSync(path.join(BROWSERS, shell))) { + const binary = path.join(BROWSERS, shell, build, "chrome-headless-shell"); + if (existsSync(binary)) return binary; + } + } + return undefined; +}; + +const withHairstyle = (source, hair) => { + const patched = source.replace("a.groups,\n 5,", `a.groups,\n ${hair},`); + if (patched === source) throw new Error(`${VIEWER} changed: can't set the hairstyle`); + return patched; +}; + +const serve = (page, hair) => page.route("http://capture/**", (route) => { + const pathname = new URL(route.request().url()).pathname; + const file = path.join(ROOT, pathname); + if (!file.startsWith(ROOT) || !existsSync(file)) return route.fulfill({ status: 404 }); + const body = pathname.endsWith(VIEWER) ? withHairstyle(readFileSync(file, "utf8"), hair) : readFileSync(file); + return route.fulfill({ body, contentType: TYPES[path.extname(file)] ?? "application/octet-stream" }); +}); + +const options = parseArgs(process.argv.slice(2)); +const browser = await chromium.launch({ + executablePath: findChrome(), + args: ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", "--ignore-gpu-blocklist"], +}); +const work = mkdtempSync(path.join(tmpdir(), "portrait-")); + +try { + const page = await browser.newPage({ viewport: { width: options.size, height: options.size } }); + page.on("pageerror", (error) => console.error(error.message)); + await serve(page, options.hair); + const query = new URLSearchParams({ cdn: options.cdn, race: options.race, gender: options.gender }); + await page.goto(`http://capture/page.html?${query}`); + await page.waitForFunction(() => window.ready, null, { timeout: 60000 }); + + const shots = {}; + for (const [name, color] of [["black", 0x000000], ["white", 0xffffff]]) { + await page.evaluate((value) => window.setBackground(value), color); + await page.waitForTimeout(500); + shots[name] = path.join(work, `${name}.png`); + await page.screenshot({ path: shots[name] }); + } + + execFileSync("magick", [ + shots.black, + "(", shots.black, shots.white, "-compose", "difference", "-composite", "-colorspace", "gray", "-negate", ")", + "-alpha", "off", "-compose", "copy_opacity", "-composite", options.out, + ]); + console.log(options.out); +} finally { + await browser.close(); + rmSync(work, { recursive: true, force: true }); +} diff --git a/scripts/portrait-capture/package-lock.json b/scripts/portrait-capture/package-lock.json new file mode 100644 index 0000000..31ce8fa --- /dev/null +++ b/scripts/portrait-capture/package-lock.json @@ -0,0 +1,42 @@ +{ + "name": "portrait-capture", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "portrait-capture", + "dependencies": { + "classic-wow-model-viewer": "0.1.0", + "playwright-core": "1.65.0", + "three": "0.187.0" + } + }, + "node_modules/classic-wow-model-viewer": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/classic-wow-model-viewer/-/classic-wow-model-viewer-0.1.0.tgz", + "integrity": "sha512-0PFPxFSkHZZpDGTi3/7uq4Nd9DARI9vCiI/E+H91z+XK+/h4lHUwpsB2zuOd45N1CKCk1f+mZ75zg+8FqOIzIQ==", + "license": "MIT", + "peerDependencies": { + "three": ">=0.160.0" + } + }, + "node_modules/playwright-core": { + "version": "1.65.0", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.65.0.tgz", + "integrity": "sha512-vNSKgH6YqtN7cdT/L334zo0a+YwkrpicyrHJlWWPIm/Q+Nn2SWInil01oT0mbu96U4GgoRtCYQD9CzJQgju+lA==", + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/three": { + "version": "0.187.0", + "resolved": "https://registry.npmjs.org/three/-/three-0.187.0.tgz", + "integrity": "sha512-Qiu7R+Cmh8CstZsY1uJOSWnVlfo7ZtNLV7mF8Jltk3LB3AtDu9cRZlcnRKkAk8Y4z6KKw35z7Y7Urd7jWY8etA==", + "license": "MIT" + } + } +} diff --git a/scripts/portrait-capture/package.json b/scripts/portrait-capture/package.json new file mode 100644 index 0000000..5144fa0 --- /dev/null +++ b/scripts/portrait-capture/package.json @@ -0,0 +1,14 @@ +{ + "name": "portrait-capture", + "private": true, + "type": "module", + "description": "Renders a 3D portrait stand-in for UI proof with classic-wow-model-viewer in headless Chromium", + "scripts": { + "capture": "node capture.mjs" + }, + "dependencies": { + "classic-wow-model-viewer": "0.1.0", + "playwright-core": "1.65.0", + "three": "0.187.0" + } +} diff --git a/scripts/portrait-capture/page.html b/scripts/portrait-capture/page.html new file mode 100644 index 0000000..3d4b621 --- /dev/null +++ b/scripts/portrait-capture/page.html @@ -0,0 +1,37 @@ + + + +
+ + + + From 513dfb36c0a71b71ba98b1a5049ac27fa7f0de9d Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 18:59:52 +0100 Subject: [PATCH 2/3] Frame the portrait capture like the client Takes the field of view and viewing direction from the pinned build's humanmale.m2 portrait camera, aims at the posed head and calibrates the turn and framing against an in-game player frame. The pose is frozen so the black and white renders match. --- DEVELOPMENT.md | 16 ++++++-- scripts/portrait-capture/capture.mjs | 57 ++++++++++++++++++++++++++-- scripts/portrait-capture/page.html | 45 +++++++++++++++++----- 3 files changed, 101 insertions(+), 17 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index ef4a293..4587b9a 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -299,10 +299,17 @@ it falls back to Blizzard's static HD portrait `scripts/portrait-capture` renders the Classic captures: the 1.12 character model through [classic-wow-model-viewer](https://github.com/JollyGrin/turtle-wow-model-viewer) -(MIT, three.js) in Playwright's headless Chromium shell (SwiftShader), framed -like `SetPortraitZoom(1)`, bald (hairstyle geoset 1, as the library's default -hair leaves a scalp gap), on a transparent background matted from a black and -a white render. It needs Node, ImageMagick and a headless shell under +(MIT, three.js) in Playwright's headless Chromium shell (SwiftShader). It +replicates the client's `SetPortraitZoom(1)` view rather than inventing one: +the field of view and viewing direction come from the portrait camera (type 0) +of the pinned build's own M2 (`--m2`, human male 119940, fetched from Wago), +frozen at the first frame of Stand. The library's Stand pose leans the head +forward where Forever's doesn't, so the camera aims at the posed head (skinned +vertices) and `TURN`, `HEAD_SHARE` and `CENTER_DROP` in `capture.mjs` are +calibrated against an in-game player frame. The model is bald (hairstyle +geoset 1, as the library's default hair leaves a scalp gap), on a transparent +background matted from a black and a white render. It needs Node, ImageMagick +and a headless shell under `~/.cache/ms-playwright` (`npx playwright install chromium-headless-shell`, or `CHROME=`). The model files come from the library's demo CDN (`--cdn` or `PORTRAIT_CDN` for another), so render once and store the result @@ -314,6 +321,7 @@ node capture.mjs human male /tmp/Male-Human.png # --hair N, --size 256 ssh nas 'cat > /volume1/Game/unit-frames/proof-portraits/classic/Male-Human.png' < /tmp/Male-Human.png rm -rf ../../.proof-art/portraits # re-fetch on the next proof run ``` + Previews always show the player's own model (the portrait driver's sample is `"player"`), so every sample portrait is the mocked Human. `player-dead`, `focus-portrait` and `pet-portrait` cover the portraits that are off by diff --git a/scripts/portrait-capture/capture.mjs b/scripts/portrait-capture/capture.mjs index 0a245e1..5a81266 100644 --- a/scripts/portrait-capture/capture.mjs +++ b/scripts/portrait-capture/capture.mjs @@ -8,22 +8,38 @@ import { fileURLToPath } from "node:url"; const ROOT = path.dirname(fileURLToPath(import.meta.url)); const VIEWER = "classic-wow-model-viewer/dist/index.js"; const DEFAULT_CDN = "https://jollygrin.github.io/turtle-wow-model-viewer"; +const DEFAULT_BUILD = "1.60.1.70862"; +const CASC = "https://wago.tools/api/casc"; +const MODELS = { "human-male": 119940 }; +const PORTRAIT_CAMERA = 0; +const CAMERA_SIZE = 116; +const NECK = 1.8; +const HEAD_SHARE = 0.55; +const CENTER_DROP = 0.13; +const TURN = 10; const BROWSERS = path.join(homedir(), ".cache", "ms-playwright"); const TYPES = { ".js": "text/javascript", ".html": "text/html" }; const usage = () => { - console.error("usage: node capture.mjs [--hair N] [--size N] [--cdn URL]"); + console.error("usage: node capture.mjs [--hair N] [--size N] [--turn DEG] [--m2 FileDataID] [--build B] [--cdn URL]"); process.exit(1); }; const parseArgs = (argv) => { const [race, gender, out, ...rest] = argv; if (!race || !gender || !out) usage(); - const options = { race, gender, out, hair: 1, size: 256, cdn: process.env.PORTRAIT_CDN ?? DEFAULT_CDN }; + const options = { + race, gender, out, hair: 1, size: 256, turn: TURN, m2: MODELS[`${race}-${gender}`], build: DEFAULT_BUILD, + cdn: process.env.PORTRAIT_CDN ?? DEFAULT_CDN, + }; for (let index = 0; index < rest.length; index += 2) { const key = rest[index].replace(/^--/, ""); if (!(key in options) || rest[index + 1] === undefined) usage(); - options[key] = ["hair", "size"].includes(key) ? Number(rest[index + 1]) : rest[index + 1]; + options[key] = ["hair", "size", "m2", "turn"].includes(key) ? Number(rest[index + 1]) : rest[index + 1]; + } + if (!options.m2) { + console.error(`no client model known for ${race}-${gender}: pass --m2 `); + process.exit(1); } return options; }; @@ -40,6 +56,34 @@ const findChrome = () => { return undefined; }; +const portraitCamera = async (fileDataId, build) => { + const response = await fetch(`${CASC}/${fileDataId}?version=${build}`); + if (!response.ok) throw new Error(`model ${fileDataId}: HTTP ${response.status}`); + const file = Buffer.from(await response.arrayBuffer()); + const header = file.indexOf("MD20"); + if (header < 0) throw new Error(`model ${fileDataId} is not an M2`); + const m2 = file.subarray(header); + const vector = (offset) => [m2.readFloatLE(offset), m2.readFloatLE(offset + 4), m2.readFloatLE(offset + 8)]; + const firstKey = (track) => { + const animations = m2.readUInt32LE(track + 12), keys = m2.readUInt32LE(track + 16); + if (!animations || !m2.readUInt32LE(keys)) return undefined; + return m2.readFloatLE(m2.readUInt32LE(keys + 4)); + }; + const count = m2.readUInt32LE(272), cameras = m2.readUInt32LE(276); + for (let index = 0; index < count; index++) { + const camera = cameras + index * CAMERA_SIZE; + if (m2.readUInt32LE(camera) !== PORTRAIT_CAMERA) continue; + return { + far: m2.readFloatLE(camera + 4), + near: m2.readFloatLE(camera + 8), + position: vector(camera + 32), + target: vector(camera + 64), + fov: firstKey(camera + 96), + }; + } + throw new Error(`model ${fileDataId} has no portrait camera`); +}; + const withHairstyle = (source, hair) => { const patched = source.replace("a.groups,\n 5,", `a.groups,\n ${hair},`); if (patched === source) throw new Error(`${VIEWER} changed: can't set the hairstyle`); @@ -55,6 +99,7 @@ const serve = (page, hair) => page.route("http://capture/**", (route) => { }); const options = parseArgs(process.argv.slice(2)); +const camera = await portraitCamera(options.m2, options.build); const browser = await chromium.launch({ executablePath: findChrome(), args: ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", "--ignore-gpu-blocklist"], @@ -65,7 +110,11 @@ try { const page = await browser.newPage({ viewport: { width: options.size, height: options.size } }); page.on("pageerror", (error) => console.error(error.message)); await serve(page, options.hair); - const query = new URLSearchParams({ cdn: options.cdn, race: options.race, gender: options.gender }); + const framing = { turn: options.turn, neck: NECK, headShare: HEAD_SHARE, centerDrop: CENTER_DROP }; + const query = new URLSearchParams({ + cdn: options.cdn, race: options.race, gender: options.gender, + camera: JSON.stringify(camera), framing: JSON.stringify(framing), + }); await page.goto(`http://capture/page.html?${query}`); await page.waitForFunction(() => window.ready, null, { timeout: 60000 }); diff --git a/scripts/portrait-capture/page.html b/scripts/portrait-capture/page.html index 3d4b621..d8f412f 100644 --- a/scripts/portrait-capture/page.html +++ b/scripts/portrait-capture/page.html @@ -20,17 +20,44 @@ } }); -const box = new THREE.Box3().setFromObject(viewer.scene); -const size = box.getSize(new THREE.Vector3()); -const head = new THREE.Vector3((box.min.x + box.max.x) / 2, box.max.y - size.y * 0.135, (box.min.z + box.max.z) / 2); -const facing = viewer.camera.position.clone().sub(viewer.controls.target).normalize(); -viewer.camera.fov = 30; -viewer.camera.position.copy(head).add(facing.multiplyScalar(size.y * 0.42)).add(new THREE.Vector3(0, -size.y * 0.06, 0)); +const toScene = ([x, y, z]) => new THREE.Vector3(x, z, -y); +const camera = JSON.parse(params.get("camera")); +const framing = JSON.parse(params.get("framing")); + +cancelAnimationFrame(viewer.animFrameId); +viewer.playAnimationByName("Stand"); +viewer.animController.update(0); +viewer.scene.updateMatrixWorld(true); + +const head = new THREE.Box3(); +const vertex = new THREE.Vector3(); +viewer.scene.traverse((object) => { + if (!object.isSkinnedMesh) return; + const positions = object.geometry.attributes.position; + for (const index of new Set(object.geometry.index.array)) { + const [x, y, z] = [positions.getX(index), positions.getY(index), positions.getZ(index)]; + if (z < framing.neck || Math.abs(x) > 0.3 || Math.abs(y) > 0.25) continue; + head.expandByPoint(object.getVertexPosition(index, vertex).applyMatrix4(object.matrixWorld)); + } +}); +const size = head.getSize(new THREE.Vector3()); +const target = head.getCenter(new THREE.Vector3()); +const visible = size.y / framing.headShare; +target.y -= visible * framing.centerDrop; + +const direction = toScene(camera.position).sub(toScene(camera.target)).normalize() + .applyAxisAngle(new THREE.Vector3(0, 1, 0), THREE.MathUtils.degToRad(framing.turn)); +viewer.camera.fov = THREE.MathUtils.radToDeg(camera.fov); +viewer.camera.near = camera.near; +viewer.camera.far = camera.far; +viewer.camera.position.copy(target).add(direction.multiplyScalar(visible / 2 / Math.tan(camera.fov / 2))); +viewer.camera.lookAt(target); viewer.camera.updateProjectionMatrix(); -viewer.controls.target.copy(head); -viewer.controls.update(); -window.setBackground = (color) => viewer.renderer.setClearColor(color); +window.setBackground = (color) => { + viewer.renderer.setClearColor(color); + viewer.renderer.render(viewer.scene, viewer.camera); +}; window.ready = true; From 878384f8821d333751058c60b506768ba861146b Mon Sep 17 00:00:00 2001 From: Martin Konstantin Herrmann Date: Mon, 9 Nov 2026 19:01:47 +0100 Subject: [PATCH 3/3] Describe portrait captures in the proof guide --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4de146b..5f43cc0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -103,7 +103,7 @@ luajit tests/run.lua workbench -t "preview" Every change that can affect what a frame, preview or Workbench panel looks like ships with UI proof rendered by `wowproof`: in the pull request and, when working in Beluga, in the chat and on the task. 1. Pick the scenarios in `tests/proof/units.lua` and `tests/proof/workbench.lua` that show the change. When none does (a new setting, state or layout), add one: a name plus a `build` that configures through `Config:SetUnitValue` and feeds sample values. Prefer one scenario per state the change touches (like `player-idle` beside `player`) over one busy frame. -2. Render and look at them with `bash scripts/proof.sh ` before claiming the change works. Dashed placeholders mean missing art or an atlas the generated table lacks, not a bug. 3D portraits show a static race portrait as a stand-in; mention them if they hide the change. +2. Render and look at them with `bash scripts/proof.sh ` before claiming the change works. Dashed placeholders mean missing art or an atlas the generated table lacks, not a bug. 3D portraits show a pre-rendered capture of the mocked player (Classic preset, from `UF_PROOF_PORTRAITS`), or a static race portrait where that folder isn't reachable, such as CI; mention them if they hide the change. 3. When opening or updating the pull request, run `bash scripts/proof-publish.sh --out .beluga/scratch/proof `. It renders the scenarios, commits the PNGs to the orphan `ui-proof` branch under `/` (it never touches the working tree or the current branch) and prints a `### UI proof` Markdown section with images pinned to that commit. Paste that section into the PR body (`gh pr create --body-file` or `gh pr edit --body-file`). Re-run it after visual changes in review; old links keep showing the earlier images. `--dry-run` skips the push. 4. In Beluga, show the same PNGs in the answer as Markdown images with their absolute paths under `.beluga/scratch/proof/`, and attach each one to the worktree's task with `task_attach_proof` (kind `image`). 5. Proof shows mocked rendering only. Still list what needs in-game verification (see Verification above): combat, secret values, taint, Edit Mode and live unit changes.