@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/score/light.js

@@ -0,0 +1,62 @@
+import { lab } from "./measure.js";
+export function lightRead(p) {
+    const n = p.width * p.height, L = [];
+    let sa = 0, sb = 0, sc = 0, edge = 0, ne = 0, mid = 0, nm = 0;
+    for (let i = 0; i < n; i++) {
+        const [l, a, b] = lab(p.data[i * 4], p.data[i * 4 + 1], p.data[i * 4 + 2]);
+        L.push(l);
+        sa += a;
+        sb += b;
+        sc += Math.hypot(a, b);
+        const x = (i % p.width) / p.width, y = Math.floor(i / p.width) / p.height, r = Math.hypot(x - 0.5, (y - 0.45) * 1.2);
+        if (r > 0.5) {
+            edge += l;
+            ne++;
+        }
+        else if (r < 0.25) {
+            mid += l;
+            nm++;
+        }
+    }
+    const mean = L.reduce((s, v) => s + v, 0) / n, sorted = [...L].sort((x, y) => x - y), q = (f) => sorted[Math.min(n - 1, Math.floor(f * n))];
+    const spread = Math.sqrt(L.reduce((s, v) => s + (v - mean) ** 2, 0) / n);
+    const r1 = (v) => Math.round(v * 10) / 10;
+    return { meanL: r1(mean), spreadL: r1(spread), pools: r1(q(0.95) - q(0.5)), chroma: r1(sc / n), a: r1(sa / n), b: r1(sb / n), edgeDark: r1((nm ? mid / nm : mean) - (ne ? edge / ne : mean)) };
+}
+const hexOfLab = (L, a, b) => {
+    const fy = (L + 16) / 116, fx = fy + a / 500, fz = fy - b / 200, inv = (t) => (t ** 3 > 0.008856 ? t ** 3 : (t - 16 / 116) / 7.787);
+    const X = inv(fx) * 0.95047, Y = inv(fy), Z = inv(fz) * 1.08883;
+    const rgb = [3.2406 * X - 1.5372 * Y - 0.4986 * Z, -0.9689 * X + 1.8758 * Y + 0.0415 * Z, 0.0557 * X - 0.204 * Y + 1.057 * Z];
+    return '#' + rgb.map((c) => Math.round(255 * Math.min(1, Math.max(0, c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055)))).map((v) => v.toString(16).padStart(2, '0')).join('');
+};
+export function lightMoves(c, t, now = {}, scope = 'light') {
+    const out = [], fmt = (v) => String(Math.round(v * 100) / 100);
+    const set = (key, from, factor, add = 0) => (from === undefined ? (add ? `${add > 0 ? '+' : ''}${fmt(add)}` : `×${fmt(factor)}`) : fmt(from * factor + add));
+    const where = (key) => (scope === 'light' ? `look set light.${key}` : `${scope}.${key} in src/places.json:`);
+    const say = (key, value, why, size) => out.push({ key, set: value, size, say: `${why}: ${value.startsWith('×') || /^[+-]/.test(value) ? `change ${scope}.${key} ${value}` : scope === 'light' ? `${where(key)}=${value}` : `${where(key)} ${value}`}` });
+    const dL = t.meanL - c.meanL;
+    if (Math.abs(dL) >= 4) {
+        const k = Math.min(2, Math.max(0.4, ((t.meanL + 16) / (c.meanL + 16)) ** 2.2));
+        say('exposure', set('exposure', now.exposure, k), `the frame is ${Math.abs(Math.round(dL))} L* ${dL < 0 ? 'brighter' : 'darker'} than the target`, Math.abs(dL) / 4);
+    }
+    if (t.pools - c.pools >= 8) {
+        say('spots', String(Math.max(3, (now.spots ?? 0) + 2)), `the target's light sits in pools (bright tail ${t.pools} over the median, the frame's ${c.pools}): spot the landmarks and the art`, (t.pools - c.pools) / 6);
+        say('ambient', set('ambient', now.ambient, 0.6), 'and drop the even fill so the shadow between the pools stays deep', (t.pools - c.pools) / 8);
+    }
+    else if (c.pools - t.pools >= 8)
+        say('ambient', set('ambient', now.ambient, 1.4), `the frame is spottier than the target (bright tail ${c.pools} against ${t.pools}): lift the fill`, (c.pools - t.pools) / 8);
+    const dS = t.spreadL - c.spreadL;
+    if (Math.abs(dS) >= 4)
+        say('contrast', set('contrast', now.contrast, 1 + Math.max(-0.3, Math.min(0.3, dS / 40))), `the target's light spreads ${t.spreadL} L*, the frame's ${c.spreadL}`, Math.abs(dS) / 5);
+    if (c.chroma > 2 && Math.abs(t.chroma / c.chroma - 1) >= 0.2)
+        say('saturation', set('saturation', now.saturation, Math.max(0.6, Math.min(1.5, t.chroma / c.chroma))), `the target's colour is ${t.chroma > c.chroma ? 'richer' : 'quieter'} (chroma ${t.chroma} against ${c.chroma})`, Math.abs(t.chroma - c.chroma) / 4);
+    const lean = Math.hypot(t.a - c.a, t.b - c.b);
+    if (lean >= 5)
+        say('tint', hexOfLab(65, (t.a - c.a) * 2.5, (t.b - c.b) * 2.5), `the target leans ${t.b < c.b ? 'cooler' : 'warmer'} (a* b* ${t.a} ${t.b} against ${c.a} ${c.b}); with tintAmount 0.06–0.12`, lean / 6);
+    const dV = t.edgeDark - c.edgeDark;
+    if (dV >= 5)
+        say('vignette', set('vignette', now.vignette, 1, Math.min(0.5, dV / 40)), `the target's edges are ${Math.round(dV)} L* darker against its centre than the frame's`, dV / 6);
+    if (t.meanL < 30 && t.pools - c.pools >= 8 && now.preset !== 'moonlit-spot')
+        out.push({ key: 'preset', set: 'moonlit-spot', size: 99, say: `a dark frame lit in pools: start from the moonlit-spot preset (${scope === 'light' ? 'look set light.preset=moonlit-spot' : `${scope}.preset in src/places.json`}), then the moves below` });
+    return out.sort((x, y) => y.size - x.size);
+}

