Skip to content

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.

feat(rig-doctor): report skin-weight health for non-humanoid rigs

nirholasa7906b7c9b29
diff --git a/docs/rig-doctor.md b/docs/rig-doctor.md
index 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 print
console.log(report.skeleton.convention); // { id: 'mixamo', label: 'Mixamo', … }
console.log(report.skeleton.mapped); // 52
console.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 all
for (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.js
index 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.js
index 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.js
index 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');