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(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.js
index 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.js
index 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.js
index 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');