package/dist/score/measure.js

@@ -0,0 +1,386 @@
+const clamp = (v, lo = 0, hi = 100) => Math.max(lo, Math.min(hi, v));
+const lin = (c) => { const s = c / 255; return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+export function lab(r, g, b) {
+    const R = lin(r), G = lin(g), B = lin(b);
+    const x = (R * 0.4124 + G * 0.3576 + B * 0.1805) / 0.95047, y = R * 0.2126 + G * 0.7152 + B * 0.0722, z = (R * 0.0193 + G * 0.1192 + B * 0.9505) / 1.08883;
+    const fx = f(x), fy = f(y), fz = f(z);
+    return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+export const deltaE = (p, q) => Math.hypot(p[0] - q[0], p[1] - q[1], p[2] - q[2]);
+export function palette(p, k = 6, iterations = 10) {
+    const px = [];
+    for (let i = 0; i < p.width * p.height; i++)
+        px.push(lab(p.data[i * 4], p.data[i * 4 + 1], p.data[i * 4 + 2]));
+    if (!px.length)
+        return [];
+    const sorted = [...px].sort((a, b) => a[0] - b[0]);
+    let centres = Array.from({ length: k }, (_, i) => [...sorted[Math.min(sorted.length - 1, Math.floor(((i + 0.5) / k) * sorted.length))]]);
+    let counts = new Array(k).fill(0);
+    for (let it = 0; it < iterations; it++) {
+        const sum = centres.map(() => [0, 0, 0]);
+        counts = new Array(k).fill(0);
+        for (const c of px) {
+            let best = 0, bd = Infinity;
+            for (let j = 0; j < k; j++) {
+                const d = deltaE(c, centres[j]);
+                if (d < bd) {
+                    bd = d;
+                    best = j;
+                }
+            }
+            counts[best]++;
+            sum[best][0] += c[0];
+            sum[best][1] += c[1];
+            sum[best][2] += c[2];
+        }
+        centres = centres.map((c, j) => (counts[j] ? [sum[j][0] / counts[j], sum[j][1] / counts[j], sum[j][2] / counts[j]] : c));
+    }
+    return centres.map((c, j) => ({ lab: c, weight: counts[j] / px.length })).filter((s) => s.weight > 0).sort((a, b) => b.weight - a.weight);
+}
+export function paletteDistance(a, b) {
+    const one = (x, y) => x.reduce((s, w) => s + w.weight * Math.min(...y.map((v) => deltaE(w.lab, v.lab))), 0);
+    return a.length && b.length ? (one(a, b) + one(b, a)) / 2 : NaN;
+}
+const meanL = (p) => { let s = 0; const n = p.width * p.height; for (let i = 0; i < n; i++)
+    s += lab(p.data[i * 4], p.data[i * 4 + 1], p.data[i * 4 + 2])[0]; return s / n; };
+export function paletteScore(capture, target) {
+    const d = paletteDistance(palette(capture), palette(target));
+    const light = Math.abs(meanL(capture) - meanL(target));
+    return { score: Math.round(clamp(100 - 2.2 * d - 1.0 * light)), delta_e: Math.round(d * 10) / 10, light_gap: Math.round(light * 10) / 10 };
+}
+function grey(p) {
+    const g = [];
+    for (let i = 0; i < p.width * p.height; i++)
+        g.push(0.299 * p.data[i * 4] + 0.587 * p.data[i * 4 + 1] + 0.114 * p.data[i * 4 + 2]);
+    return g;
+}
+function edges(g, w, h) {
+    const e = new Array(w * h).fill(0);
+    for (let y = 1; y < h - 1; y++)
+        for (let x = 1; x < w - 1; x++) {
+            const v = (dx, dy) => g[(y + dy) * w + x + dx];
+            const gx = v(1, -1) + 2 * v(1, 0) + v(1, 1) - v(-1, -1) - 2 * v(-1, 0) - v(-1, 1);
+            const gy = v(-1, 1) + 2 * v(0, 1) + v(1, 1) - v(-1, -1) - 2 * v(0, -1) - v(1, -1);
+            e[y * w + x] = Math.hypot(gx, gy);
+        }
+    return e;
+}
+export function correlation(a, b) {
+    const n = Math.min(a.length, b.length);
+    if (!n)
+        return NaN;
+    let ma = 0, mb = 0;
+    for (let i = 0; i < n; i++) {
+        ma += a[i];
+        mb += b[i];
+    }
+    ma /= n;
+    mb /= n;
+    let sab = 0, saa = 0, sbb = 0;
+    for (let i = 0; i < n; i++) {
+        const x = a[i] - ma, y = b[i] - mb;
+        sab += x * y;
+        saa += x * x;
+        sbb += y * y;
+    }
+    return saa && sbb ? sab / Math.sqrt(saa * sbb) : 0;
+}
+export function layoutScore(capture, target) {
+    const gc = grey(capture), gt = grey(target);
+    const r1 = correlation(gc, gt), r2 = correlation(edges(gc, capture.width, capture.height), edges(gt, target.width, target.height));
+    const s = 0.3 + 0.7 * ((Math.max(0, r1) + Math.max(0, r2)) / 2);
+    return { score: Math.round(clamp(100 * s)), luminance_r: Math.round(r1 * 100) / 100, edge_r: Math.round(r2 * 100) / 100 };
+}
+export function detailShare(p, spread = 18) {
+    const g = grey(p), TX = 16, TY = 9;
+    let busy = 0;
+    for (let ty = 0; ty < TY; ty++)
+        for (let tx = 0; tx < TX; tx++) {
+            let lo = 255, hi = 0;
+            for (let y = Math.floor((ty * p.height) / TY); y < Math.floor(((ty + 1) * p.height) / TY); y++)
+                for (let x = Math.floor((tx * p.width) / TX); x < Math.floor(((tx + 1) * p.width) / TX); x++) {
+                    const v = g[y * p.width + x];
+                    lo = Math.min(lo, v);
+                    hi = Math.max(hi, v);
+                }
+            if (hi - lo > spread)
+                busy++;
+        }
+    return busy / (TX * TY);
+}
+export function densityScore(capture, target) {
+    const a = detailShare(capture), b = detailShare(target);
+    return { score: Math.round(clamp(Math.max(a, b) ? (100 * Math.min(a, b)) / Math.max(a, b) : 100)), capture: Math.round(a * 100) / 100, target: Math.round(b * 100) / 100 };
+}
+export function heroScore(capture, target) {
+    if (!(capture > 0 && target > 0))
+        return NaN;
+    return Math.round(clamp(100 * (1 - Math.abs(Math.log(capture / target)) / Math.LN2)));
+}
+export function changedShare(a, b, step = 12) {
+    const ga = grey(a), gb = grey(b);
+    let n = 0;
+    for (let i = 0; i < ga.length; i++)
+        if (Math.abs(ga[i] - gb[i]) > step)
+            n++;
+    return ga.length ? n / ga.length : 0;
+}
+export function lifeScore(changed, animated) {
+    const parts = [];
+    if (changed !== null)
+        parts.push(100 * Math.min(1, changed / 0.12));
+    if (animated && animated.of)
+        parts.push((100 * animated.n) / animated.of);
+    return parts.length ? Math.round(parts.reduce((a, b) => a + b, 0) / parts.length) : NaN;
+}
+export const AXES = ['composition', 'hero', 'identity', 'palette_light', 'density', 'life'];
+export function axis(measured, judge, why) {
+    const m = measured !== null && Number.isFinite(measured) ? measured : null, j = judge !== null && Number.isFinite(judge) ? judge : null;
+    const score = m !== null && j !== null ? Math.round((m + j) / 2) : m ?? j;
+    return { measured: m, judge: j, score, why };
+}
+export function overall(axes, bar) {
+    const seen = AXES.filter((a) => axes[a].score !== null);
+    const score = seen.length ? Math.round(seen.reduce((s, a) => s + axes[a].score, 0) / seen.length) : null;
+    return { score, observed: seen.length, gaps: seen.filter((a) => axes[a].score < bar) };
+}
+const box3 = (g, w, h) => {
+    const o = new Array(w * h).fill(0);
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            let s = 0, n = 0;
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dx = -1; dx <= 1; dx++) {
+                    const X = x + dx, Y = y + dy;
+                    if (X >= 0 && Y >= 0 && X < w && Y < h) {
+                        s += g[Y * w + X];
+                        n++;
+                    }
+                }
+            o[y * w + x] = s / n;
+        }
+    return o;
+};
+export const HORIZON = { columns: 0.4, band: 0.08, holdsBand: 0.3, deltaE: 14, holds: 0.7 };
+export function horizonRead(p) {
+    const W = p.width, H = p.height;
+    const L = [];
+    for (let i = 0; i < W * H; i++)
+        L.push(lab(p.data[i * 4], p.data[i * 4 + 1], p.data[i * 4 + 2]));
+    const e = edges(grey(p), W, H);
+    const tex = (x, y) => { let s = 0, n = 0; for (let dy = -1; dy <= 1; dy++)
+        for (let dx = -1; dx <= 1; dx++) {
+            const X = x + dx, Y = y + dy;
+            if (X > 0 && Y > 0 && X < W - 1 && Y < H - 1) {
+                s += e[Y * W + X];
+                n++;
+            }
+        } return n ? s / n : 0; };
+    const smooth = 60, rough = 140;
+    const K = Math.max(3, Math.round(H * 0.12)), top = Math.max(2, Math.round(H * 0.03));
+    const found = [];
+    for (let x = 1; x < W - 1; x++) {
+        let sky = [0, 0, 0], skyTex = 0;
+        for (let y = 1; y <= top; y++) {
+            const c = L[y * W + x];
+            sky = [sky[0] + c[0] / top, sky[1] + c[1] / top, sky[2] + c[2] / top];
+            skyTex += tex(x, y) / top;
+        }
+        if (skyTex > smooth)
+            continue;
+        let trend = [0, 0, 0];
+        const ahead = (k) => [sky[0] + trend[0] * k, sky[1] + trend[1] * k, sky[2] + trend[2] * k];
+        const departed = (y, k) => deltaE(L[y * W + x], ahead(k)) > HORIZON.deltaE + k || tex(x, y) > rough;
+        for (let y = top + 1; y < H - K; y++) {
+            const c = L[y * W + x];
+            if (departed(y, 1)) {
+                let held = 0;
+                for (let k = 1; k <= K; k++)
+                    if (departed(y + k, k + 1))
+                        held++;
+                if (held >= HORIZON.holds * K) {
+                    found.push(y);
+                    break;
+                }
+                continue;
+            }
+            trend = [0, 1, 2].map((i) => trend[i] * 0.6 + (c[i] - sky[i]) * 0.4);
+            sky = [c[0], c[1], c[2]];
+        }
+    }
+    const columns = Math.round((found.length / Math.max(1, W - 2)) * 100) / 100;
+    if (found.length < HORIZON.columns * (W - 2))
+        return { at: null, columns, spread: null, why: `sky seen in ${Math.round(columns * 100)}% of the columns: no skyline across the frame` };
+    found.sort((a, b) => a - b);
+    const win = Math.max(2, Math.round(H * HORIZON.band));
+    const count = (y0) => found.filter((v) => v >= y0 && v <= y0 + win).length;
+    let pick = -1;
+    for (let y0 = H - 1; y0 >= 0; y0--)
+        if (count(y0) >= HORIZON.holdsBand * found.length) {
+            pick = y0;
+            break;
+        }
+    if (pick < 0) {
+        const most = Math.max(...found.map((v) => count(v)));
+        return { at: null, columns, spread: Math.round((most / found.length) * 100) / 100, why: `no one skyline: the sky ends at many heights (no band holds ${Math.round(HORIZON.holdsBand * 100)}% of the sky columns)` };
+    }
+    let lo = pick;
+    for (let y0 = Math.max(0, pick - win); y0 <= pick; y0++)
+        if (count(y0) > count(lo))
+            lo = y0;
+    const inBand = found.filter((v) => v >= lo && v <= lo + win);
+    const share = Math.round((inBand.length / found.length) * 100) / 100;
+    return { at: Math.round((inBand[inBand.length >> 1] / H) * 100) / 100, columns, spread: share, why: 'the sky edge' };
+}
+export const horizonOf = (p) => horizonRead(p).at;
+export function subjectOf(p) {
+    const W = p.width, H = p.height, e = edges(grey(p), W, H);
+    let sum = 0, sx = 0, sy = 0;
+    const colMass = new Array(H).fill(0);
+    for (let y = 1; y < H - 1; y++)
+        for (let x = 1; x < W - 1; x++) {
+            const v = e[y * W + x];
+            sum += v;
+            sx += v * x;
+            sy += v * y;
+            colMass[y] += v;
+        }
+    if (!sum)
+        return { x: 0.5, y: 0.5, size: 0 };
+    let acc = 0, lo = 0, hi = H - 1;
+    for (let y = 0; y < H; y++) {
+        acc += colMass[y];
+        if (acc < 0.15 * sum)
+            lo = y;
+        if (acc <= 0.85 * sum)
+            hi = y;
+    }
+    return { x: Math.round((sx / sum / W) * 100) / 100, y: Math.round((sy / sum / H) * 100) / 100, size: Math.round(((hi - lo) / H) * 100) / 100 };
+}
+export function zoomPan(capture, target) {
+    const W = capture.width, H = capture.height;
+    const ec = box3(box3(edges(grey(capture), W, H), W, H), W, H), et = box3(box3(edges(grey(target), target.width, target.height), W, H), W, H);
+    let best = { zoom: 1, pan: { x: 0, y: 0 }, r: -2 }, still = -2;
+    for (const zoom of [0.6, 0.7, 0.8, 0.9, 1, 1.12, 1.25, 1.4, 1.6, 1.8]) {
+        for (let i = -4; i <= 4; i++)
+            for (let k = -4; k <= 4; k++) {
+                const px = i / 20, py = k / 20;
+                const a = [], b = [];
+                for (let y = 0; y < H; y += 2)
+                    for (let x = 0; x < W; x += 2) {
+                        const sx = Math.round(W / 2 + (x - W / 2 - px * W) / zoom), sy = Math.round(H / 2 + (y - H / 2 - py * H) / zoom);
+                        if (sx < 0 || sy < 0 || sx >= W || sy >= H)
+                            continue;
+                        a.push(ec[sy * W + sx]);
+                        b.push(et[y * W + x]);
+                    }
+                if (a.length < (W * H) / 16)
+                    continue;
+                const r = correlation(a, b);
+                if (zoom === 1 && i === 0 && k === 0)
+                    still = r;
+                if (r > best.r + 0.005 || (Math.abs(r - best.r) <= 0.005 && Math.abs(Math.log(zoom)) + Math.hypot(px, py) < Math.abs(Math.log(best.zoom)) + Math.hypot(best.pan.x, best.pan.y)))
+                    best = { zoom, pan: { x: Math.round(px * 100) / 100 || 0, y: Math.round(py * 100) / 100 || 0 }, r: Math.round(r * 100) / 100 };
+            }
+    }
+    if (best.r - still < (still < ZOOM_PAN_MIN_GAIN.alikeAt ? ZOOM_PAN_MIN_GAIN.apart : ZOOM_PAN_MIN_GAIN.alike))
+        return { zoom: 1, pan: { x: 0, y: 0 }, r: Math.round(still * 100) / 100 };
+    return best;
+}
+export const ZOOM_PAN_MIN_GAIN = { alikeAt: 0.4, alike: 0.05, apart: 0.1 };
+const pc = (v) => `${Math.round(v * 100)}%`;
+export function vanishingPoint(p) {
+    const W = p.width, H = p.height, g = grey(p);
+    const pts = [];
+    for (let y = 1; y < H - 1; y++)
+        for (let x = 1; x < W - 1; x++) {
+            const v = (ox, oy) => g[(y + oy) * W + x + ox];
+            const gx = v(1, -1) + 2 * v(1, 0) + v(1, 1) - v(-1, -1) - 2 * v(-1, 0) - v(-1, 1);
+            const gy = v(-1, 1) + 2 * v(0, 1) + v(1, 1) - v(-1, -1) - 2 * v(0, -1) - v(1, -1);
+            const m = Math.hypot(gx, gy);
+            if (m < 60)
+                continue;
+            const dx = -gy / m, dy = gx / m;
+            const ang = Math.abs(Math.atan2(dy, dx)) % Math.PI;
+            const off = Math.min(ang, Math.abs(ang - Math.PI / 2), Math.abs(Math.PI - ang));
+            if (off < (12 * Math.PI) / 180)
+                continue;
+            pts.push({ x, y, dx, dy, m });
+        }
+    if (pts.length < 40)
+        return null;
+    const score = (cx, cy) => {
+        let s = 0;
+        for (const q of pts) {
+            const ux = cx - q.x, uy = cy - q.y, d = Math.hypot(ux, uy);
+            if (d < 3)
+                continue;
+            const c = Math.abs((ux * q.dx + uy * q.dy) / d);
+            if (c > 0.985)
+                s += q.m * (c - 0.985) / 0.015;
+        }
+        return s;
+    };
+    const step = Math.max(2, Math.round(W / 40));
+    let best = { x: 0, y: 0, s: -1 };
+    for (let cy = 0; cy < H; cy += step)
+        for (let cx = 0; cx < W; cx += step) {
+            const sc = score(cx, cy);
+            if (sc > best.s)
+                best = { x: cx, y: cy, s: sc };
+        }
+    for (let cy = best.y - step; cy <= best.y + step; cy++)
+        for (let cx = best.x - step; cx <= best.x + step; cx++) {
+            const sc = score(cx, cy);
+            if (sc > best.s)
+                best = { x: cx, y: cy, s: sc };
+        }
+    let on = 0, all = 0;
+    for (const q of pts) {
+        all += q.m;
+        const ux = best.x - q.x, uy = best.y - q.y, d = Math.hypot(ux, uy);
+        if (d >= 3 && Math.abs((ux * q.dx + uy * q.dy) / d) > 0.985)
+            on += q.m;
+    }
+    const strength = all ? on / all : 0;
+    return strength >= VANISH_MIN ? { x: Math.round((best.x / W) * 100) / 100, y: Math.round((best.y / H) * 100) / 100, strength: Math.round(strength * 100) / 100 } : null;
+}
+export const VANISH_MIN = 0.15;
+export function cameraDelta(capture, target, hero = { capture: null, target: null }) {
+    const hrC = horizonRead(capture), hrT = horizonRead(target), hc = hrC.at, ht = hrT.at, sc = subjectOf(capture), st = subjectOf(target), zp = zoomPan(capture, target);
+    const moves = [];
+    const inside = (v) => !!v && v.x >= 0.1 && v.x <= 0.9 && v.y >= 0.1 && v.y <= 0.9;
+    const vc = vanishingPoint(capture), vt = vanishingPoint(target);
+    const vanish = inside(vc) && inside(vt) ? { capture: { x: vc.x, y: vc.y }, target: { x: vt.x, y: vt.y } } : null;
+    const heroBoth = hero.capture !== null && hero.target !== null && hero.capture > 0 && hero.target > 0 ? { capture: hero.capture, target: hero.target } : null;
+    if (heroBoth) {
+        const k = heroBoth.capture / heroBoth.target;
+        if (k > 1.15)
+            moves.push({ size: Math.log(k), say: `the hero fills ${pc(heroBoth.capture)} of the frame height, the target ${pc(heroBoth.target)}: pull the camera back (or widen the lens) about ×${(Math.round(k * 10) / 10).toFixed(1)}` });
+        else if (k < 0.87)
+            moves.push({ size: Math.log(1 / k), say: `the hero fills ${pc(heroBoth.capture)} of the frame height, the target ${pc(heroBoth.target)}: move the camera in (or narrow the lens) about ×${(Math.round((1 / k) * 10) / 10).toFixed(1)}` });
+    }
+    else if (zp.zoom >= 1.12)
+        moves.push({ size: Math.log(zp.zoom), say: `the target is framed tighter: move the camera in (or narrow the lens) about ×${zp.zoom.toFixed(2)}` });
+    else if (zp.zoom <= 0.9)
+        moves.push({ size: Math.log(1 / zp.zoom), say: `the target is framed wider: pull the camera back (or widen the lens) about ×${(1 / zp.zoom).toFixed(2)}` });
+    const dh = hc !== null && ht !== null ? ht - hc : 0;
+    if (!vanish && hc !== null && ht !== null && Math.abs(dh) >= 0.06)
+        moves.push({ size: Math.abs(dh) * 2, say: `the horizon sits ${pc(hc)} down the frame, the target's ${pc(ht)}: tilt the camera ${dh > 0 ? 'up' : 'down'} (or ${dh > 0 ? 'lower' : 'raise'} it) until the horizon is at ${pc(ht)}` });
+    if (!vanish && Math.abs(zp.pan.x) >= 0.05)
+        moves.push({ size: Math.abs(zp.pan.x) * 1.5, say: `the scene must move ${zp.pan.x > 0 ? 'right' : 'left'} about ${pc(Math.abs(zp.pan.x))} of the frame width to sit where the target has it: pan (or offset the follow) ${zp.pan.x > 0 ? 'left' : 'right'}` });
+    if (!vanish && Math.abs(zp.pan.y) >= 0.05 && Math.abs(dh) < 0.06)
+        moves.push({ size: Math.abs(zp.pan.y) * 1.5, say: `the scene must move ${zp.pan.y > 0 ? 'down' : 'up'} about ${pc(Math.abs(zp.pan.y))} of the frame height: tilt ${zp.pan.y > 0 ? 'up' : 'down'}` });
+    const dx = st.x - sc.x;
+    if (!vanish && Math.abs(dx) >= 0.08 && Math.abs(zp.pan.x) < 0.05)
+        moves.push({ size: Math.abs(dx), say: `the picture's weight sits ${pc(sc.x)} across, the target's ${pc(st.x)}: put the subject ${dx > 0 ? 'further right' : 'further left'} (a follow offset, or turn the camera ${dx > 0 ? 'left' : 'right'})` });
+    if (sc.size && st.size && !heroBoth && Math.abs(Math.log(sc.size / st.size)) > Math.log(1.3) && zp.zoom > 0.9 && zp.zoom < 1.12)
+        moves.push({ size: Math.abs(Math.log(sc.size / st.size)) / 2, say: `the detail spans ${pc(sc.size)} of the frame height, the target's ${pc(st.size)}: ${sc.size > st.size ? 'crop wider (pull back)' : 'crop tighter (move in)'}` });
+    const unseen = hc === null || ht === null ? `horizon not observed in the ${hc === null && ht === null ? 'capture or the target' : hc === null ? 'capture' : 'target'} (${(hc === null ? hrC : hrT).why}): no tilt advised from it` : undefined;
+    if (vanish && Math.hypot(vanish.target.x - vanish.capture.x, vanish.target.y - vanish.capture.y) >= 0.04) {
+        const dxv = vanish.target.x - vanish.capture.x, dyv = vanish.target.y - vanish.capture.y;
+        moves.push({ size: Math.hypot(dxv, dyv) * 2.5, say: `the lines meet ${pc(vanish.capture.x)} across, ${pc(vanish.capture.y)} down; the target's at ${pc(vanish.target.x)}, ${pc(vanish.target.y)}: ${Math.abs(dxv) >= 0.03 ? `turn ${dxv > 0 ? 'left' : 'right'}` : ''}${Math.abs(dxv) >= 0.03 && Math.abs(dyv) >= 0.03 ? ' and ' : ''}${Math.abs(dyv) >= 0.03 ? `tilt ${dyv > 0 ? 'up' : 'down'}` : ''} until they meet there` });
+    }
+    return { horizon: { capture: hc, target: ht, ...(unseen ? { why: unseen } : {}) }, subject: { capture: sc, target: st }, zoom: zp.zoom, pan: zp.pan, fit_r: zp.r, hero: heroBoth, vanish, moves: moves.sort((a, b) => b.size - a.size).map((m) => m.say) };
+}

