Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(rig-doctor): add a zero-network, browser-only Engine QA partial grade
nirholas62ea70a173cc
diff --git a/src/engine-qa-client.js b/src/engine-qa-client.jsnew file mode 100644index 000000000..fe650b793--- /dev/null+++ b/src/engine-qa-client.js@@ -0,0 +1,285 @@+// Engine QA, computed entirely in the browser: zero network, zero upload.+//+// Rig Doctor's whole privacy claim ("No bytes are sent to any server... works+// with the network disconnected") rules out posting a visitor's file to+// /api/3d/engine-qa for the full server-side grade (api/_lib/engine-qa.js),+// which needs Node-only dependencies (gltf-transform's NodeIO, the manifold+// print pipeline) anyway. This module grades the three checks that are pure+// math over bytes already in memory: draw calls, material count, and texel+// density. It shares its thresholds and verdict logic with the server grader+// via api/_lib/engine-qa-core.js, so the two can never disagree on a verdict.+//+// What it deliberately does NOT grade (returned as `skip`, never fabricated):+// triangleBudget needs a real LOD chain, which needs real decimation work+// (meshoptimizer), heavy enough that even the server gates+// it behind its own rate limit. Rig Doctor's own offer to+// build one is an explicit, visible upload: see+// rig-doctor-page.js's `requestFullEngineQa`.+// collider needs the manifold/watertight analyzer, which is a+// server-only dependency chain (api/_lib/print/*). Same+// explicit-upload offer covers this.+//+// Parses the raw GLB with rig-report.js's own byte-level reader rather than a+// second JSON/BIN parser, so the two analyses of the same file can never+// disagree about where the chunks are.++import { readGlbJson } from './rig-report.js';+import {+ ENGINE_QA_VERSION,+ ENGINE_QA_THRESHOLDS,+ worstVerdict,+ verdictFromBand,+} from '../api/_lib/engine-qa-core.js';++const MODE_TRIANGLES = 4;+const COMPONENT_FLOAT = 5126;+const INDEX_READERS = {+ 5121: (dv, o) => dv.getUint8(o),+ 5123: (dv, o) => dv.getUint16(o, true),+ 5125: (dv, o) => dv.getUint32(o, true),+};++function sliceBin(buffer, jsonBytes) {+ const c1Offset = 20 + jsonBytes;+ if (c1Offset + 8 > buffer.byteLength) return null;+ const view = new DataView(buffer);+ const c1Len = view.getUint32(c1Offset, true);+ return new Uint8Array(buffer, c1Offset + 8, c1Len);+}++// Only FLOAT VEC2/VEC3 accessors (positions and UVs are FLOAT in every mesh+// this needs to measure); anything else, including quantized attributes,+// returns null so the caller skips that primitive's area contribution rather+// than misreading it.+function readFloatAccessor(json, bin, accessorIndex, numComponents) {+ const accessor = json.accessors?.[accessorIndex];+ if (!accessor || accessor.sparse || accessor.componentType !== COMPONENT_FLOAT) return null;+ if (typeof accessor.bufferView !== 'number' || !bin) return null;+ const view = json.bufferViews?.[accessor.bufferView];+ if (!view) return null;+ const stride = view.byteStride || numComponents * 4;+ const base = (view.byteOffset || 0) + (accessor.byteOffset || 0);+ if (base + stride * Math.max(0, accessor.count - 1) + numComponents * 4 > bin.byteLength) return null;+ const dv = new DataView(bin.buffer, bin.byteOffset + base);+ return {+ count: accessor.count,+ get(i, out) {+ const o = i * stride;+ for (let c = 0; c < numComponents; c++) out[c] = dv.getFloat32(o + c * 4, true);+ return out;+ },+ };+}++function readIndexAccessor(json, bin, accessorIndex) {+ const accessor = json.accessors?.[accessorIndex];+ if (!accessor || accessor.sparse) return null;+ const reader = INDEX_READERS[accessor.componentType];+ if (!reader || typeof accessor.bufferView !== 'number' || !bin) return null;+ const view = json.bufferViews?.[accessor.bufferView];+ if (!view) return null;+ const compBytes = accessor.componentType === 5125 ? 4 : accessor.componentType === 5123 ? 2 : 1;+ const stride = view.byteStride || compBytes;+ const base = (view.byteOffset || 0) + (accessor.byteOffset || 0);+ if (base + stride * Math.max(0, accessor.count - 1) + compBytes > bin.byteLength) return null;+ const dv = new DataView(bin.buffer, bin.byteOffset + base);+ return { count: accessor.count, get: (i) => reader(dv, i * stride) };+}++function mat4Identity() {+ return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];+}++function mat4Multiply(a, b) {+ const out = new Array(16);+ for (let col = 0; col < 4; col++) {+ for (let row = 0; row < 4; row++) {+ out[col * 4 + row] =+ a[0 * 4 + row] * b[col * 4 + 0] ++ a[1 * 4 + row] * b[col * 4 + 1] ++ a[2 * 4 + row] * b[col * 4 + 2] ++ a[3 * 4 + row] * b[col * 4 + 3];+ }+ }+ return out;+}++// Column-major, matching glTF's own convention and api/_lib/engine-qa.js's+// transformPoint helper, so a mesh graded on both sides never gets two+// different world-space triangle areas for the same transform.+function localMatrix(node) {+ if (Array.isArray(node.matrix) && node.matrix.length === 16) return node.matrix;+ const [tx, ty, tz] = node.translation || [0, 0, 0];+ const [x, y, z, w] = node.rotation || [0, 0, 0, 1];+ const [sx, sy, sz] = node.scale || [1, 1, 1];+ const r00 = 1 - 2 * (y * y + z * z), r01 = 2 * (x * y - z * w), r02 = 2 * (x * z + y * w);+ const r10 = 2 * (x * y + z * w), r11 = 1 - 2 * (x * x + z * z), r12 = 2 * (y * z - x * w);+ const r20 = 2 * (x * z - y * w), r21 = 2 * (y * z + x * w), r22 = 1 - 2 * (x * x + y * y);+ return [+ r00 * sx, r10 * sx, r20 * sx, 0,+ r01 * sy, r11 * sy, r21 * sy, 0,+ r02 * sz, r12 * sz, r22 * sz, 0,+ tx, ty, tz, 1,+ ];+}++function transformPoint(m, x, y, z) {+ const w = m[3] * x + m[7] * y + m[11] * z + m[15] || 1;+ return [+ (m[0] * x + m[4] * y + m[8] * z + m[12]) / w,+ (m[1] * x + m[5] * y + m[9] * z + m[13]) / w,+ (m[2] * x + m[6] * y + m[10] * z + m[14]) / w,+ ];+}++function triangleArea(a, b, c) {+ const abx = b[0] - a[0], aby = b[1] - a[1], abz = b[2] - a[2];+ const acx = c[0] - a[0], acy = c[1] - a[1], acz = c[2] - a[2];+ const cx = aby * acz - abz * acy, cy = abz * acx - abx * acz, cz = abx * acy - aby * acx;+ return 0.5 * Math.sqrt(cx * cx + cy * cy + cz * cz);+}++function triangleAreaUv(a, b, c) {+ return Math.abs((b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1])) / 2;+}++function firstTextureRef(material) {+ if (!material) return null;+ return (+ material.pbrMetallicRoughness?.baseColorTexture ??+ material.normalTexture ??+ material.pbrMetallicRoughness?.metallicRoughnessTexture ??+ material.emissiveTexture ??+ material.occlusionTexture ??+ null+ );+}++// Decode an embedded (bufferView-backed) image to get its pixel size, via the+// browser's own image decoder: no manual PNG/JPEG header parsing, and it+// never leaves the tab because the bytes are already local. A `uri`-backed+// image (external reference) is skipped rather than fetched: fetching it+// would be this module's only network request, and the one guarantee Rig+// Doctor makes is that there isn't one.+async function textureSize(json, bin, textureRef) {+ const texture = json.textures?.[textureRef?.index];+ const image = json.images?.[texture?.source];+ if (!image || typeof image.bufferView !== 'number' || !bin) return null;+ const view = json.bufferViews?.[image.bufferView];+ if (!view) return null;+ const start = (view.byteOffset || 0);+ const bytes = bin.subarray(start, start + view.byteLength);+ const blob = new Blob([bytes], { type: image.mimeType || 'image/png' });+ try {+ const bitmap = await createImageBitmap(blob);+ const size = [bitmap.width, bitmap.height];+ bitmap.close?.();+ return size;+ } catch {+ return null;+ }+}++/**+ * Grade the checks that are pure math over bytes already in memory: draw+ * calls, material count, and texel density. `triangleBudget` and `collider`+ * come back `skip` with a reason pointing at the explicit upload path.+ *+ * @param {ArrayBuffer} buffer a GLB already read into memory (FileReader result)+ */+export async function gradeEngineQaClient(buffer) {+ const { json, jsonBytes } = readGlbJson(buffer);+ const bin = sliceBin(buffer, jsonBytes);++ const materialCount = (json.materials || []).length;+ const textureCount = (json.textures || []).length;++ const sceneIndex = json.scene ?? 0;+ const rootIndices = json.scenes?.[sceneIndex]?.nodes ?? [];+ const seen = new Set();+ let drawCalls = 0;+ let totalWorldAreaM2 = 0;+ let totalUvAreaTexels = 0;+ let anyMeasured = false;++ const visit = async (nodeIndex, parentMatrix) => {+ if (seen.has(nodeIndex)) return;+ seen.add(nodeIndex);+ const node = json.nodes?.[nodeIndex];+ if (!node) return;+ const matrix = mat4Multiply(parentMatrix, localMatrix(node));++ if (typeof node.mesh === 'number') {+ for (const prim of json.meshes?.[node.mesh]?.primitives || []) {+ if ((prim.mode ?? MODE_TRIANGLES) !== MODE_TRIANGLES) continue;+ drawCalls += 1;++ const posAcc = prim.attributes?.POSITION;+ const uvAcc = prim.attributes?.TEXCOORD_0;+ const material = json.materials?.[prim.material];+ const textureRef = firstTextureRef(material);+ if (posAcc == null || uvAcc == null || !textureRef) continue;++ const position = readFloatAccessor(json, bin, posAcc, 3);+ const uv = readFloatAccessor(json, bin, uvAcc, 2);+ if (!position || !uv) continue;+ const size = await textureSize(json, bin, textureRef);+ if (!size) continue;+ const [texWidth, texHeight] = size;++ const index = prim.indices != null ? readIndexAccessor(json, bin, prim.indices) : null;+ const count = index ? index.count : position.count;+ const p = [0, 0, 0], uvA = [0, 0], uvB = [0, 0], uvC = [0, 0];+ for (let i = 0; i + 2 < count; i += 3) {+ const ia = index ? index.get(i) : i;+ const ib = index ? index.get(i + 1) : i + 1;+ const ic = index ? index.get(i + 2) : i + 2;++ const a = transformPoint(matrix, ...position.get(ia, p));+ const b = transformPoint(matrix, ...position.get(ib, p));+ const c = transformPoint(matrix, ...position.get(ic, p));+ totalWorldAreaM2 += triangleArea(a, b, c);++ uv.get(ia, uvA);+ uv.get(ib, uvB);+ uv.get(ic, uvC);+ totalUvAreaTexels += triangleAreaUv(uvA, uvB, uvC) * texWidth * texHeight;+ anyMeasured = true;+ }+ }+ }+ for (const childIndex of node.children || []) await visit(childIndex, matrix);+ };+ for (const rootIndex of rootIndices) await visit(rootIndex, mat4Identity());++ const drawCallsCheck = { value: drawCalls, verdict: verdictFromBand(drawCalls, ENGINE_QA_THRESHOLDS.drawCalls), thresholds: ENGINE_QA_THRESHOLDS.drawCalls };+ const materialCountCheck = { value: materialCount, verdict: verdictFromBand(materialCount, ENGINE_QA_THRESHOLDS.materialCount), thresholds: ENGINE_QA_THRESHOLDS.materialCount };++ let texelDensityCheck;+ if (anyMeasured && totalWorldAreaM2 > 0) {+ const pxPerMeter = Math.round(Math.sqrt(totalUvAreaTexels / totalWorldAreaM2));+ const { minPxPerMeter, maxPxPerMeter } = ENGINE_QA_THRESHOLDS.texelDensity;+ const verdict = pxPerMeter < minPxPerMeter ? 'fail' : pxPerMeter > maxPxPerMeter ? 'warn' : 'pass';+ texelDensityCheck = { value: pxPerMeter, verdict, thresholds: ENGINE_QA_THRESHOLDS.texelDensity };+ } else {+ texelDensityCheck = { value: null, verdict: 'skip', reason: 'no UV-mapped texture found to measure' };+ }++ const checks = {+ drawCalls: drawCallsCheck,+ materialCount: materialCountCheck,+ texelDensity: texelDensityCheck,+ triangleBudget: { value: null, verdict: 'skip', reason: 'requires building a real LOD chain; use "Check LOD & collider fitness" to run it' },+ collider: { value: null, verdict: 'skip', reason: 'requires the server-side manifold analyzer; use "Check LOD & collider fitness" to run it' },+ };++ return {+ version: ENGINE_QA_VERSION,+ overall: worstVerdict(Object.values(checks).map((c) => c.verdict)),+ materialCount,+ textureCount,+ drawCalls,+ partial: true,+ checks,+ };+}diff --git a/tests/engine-qa-client.test.js b/tests/engine-qa-client.test.jsnew file mode 100644index 000000000..71cc1efb7--- /dev/null+++ b/tests/engine-qa-client.test.js@@ -0,0 +1,140 @@+// src/engine-qa-client.js: the browser-only partial grade Rig Doctor runs+// with zero network. There is no real browser in this suite, so the one+// browser-only primitive it needs (createImageBitmap) is polyfilled with a+// real PNG decode (sharp), exactly like tests/engine-qa.test.js polyfills the+// bytes for the server-side grader. Everything else, including the GLB+// parsing and the matrix/area math, is the real module, unmodified.+import { describe, it, expect, beforeAll } from 'vitest';+import { Document, NodeIO } from '@gltf-transform/core';+import { gradeEngineQaClient } from '../src/engine-qa-client.js';++function cubeMesh(size) {+ const h = size / 2;+ const positions = [+ -h, -h, -h, h, -h, -h, h, h, -h, -h, h, -h,+ -h, -h, h, h, -h, h, h, h, h, -h, h, h,+ ];+ const faces = [+ [0, 2, 1], [0, 3, 2], [4, 5, 6], [4, 6, 7],+ [0, 1, 5], [0, 5, 4], [3, 7, 6], [3, 6, 2],+ [0, 4, 7], [0, 7, 3], [1, 2, 6], [1, 6, 5],+ ];+ return { positions, indices: faces.flat() };+}++function planeMesh(width, depth) {+ const hw = width / 2, hd = depth / 2;+ return {+ positions: [-hw, 0, -hd, hw, 0, -hd, hw, 0, hd, -hw, 0, hd],+ indices: [0, 2, 1, 0, 3, 2],+ uv: [0, 0, 1, 0, 1, 1, 0, 1],+ };+}++let pngCache = new Map();+async function pngBuffer(width, height) {+ const key = `${width}x${height}`;+ if (!pngCache.has(key)) {+ const sharp = (await import('sharp')).default;+ pngCache.set(key, sharp({ create: { width, height, channels: 4, background: { r: 128, g: 128, b: 128, alpha: 1 } } }).png().toBuffer());+ }+ return pngCache.get(key);+}++async function buildGlbArrayBuffer(parts) {+ const doc = new Document();+ const buffer = doc.createBuffer();+ const scene = doc.createScene('scene');+ const materials = new Map();+ const textures = new Map();++ for (const [i, part] of parts.entries()) {+ const position = doc.createAccessor().setType('VEC3').setArray(new Float32Array(part.positions)).setBuffer(buffer);+ const index = doc.createAccessor().setType('SCALAR').setArray(new Uint32Array(part.indices)).setBuffer(buffer);+ const prim = doc.createPrimitive().setAttribute('POSITION', position).setIndices(index);++ if (part.uv) {+ const uv = doc.createAccessor().setType('VEC2').setArray(new Float32Array(part.uv)).setBuffer(buffer);+ prim.setAttribute('TEXCOORD_0', uv);+ }++ const materialKey = part.materialKey ?? `material-${i}`;+ if (!materials.has(materialKey)) {+ const material = doc.createMaterial(materialKey);+ if (part.textureSize) {+ const textureKey = `${materialKey}:${part.textureSize.join('x')}`;+ if (!textures.has(textureKey)) {+ const [w, h] = part.textureSize;+ const image = await pngBuffer(w, h);+ textures.set(textureKey, doc.createTexture(textureKey).setMimeType('image/png').setImage(new Uint8Array(image)));+ }+ material.setBaseColorTexture(textures.get(textureKey));+ }+ materials.set(materialKey, material);+ }+ prim.setMaterial(materials.get(materialKey));++ const mesh = doc.createMesh(`mesh-${i}`).addPrimitive(prim);+ const node = doc.createNode(`node-${i}`).setMesh(mesh);+ scene.addChild(node);+ }++ const bytes = await new NodeIO().writeBinary(doc);+ return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);+}++beforeAll(() => {+ // eslint-disable-next-line no-undef+ globalThis.createImageBitmap = async (blob) => {+ const sharp = (await import('sharp')).default;+ const buf = Buffer.from(await blob.arrayBuffer());+ const meta = await sharp(buf).metadata();+ return { width: meta.width, height: meta.height, close() {} };+ };+});++describe('gradeEngineQaClient', () => {+ it('grades draw calls and material count from real GLB bytes with no texture', async () => {+ const buffer = await buildGlbArrayBuffer([{ ...cubeMesh(0.4) }]);+ const report = await gradeEngineQaClient(buffer);++ expect(report.partial).toBe(true);+ expect(report.drawCalls).toBe(1);+ expect(report.materialCount).toBe(1);+ expect(report.checks.drawCalls.verdict).toBe('pass');+ expect(report.checks.materialCount.verdict).toBe('pass');+ });++ it('counts one draw call per node+primitive and flags the warn band', async () => {+ const parts = Array.from({ length: 25 }, () => ({ ...cubeMesh(0.1) }));+ const buffer = await buildGlbArrayBuffer(parts);+ const report = await gradeEngineQaClient(buffer);++ expect(report.drawCalls).toBe(25);+ expect(report.checks.drawCalls.verdict).toBe('warn');+ });++ it('skips texel density when nothing is UV-mapped to a texture', async () => {+ const buffer = await buildGlbArrayBuffer([{ ...cubeMesh(0.4) }]);+ const report = await gradeEngineQaClient(buffer);+ expect(report.checks.texelDensity.verdict).toBe('skip');+ expect(report.checks.texelDensity.value).toBeNull();+ });++ it('measures texel density from real UV + decoded-image data, matching the closed form', async () => {+ const buffer = await buildGlbArrayBuffer([{ ...planeMesh(1, 1), textureSize: [512, 512] }]);+ const report = await gradeEngineQaClient(buffer);+ // sqrt(512*512 / (1*1)) = 512+ expect(report.checks.texelDensity.value).toBeCloseTo(512, 0);+ expect(report.checks.texelDensity.verdict).toBe('pass');+ });++ it('always skips triangleBudget and collider with an actionable reason, matching the explicit-upload design', async () => {+ const buffer = await buildGlbArrayBuffer([{ ...cubeMesh(0.4) }]);+ const report = await gradeEngineQaClient(buffer);+ expect(report.checks.triangleBudget.verdict).toBe('skip');+ expect(report.checks.collider.verdict).toBe('skip');+ expect(report.checks.triangleBudget.reason).toMatch(/LOD/);+ expect(report.checks.collider.reason).toMatch(/manifold/);+ });+});