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): report skin-weight health for non-humanoid rigs
nirholasa7906b7c9b29
diff --git a/docs/rig-doctor.md b/docs/rig-doctor.mdindex 4888c945f..8bdcf3ceb 100644--- a/docs/rig-doctor.md+++ b/docs/rig-doctor.md@@ -47,6 +47,10 @@ One of two things is true:- **No skinned mesh.** There is no skin binding a mesh to a skeleton, so no clip can deform anything. The model renders as a static prop and every animation affordance is hidden. Fix it by re-exporting with skinning enabled, or by running the mesh through the auto-rigger (`POST /api/forge?action=rig` with a `glb_url`).- **Under the joint floor.** Fewer than **8** joints mapped to the canonical set. Below that threshold a retargeted clip moves a limb or two on an otherwise frozen statue, which reads worse than not animating at all, so the platform substitutes the default rig instead.+### Non-humanoid rigs++A quadruped, a creature, or a prop rigged by [`workers/rig-nonhuman`](https://github.com/nirholas/three.ws/tree/main/workers/rig-nonhuman) (UniRig + SkinTokens) or the [AniGen](./forge.md) Forge lane has no Mixamo-shaped skeleton to score against, so it always lands in **Will not animate** here: zero canonical joints is the correct, expected result for a mesh the clip library was never going to retarget onto in the first place. Canonical coverage cannot tell you whether a rig like that is actually sound, so the **Skin weights** stat answers the real question instead: how many joints influence the single heaviest-weighted vertex (**max influences**), and how many of the mesh's skinned vertices came back with no joint influence at all (**unweighted vertices**). A model with zero unweighted vertices is fully deformable by its own predicted skeleton even though it will never drive a three.ws clip; a nonzero count means the skinning step missed geometry and that part of the mesh will not move under any skeleton, humanoid or not.+---## Coverage: which limbs will move@@ -187,6 +191,8 @@ console.log(report.verdict.headline); // one sentence you can printconsole.log(report.skeleton.convention); // { id: 'mixamo', label: 'Mixamo', … }console.log(report.skeleton.mapped); // 52console.log(report.skeleton.unmapped); // joint names with no canonical form+console.log(report.skeleton.maxInfluences); // heaviest per-vertex joint count, e.g. 4+console.log(report.skeleton.unweightedVertices); // skinned vertices with no joint influence at allfor (const g of report.skeleton.groups) {if (!g.driven) console.log(`${g.label} frozen, missing ${g.missingKey.join(', ')}`);diff --git a/src/rig-doctor-page.js b/src/rig-doctor-page.jsindex 2e0b6d0bc..84962d602 100644--- a/src/rig-doctor-page.js+++ b/src/rig-doctor-page.js@@ -372,12 +372,27 @@ function renderStats(report) {['Convention', report.skeleton.convention.label, report.skeleton.convention.evidence],['Triangles', report.geometry.triangles.toLocaleString(), `${report.geometry.vertices.toLocaleString()} vertices across ${report.geometry.primitives} primitives`],['Joints', String(report.skeleton.jointCount), `${report.skeleton.mapped} recognised, ${report.skeleton.unmapped.length} not`],+ ];+ // Skin-weight health has no canonical-bone requirement, so it is the one+ // drivability signal a non-humanoid rig (UniRig/SkinTokens, AniGen) still+ // gets: a creature or prop maps zero canonical joints by design, but its+ // vertices should still all carry a joint influence.+ if (report.skeleton.skinnedVertices > 0) {+ rows.push([+ 'Skin weights',+ `${report.skeleton.maxInfluences} max influences`,+ report.skeleton.unweightedVertices > 0+ ? `${report.skeleton.unweightedVertices} of ${report.skeleton.skinnedVertices} vertices have no joint influence at all`+ : `All ${report.skeleton.skinnedVertices} skinned vertices have at least one joint influence`,+ ]);+ }+ rows.push(['Materials', String(report.counts.materials), `${report.counts.textures} textures, ${formatBytes(report.textureBytes)}`],['Blendshapes', String(report.morphs.total), report.morphs.lipSync ? `${report.morphs.visemeCount} visemes, lip-sync ready` : 'No visemes, so no lip-sync'],['Embedded clips', String(report.animations.length), report.animations.length ? report.animations.map((a) => a.name).slice(0, 4).join(', ') : 'None; the library supplies the motion'],['Extensions', report.extensions.length ? String(report.extensions.length) : 'none', report.extensions.length ? report.extensions.join(', ') : 'Plain glTF 2.0'],['File', formatBytes(report.bytes), `${formatBytes(report.jsonBytes)} JSON, ${formatBytes(report.binBytes)} binary`],- ];+ );for (const [term, value, tip] of rows) {const wrap = document.createElement('div');wrap.className = 'rd-stat';diff --git a/src/rig-report.js b/src/rig-report.jsindex 84b8a5b9c..4650efdff 100644--- a/src/rig-report.js+++ b/src/rig-report.js@@ -213,6 +213,103 @@ function jointNodeIndices(json) {return set;}+// Slice the BIN chunk out of a GLB ArrayBuffer, the same chunk-1 offset math+// glb-canonicalize.js's canonicalizeGLBBones uses: 20 bytes of header + the+// (already 4-byte-padded) JSON chunk length lands exactly on chunk 1's own+// 8-byte length/type header. Returns null for a file with no BIN chunk at all+// (a skinless, texture-free, or data-URI-only GLB).+function readGlbBin(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);+}++const ACCESSOR_COMPONENT_BYTES = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };+// Divisors for KHR-normalized integer accessors (glTF 2.0 §3.6.2.3): an+// UNSIGNED_BYTE weight of 255 means 1.0, an UNSIGNED_SHORT weight of 65535+// means 1.0. JOINTS_0 is never normalized (its ints are bone indices).+const ACCESSOR_NORMALIZE_MAX = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 };++// Read one VEC4 accessor (JOINTS_0/WEIGHTS_0 and any JOINTS_n/WEIGHTS_n set+// above 0) into `count` rows of 4 numbers. Returns null for anything this+// reader cannot safely walk (no bufferView, an unsupported componentType, or+// a sparse accessor). Skin-weight attributes are not sparse in practice, and+// a report that skipped the rare case is safer than one that misreads it.+function readVec4Accessor(json, bin, accessorIndex) {+ const accessor = json.accessors?.[accessorIndex];+ if (!accessor || accessor.sparse || typeof accessor.bufferView !== 'number') return null;+ const view = json.bufferViews?.[accessor.bufferView];+ const compBytes = ACCESSOR_COMPONENT_BYTES[accessor.componentType];+ if (!view || !bin || !compBytes) return null;+ const stride = view.byteStride || compBytes * 4;+ const base = (view.byteOffset || 0) + (accessor.byteOffset || 0);+ if (base + stride * Math.max(0, accessor.count - 1) + compBytes * 4 > bin.byteLength) return null;+ const dv = new DataView(bin.buffer, bin.byteOffset + base);+ const normMax = accessor.normalized ? ACCESSOR_NORMALIZE_MAX[accessor.componentType] : null;+ const rows = [];+ for (let i = 0; i < accessor.count; i++) {+ const row = [];+ for (let c = 0; c < 4; c++) {+ const o = i * stride + c * compBytes;+ let v;+ switch (accessor.componentType) {+ case 5120: v = dv.getInt8(o); break;+ case 5121: v = dv.getUint8(o); break;+ case 5122: v = dv.getInt16(o, true); break;+ case 5123: v = dv.getUint16(o, true); break;+ case 5125: v = dv.getUint32(o, true); break;+ default: v = dv.getFloat32(o, true); break;+ }+ row.push(normMax ? v / normMax : v);+ }+ rows.push(row);+ }+ return rows;+}++// Per-vertex skin-weight health, the question canonical joint coverage can't+// answer: a non-humanoid rig (UniRig/SkinTokens, AniGen) has no canonical+// names to map at all, so its drivability hinges entirely on whether every+// vertex actually got a weight. Walks every JOINTS_n/WEIGHTS_n set a skinned+// primitive declares (glTF allows more than one set for >4 influences per+// vertex) and reports the heaviest influence count seen and how many+// vertices came back with no weight on any joint, a sign the predictor's+// skinning step missed geometry the mesh step produced.+function analyzeSkinWeights(json, bin) {+ const skinnedMeshIdx = new Set();+ for (const node of json.nodes || []) {+ if (node.skin != null && node.mesh != null) skinnedMeshIdx.add(node.mesh);+ }+ let maxInfluences = 0;+ let unweightedVertices = 0;+ let totalVertices = 0;+ for (const meshIdx of skinnedMeshIdx) {+ for (const prim of json.meshes?.[meshIdx]?.primitives || []) {+ const sets = Object.keys(prim.attributes || {})+ .map((k) => /^JOINTS_(\d+)$/.exec(k)?.[1])+ .filter((n) => n != null)+ .map(Number)+ .sort((a, b) => a - b);+ if (!sets.length) continue;+ const weightRows = sets.map((n) => readVec4Accessor(json, bin, prim.attributes[`WEIGHTS_${n}`]));+ if (weightRows.some((rows) => !rows)) continue;+ const vertexCount = weightRows[0].length;+ for (let v = 0; v < vertexCount; v++) {+ let influences = 0;+ for (const rows of weightRows) {+ for (const w of rows[v]) if (w > 1e-6) influences++;+ }+ totalVertices++;+ if (influences === 0) unweightedVertices++;+ if (influences > maxInfluences) maxInfluences = influences;+ }+ }+ }+ return { maxInfluences, unweightedVertices, totalVertices };+}+export function detectConvention(ctx) {for (const c of CONVENTIONS) {let hit = false;@@ -314,6 +411,7 @@ export function analyzeGlb(buffer, opts = {}) {const { json, jsonBytes, binBytes } = readGlbJson(buffer);const nodes = json.nodes || [];const jointIdx = jointNodeIndices(json);+ const skinWeights = analyzeSkinWeights(json, readGlbBin(buffer, jsonBytes));// Skinned = at least one mesh primitive is bound to a skin. This is the// glTF-level equivalent of three.js's `node.isSkinnedMesh` check, which the@@ -402,6 +500,9 @@ export function analyzeGlb(buffer, opts = {}) {collisions,renames,groups,+ maxInfluences: skinWeights.maxInfluences,+ unweightedVertices: skinWeights.unweightedVertices,+ skinnedVertices: skinWeights.totalVertices,},};report.verdict = buildVerdict(report, drivable);@@ -428,14 +529,26 @@ function buildVerdict(report, drivable) {}if (!drivable) {+ // A non-humanoid rig (a creature, a prop, anything UniRig/SkinTokens or+ // AniGen rigged) never maps canonical joints and lands here by design;+ // its own drivability question isn't "does the clip library retarget"+ // but "did the skinning step actually weight every vertex it rigged".+ const failNotes = [+ `Detected convention: ${s.convention.label} (${s.convention.evidence}).`,+ s.unmapped.length ? `${s.unmapped.length} joint names were not recognised, including ${s.unmapped.slice(0, 3).join(', ')}.` : 'The skeleton has very few joints.',+ ];+ if (s.skinnedVertices > 0) {+ failNotes.push(+ s.unweightedVertices > 0+ ? `${s.unweightedVertices} of ${s.skinnedVertices} skinned vertices have no joint influence at all (max ${s.maxInfluences} influences elsewhere).`+ : `Every one of ${s.skinnedVertices} skinned vertices has a joint influence (up to ${s.maxInfluences} at once), so the skin itself is sound even though no canonical bone mapped.`,+ );+ }return {level: 'fail',headline: `Only ${s.mapped} of this rig's joints map to the canonical skeleton, under the ${MIN_CANONICAL_BONES} needed to drive a clip.`,detail: 'three.ws falls back to the default rig for models like this rather than leaving them in a T-pose, so your own mesh will not be the one moving.',- notes: [- `Detected convention: ${s.convention.label} (${s.convention.evidence}).`,- s.unmapped.length ? `${s.unmapped.length} joint names were not recognised, including ${s.unmapped.slice(0, 3).join(', ')}.` : 'The skeleton has very few joints.',- ],+ notes: failNotes,fixes: ['Rename the joints to the canonical set below, or let the auto-rigger rebuild the skeleton (POST /api/forge?action=rig).','If this is a common rig convention we should already know, the unmapped names below are exactly what belongs in src/glb-canonicalize.js.',diff --git a/tests/rig-report.test.js b/tests/rig-report.test.jsindex 197057426..47a17ad37 100644--- a/tests/rig-report.test.js+++ b/tests/rig-report.test.js@@ -158,6 +158,31 @@ describe('analyzeGlb verdicts', () => {expect(r.verdict.headline).toMatch(/canonical skeleton/i);});+ it('reports per-vertex skin-weight health for a non-humanoid rig, same verdict as before', () => {+ // fox.glb has no canonical bone names at all (UniRig/SkinTokens/AniGen+ // output looks the same way), so canonical coverage can never answer+ // "is this skin sound" for it; maxInfluences/unweightedVertices can.+ const r = report('fox');+ expect(r.skeleton.skinnedVertices).toBeGreaterThan(0);+ expect(r.skeleton.maxInfluences).toBeGreaterThan(0);+ expect(r.skeleton.maxInfluences).toBeLessThanOrEqual(8);+ expect(r.skeleton.unweightedVertices).toBeGreaterThanOrEqual(0);+ expect(r.skeleton.unweightedVertices).toBeLessThanOrEqual(r.skeleton.skinnedVertices);+ // The new fields are informational: they must not change the verdict+ // this rig already got.+ expect(r.verdict.drivable).toBe(false);+ expect(r.verdict.level).toBe('fail');+ expect(r.verdict.notes.some((n) => /skinned vertices?/i.test(n))).toBe(true);+ });++ it('reports zero skin-weight stats for an unskinned model rather than throwing', () => {+ const r = report('mannequin');+ expect(r.skeleton.skinned).toBe(false);+ expect(r.skeleton.maxInfluences).toBe(0);+ expect(r.skeleton.unweightedVertices).toBe(0);+ expect(r.skeleton.skinnedVertices).toBe(0);+ });+it('warns on a halfbody rig and names exactly which groups stay frozen', () => {const r = report('realistic-halfbody');expect(r.verdict.level).toBe('warn');