package/dist/score/vision.js

@@ -0,0 +1,59 @@
+export const VISION_DEFAULT_MODEL = 'google/gemini-2.5-flash';
+const URL = 'https://openrouter.ai/api/v1/chat/completions';
+export const VISION_PROMPT = `You compare a CANDIDATE frame from a game against a REFERENCE picture of what the frame was meant to look like.
+Score how closely the candidate matches the reference, 0-100 on each axis (100 = indistinguishable in that respect, 90 = a close match with small differences, 50 = clearly different):
+- composition: camera position, angle, framing and where the main masses sit
+- hero: the main character's size in frame and pose
+- identity: the characters, creatures, machines and places are recognisably the same designs
+- palette_light: colours, light direction, time of day, mood
+- density: amount of detail, props, texture and life in the scene
+- life: how alive the scene looks (people and creatures doing things, motion cues)
+Reply with JSON only: {"composition":n,"hero":n,"identity":n,"palette_light":n,"density":n,"life":n,"gaps":["the biggest differences, short"]}`;
+export function parseVision(text) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (!m)
+        return null;
+    try {
+        const j = JSON.parse(m[0]);
+        const axes = {};
+        for (const k of ['composition', 'hero', 'identity', 'palette_light', 'density', 'life']) {
+            const v = Number(j[k]);
+            if (Number.isFinite(v) && v >= 0 && v <= 100)
+                axes[k] = Math.round(v);
+        }
+        return { axes, gaps: Array.isArray(j.gaps) ? j.gaps.filter((g) => typeof g === 'string').slice(0, 6) : [] };
+    }
+    catch {
+        return null;
+    }
+}
+export async function visionJudge(reference, candidate, env = process.env) {
+    const key = env.OPENROUTER_API_KEY;
+    if (!key)
+        return null;
+    const model = env.FUNTOOLS_VISION_MODEL || VISION_DEFAULT_MODEL;
+    const url = (p) => `data:${p.type};base64,${Buffer.from(p.bytes).toString('base64')}`;
+    try {
+        const res = await fetch(URL, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model, temperature: 0, max_tokens: 400,
+                messages: [{ role: 'user', content: [
+                            { type: 'text', text: VISION_PROMPT },
+                            { type: 'text', text: 'REFERENCE:' }, { type: 'image_url', image_url: { url: url(reference) } },
+                            { type: 'text', text: 'CANDIDATE:' }, { type: 'image_url', image_url: { url: url(candidate) } },
+                        ] }],
+            }),
+            signal: AbortSignal.timeout(60_000),
+        });
+        if (!res.ok)
+            return { model, axes: {}, gaps: [], error: `the judge answered ${res.status}` };
+        const body = await res.json();
+        const parsed = parseVision(body.choices?.[0]?.message?.content ?? '');
+        return parsed ? { model, ...parsed } : { model, axes: {}, gaps: [], error: 'the judge did not answer in JSON' };
+    }
+    catch (e) {
+        return { model, axes: {}, gaps: [], error: `the judge was not reached: ${e.message.split('\n')[0]}` };
+    }
+}