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(glb-diff): split geometryHash into topology/uv/skinWeights sub-hashes
nirholasd84e3acd473f
diff --git a/packages/glb-diff/src/describe.js b/packages/glb-diff/src/describe.jsindex d8c99efd5..d03edbb3b 100644--- a/packages/glb-diff/src/describe.js+++ b/packages/glb-diff/src/describe.js@@ -19,7 +19,11 @@import { hashBytes, hashNumbers, hashString, hashValue } from './hash.js';import { isGLB, readDocument } from './document.js';-export const DESCRIPTION_VERSION = 1;+// Bumped to 2: primitives and meshes now also carry topologyHash, uvHash and+// skinWeightHash (the preserve-contract sub-hashes), on top of the combined+// geometryHash. A cache keyed on version 1 should re-describe rather than+// trust a stored description that predates those fields.+export const DESCRIPTION_VERSION = 2;// glTF primitive modes that produce triangles, and how many vertices each// triangle consumes. Anything else (points, lines) contributes zero triangles.@@ -42,6 +46,29 @@ const PRIMITIVE_MODE_NAMES = {// which breaks animation in exactly the way this tool exists to catch.const HASHED_SEMANTICS = ['POSITION', 'NORMAL', 'TANGENT', 'TEXCOORD_0', 'TEXCOORD_1', 'COLOR_0', 'JOINTS_0', 'WEIGHTS_0'];+// The three sub-hashes a "preserve" contract checks independently of the+// combined geometryHash above: an edit that keeps topology can still repaint+// UVs, and an edit that keeps UVs can still rebind skin weights, so a single+// combined hash cannot tell those apart. TOPOLOGY_SEMANTICS deliberately+// excludes NORMAL/TANGENT/COLOR_0: those are appearance attributes that a+// re-bake legitimately regenerates without the mesh's connectivity changing.+const TOPOLOGY_SEMANTICS = ['POSITION'];+const UV_SEMANTICS = ['TEXCOORD_0', 'TEXCOORD_1'];+const SKIN_WEIGHT_SEMANTICS = ['JOINTS_0', 'WEIGHTS_0'];++// Hash a fixed subset of a primitive's attribute semantics, seeded by `label`+// so "no semantics present" still differs between topology/uv/skin and isn't+// mistaken for "identical to a primitive that never had attributes at all".+function hashSemantics(prim, semantics, label) {+ let h = hashString(`sub:${label}`);+ for (const semantic of semantics) {+ const attr = prim.getAttribute(semantic);+ if (!attr) continue;+ h = hashString(h + hashNumbers(attr.getArray(), { seed: semantic, quantize: !semantic.startsWith('JOINTS') }));+ }+ return h;+}+function nameOf(prop, fallback) {const n = prop && typeof prop.getName === 'function' ? prop.getName() : '';return n || fallback;@@ -100,6 +127,14 @@ function describePrimitive(prim, materialNames) {}if (indices) geometry = hashString(geometry + hashNumbers(indices.getArray(), { quantize: false, seed: 'INDICES' }));+ // Topology also includes the index buffer: two meshes with identical+ // vertex positions but a rewound/retriangulated index buffer do not share+ // connectivity, even though POSITION alone would hash the same.+ let topology = hashSemantics(prim, TOPOLOGY_SEMANTICS, 'topology');+ if (indices) topology = hashString(topology + hashNumbers(indices.getArray(), { quantize: false, seed: 'INDICES' }));+ const uv = hashSemantics(prim, UV_SEMANTICS, 'uv');+ const skinWeights = hashSemantics(prim, SKIN_WEIGHT_SEMANTICS, 'skin');+const targets = prim.listTargets().length;return {@@ -112,6 +147,9 @@ function describePrimitive(prim, materialNames) {indexed: Boolean(indices),morphTargets: targets,geometryHash: geometry,+ topologyHash: topology,+ uvHash: uv,+ skinWeightHash: skinWeights,};}@@ -142,6 +180,9 @@ function describeMesh(mesh, index, materialNames) {const vertices = primitives.reduce((sum, p) => sum + p.vertices, 0);const triangles = primitives.reduce((sum, p) => sum + p.triangles, 0);const geometryHash = hashString(primitives.map((p) => p.geometryHash).join('|'));+ const topologyHash = hashString(primitives.map((p) => p.topologyHash).join('|'));+ const uvHash = hashString(primitives.map((p) => p.uvHash).join('|'));+ const skinWeightHash = hashString(primitives.map((p) => p.skinWeightHash).join('|'));return {type: 'mesh',@@ -153,6 +194,9 @@ function describeMesh(mesh, index, materialNames) {triangles,bounds,geometryHash,+ topologyHash,+ uvHash,+ skinWeightHash,key: id.key,fingerprint: hashString(`${geometryHash}|${primitives.map((p) => p.material || '').join(',')}`),};diff --git a/packages/glb-diff/src/diff.js b/packages/glb-diff/src/diff.jsindex 6991323e9..070f1177d 100644--- a/packages/glb-diff/src/diff.js+++ b/packages/glb-diff/src/diff.js@@ -10,7 +10,10 @@ import { canonicalize } from './hash.js';import { jaccard, matchEntries, ratio } from './match.js';import { maxSeverity } from './severity.js';-export const CHANGESET_VERSION = 1;+// Bumped to 2 alongside DESCRIPTION_VERSION: mesh diffs now also carry+// 'topology', 'uv' and 'skinWeights' fields, independent of the combined+// 'geometry' field, so a preserve contract can tell them apart.+export const CHANGESET_VERSION = 2;function equalish(a, b) {if (a === b) return true;@@ -154,6 +157,13 @@ function diffMeshes(a, b) {field(changes, 'triangles', x.triangles, y.triangles, 'major');field(changes, 'primitives', x.primitives.length, y.primitives.length, 'major');field(changes, 'bounds', x.bounds, y.bounds, 'minor');+ // Independent sub-hashes of the combined 'geometry' field above, so a+ // preserve contract (packages/glb-diff consumers that must keep topology,+ // UVs or skin weights across an edit) can tell which of the three moved+ // instead of only knowing that geometryHash differs.+ field(changes, 'topology', x.topologyHash, y.topologyHash, 'major', 'vertex positions or index buffer changed');+ field(changes, 'uv', x.uvHash, y.uvHash, 'minor', 'UV coordinates changed');+ field(changes, 'skinWeights', x.skinWeightHash, y.skinWeightHash, 'major', 'vertex joint/weight bindings changed');field(changes,'materials',diff --git a/packages/glb-diff/tests/glb-diff.test.js b/packages/glb-diff/tests/glb-diff.test.jsindex d02de0b8f..839b88185 100644--- a/packages/glb-diff/tests/glb-diff.test.js+++ b/packages/glb-diff/tests/glb-diff.test.js@@ -49,6 +49,9 @@ function buildModel(overrides = {}) {meshName = 'Body',nodeName = 'Root',positions = [0, 0, 0, 1, 0, 0, 0, 1, 0],+ uv = [0, 0, 1, 0, 0, 1],+ jointIndices = [0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0],+ jointWeights = [0.5, 0.5, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0],materialName = 'Skin',baseColor = [1, 1, 1, 1],joints = ['Hips', 'Spine'],@@ -65,9 +68,30 @@ function buildModel(overrides = {}) {.setType('VEC3').setArray(new Float32Array(positions)).setBuffer(buffer);+ const texcoord = doc+ .createAccessor()+ .setType('VEC2')+ .setArray(new Float32Array(uv))+ .setBuffer(buffer);+ const jointsAccessor = doc+ .createAccessor()+ .setType('VEC4')+ .setArray(new Uint16Array(jointIndices))+ .setBuffer(buffer);+ const weightsAccessor = doc+ .createAccessor()+ .setType('VEC4')+ .setArray(new Float32Array(jointWeights))+ .setBuffer(buffer);const material = doc.createMaterial(materialName).setBaseColorFactor(baseColor);- const prim = doc.createPrimitive().setAttribute('POSITION', position).setMaterial(material);+ const prim = doc+ .createPrimitive()+ .setAttribute('POSITION', position)+ .setAttribute('TEXCOORD_0', texcoord)+ .setAttribute('JOINTS_0', jointsAccessor)+ .setAttribute('WEIGHTS_0', weightsAccessor)+ .setMaterial(material);const mesh = doc.createMesh(meshName).addPrimitive(prim);const root = doc.createNode(nodeName).setMesh(mesh);@@ -213,6 +237,42 @@ describe('diff', () => {expect(changes.highlights[0].text).toContain('Spine');});+ it('tells a UV repaint apart from a topology or skin edit', () => {+ // Only TEXCOORD_0 moves: positions and skin weights hold still.+ const changes = diffDescriptions(describeBuilt({}, 'a'), describeBuilt({ uv: [1, 1, 0, 1, 1, 0] }, 'b'));+ const mesh = changes.sections.meshes.modified.find((m) => m.name === 'Body');+ const fields = mesh.changes.map((c) => c.field);+ expect(fields).toContain('uv');+ expect(fields).not.toContain('topology');+ expect(fields).not.toContain('skinWeights');+ });++ it('tells a topology edit apart from a UV or skin edit', () => {+ // Only POSITION moves: UVs and skin weights hold still.+ const changes = diffDescriptions(+ describeBuilt({}, 'a'),+ describeBuilt({ positions: [0, 0, 0, 1, 0, 0, 0, 2, 0] }, 'b'),+ );+ const mesh = changes.sections.meshes.modified.find((m) => m.name === 'Body');+ const fields = mesh.changes.map((c) => c.field);+ expect(fields).toContain('topology');+ expect(fields).not.toContain('uv');+ expect(fields).not.toContain('skinWeights');+ });++ it('tells a re-skin apart from a topology or UV edit', () => {+ // Only WEIGHTS_0 moves: positions and UVs hold still.+ const changes = diffDescriptions(+ describeBuilt({}, 'a'),+ describeBuilt({ jointWeights: [1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0] }, 'b'),+ );+ const mesh = changes.sections.meshes.modified.find((m) => m.name === 'Body');+ const fields = mesh.changes.map((c) => c.field);+ expect(fields).toContain('skinWeights');+ expect(fields).not.toContain('topology');+ expect(fields).not.toContain('uv');+ });+it('calls a recoloured material a minor change', () => {const changes = diffDescriptions(describeBuilt({}, 'a'), describeBuilt({ baseColor: [1, 0, 0, 1] }, 'b'));expect(changes.severity).toBe('minor');