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
// Turn a glTF Document into a flat, JSON-safe description of everything the
// diff cares about.
//
// This is the seam that makes the rest of the engine testable and portable.
// After describeDocument() runs there is no glTF-Transform object left in play,
// only plain data, so the matcher and the differ are ordinary functions over
// arrays that a unit test can build by hand. It is also what lets a description
// be computed once in the browser, cached, and diffed repeatedly against
// several candidates without re-parsing bytes.
//
// Two identity values hang off every entry and the distinction between them is
// the whole trick:
// key what the asset calls this thing (name, or hierarchy path for nodes)
// fingerprint what this thing IS, with the name deliberately excluded
// Matching on `key` finds the obvious pairs. Matching leftovers on `fingerprint`
// is what turns "one object removed, one object added" into "renamed", which is
// the difference between a diff you can read and a wall of noise.
import { hashBytes, hashNumbers, hashString, hashValue } from './hash.js';
import { isGLB, readDocument } from './document.js';
// 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.
const TRIANGLE_MODES = new Set([4, 5, 6]);
const PRIMITIVE_MODE_NAMES = {
0: 'POINTS',
1: 'LINES',
2: 'LINE_LOOP',
3: 'LINE_STRIP',
4: 'TRIANGLES',
5: 'TRIANGLE_STRIP',
6: 'TRIANGLE_FAN',
};
// Attribute semantics whose values participate in the geometry hash, in a fixed
// order so the hash is stable. Positions decide "is this the same shape";
// normals and UVs decide "was it re-baked"; skin weights decide "was it
// re-skinned", which is a change a positions-only hash would miss entirely and
// 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;
}
// glTF names are optional, and plenty of exporters ship none. Inventing
// "mesh.0" would be worse than useless: it reads like a real name in the report
// and, worse, would match an unrelated object that happens to be third in the
// other file. Unnamed objects get a label that admits what it is and a key
// scoped to their index, so they only ever pair with the same slot on the other
// side.
function identify(prop, type, index) {
const raw = prop && typeof prop.getName === 'function' ? prop.getName() : '';
if (raw) return { name: raw, key: raw, unnamed: false };
return { name: `(unnamed ${type} ${index})`, key: `#${type}.${index}`, unnamed: true };
}
function round(value, places = 5) {
if (!Number.isFinite(value)) return 0;
const f = 10 ** places;
return Math.round(value * f) / f;
}
function roundArray(arr, places = 5) {
if (!arr) return null;
return Array.from(arr, (v) => round(v, places));
}
// ── Geometry ─────────────────────────────────────────────────────────────────
function describePrimitive(prim, materialNames) {
const position = prim.getAttribute('POSITION');
const vertices = position ? position.getCount() : 0;
const indices = prim.getIndices();
const mode = prim.getMode();
const indexCount = indices ? indices.getCount() : 0;
let triangles = 0;
if (TRIANGLE_MODES.has(mode)) {
const count = indices ? indexCount : vertices;
triangles = mode === 4 ? Math.floor(count / 3) : Math.max(0, count - 2);
}
const semantics = prim.listSemantics().slice().sort();
const material = prim.getMaterial();
// The per-primitive geometry hash. Attribute arrays are hashed in a fixed
// order under a seed naming the semantic, so a model that gained a UV set
// does not hash the same as one that lost a color set of equal length.
let geometry = hashString(`mode:${mode}`);
for (const semantic of HASHED_SEMANTICS) {
const attr = prim.getAttribute(semantic);
if (!attr) continue;
geometry = hashString(
geometry + hashNumbers(attr.getArray(), { seed: semantic, quantize: !semantic.startsWith('JOINTS') }),
);
}
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 {
mode,
modeName: PRIMITIVE_MODE_NAMES[mode] || `MODE_${mode}`,
material: material ? nameOf(material, `material.${materialNames.get(material) ?? '?'}`) : null,
attributes: semantics,
vertices,
triangles,
indexed: Boolean(indices),
morphTargets: targets,
geometryHash: geometry,
topologyHash: topology,
uvHash: uv,
skinWeightHash: skinWeights,
};
}
function boundsOf(prim) {
const position = prim.getAttribute('POSITION');
if (!position) return null;
const min = position.getMin([]);
const max = position.getMax([]);
if (!min || !max || min.length < 3) return null;
return { min: roundArray(min), max: roundArray(max) };
}
function unionBounds(a, b) {
if (!a) return b;
if (!b) return a;
return {
min: a.min.map((v, i) => Math.min(v, b.min[i])),
max: a.max.map((v, i) => Math.max(v, b.max[i])),
};
}
function describeMesh(mesh, index, materialNames) {
const id = identify(mesh, 'mesh', index);
const primitives = mesh.listPrimitives().map((p) => describePrimitive(p, materialNames));
let bounds = null;
for (const prim of mesh.listPrimitives()) bounds = unionBounds(bounds, boundsOf(prim));
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',
index,
name: id.name,
unnamed: id.unnamed,
primitives,
vertices,
triangles,
bounds,
geometryHash,
topologyHash,
uvHash,
skinWeightHash,
key: id.key,
fingerprint: hashString(`${geometryHash}|${primitives.map((p) => p.material || '').join(',')}`),
};
}
// ── Hierarchy ────────────────────────────────────────────────────────────────
// Walk the scene graph and give every node a stable path. Siblings that share a
// name get a positional suffix, because a rig with three nodes called "Bone"
// under one parent is real and a path that cannot tell them apart would report
// phantom moves on every export.
function describeNodes(root, meshByProp) {
const out = [];
const seen = new Set();
let index = 0;
const visit = (node, parentPath, parentName, depth) => {
const siblings = parentPath === null ? [] : null;
void siblings;
const raw = nameOf(node, `#node.${index}`);
const path = parentPath ? `${parentPath}/${raw}` : raw;
let unique = path;
let bump = 1;
while (seen.has(unique)) unique = `${path}#${bump++}`;
seen.add(unique);
const mesh = node.getMesh();
const skin = node.getSkin();
const camera = node.getCamera();
const children = node.listChildren();
const translation = roundArray(node.getTranslation());
const rotation = roundArray(node.getRotation());
const scale = roundArray(node.getScale());
const meshDesc = mesh ? meshByProp.get(mesh) : null;
out.push({
type: 'node',
index: index++,
name: raw,
path: unique,
parent: parentName,
depth,
translation,
rotation,
scale,
mesh: meshDesc ? meshDesc.name : null,
skin: skin ? nameOf(skin, 'skin') : null,
camera: camera ? nameOf(camera, 'camera') : null,
childCount: children.length,
key: unique,
// Name-free identity: where it sits, what it carries, how it is posed.
// A node that keeps its geometry and transform but changes name is a
// rename; one that keeps its name and changes geometry is an edit.
fingerprint: hashValue({
t: translation,
r: rotation,
s: scale,
g: meshDesc ? meshDesc.geometryHash : null,
skin: Boolean(skin),
children: children.length,
depth,
}),
});
for (const child of children) visit(child, unique, raw, depth + 1);
};
for (const scene of root.listScenes()) {
for (const node of scene.listChildren()) visit(node, '', null, 0);
}
// Nodes reachable from no scene still ship in the file and still cost bytes,
// so they are described rather than silently dropped.
const covered = new Set(out.map((n) => n.name));
for (const node of root.listNodes()) {
if (node.getParentNode()) continue;
const raw = nameOf(node, 'node');
if (covered.has(raw)) continue;
visit(node, '(detached)', null, 0);
}
return out;
}
// ── Appearance ───────────────────────────────────────────────────────────────
const TEXTURE_SLOTS = [
['baseColor', 'getBaseColorTexture'],
['metallicRoughness', 'getMetallicRoughnessTexture'],
['normal', 'getNormalTexture'],
['occlusion', 'getOcclusionTexture'],
['emissive', 'getEmissiveTexture'],
];
function describeMaterial(material, index, textureByProp) {
const id = identify(material, 'material', index);
const slots = {};
for (const [slot, getter] of TEXTURE_SLOTS) {
const tex = material[getter]();
const desc = tex ? textureByProp.get(tex) : null;
slots[slot] = desc ? desc.name : tex ? 'texture' : null;
}
const core = {
baseColorFactor: roundArray(material.getBaseColorFactor()),
metallic: round(material.getMetallicFactor()),
roughness: round(material.getRoughnessFactor()),
emissiveFactor: roundArray(material.getEmissiveFactor()),
normalScale: round(material.getNormalScale()),
occlusionStrength: round(material.getOcclusionStrength()),
alphaMode: material.getAlphaMode(),
alphaCutoff: round(material.getAlphaCutoff()),
doubleSided: material.getDoubleSided(),
textures: slots,
};
const extensions = material
.listExtensions()
.map((e) => e.extensionName)
.sort();
return {
type: 'material',
index,
name: id.name,
unnamed: id.unnamed,
...core,
extensions,
key: id.key,
fingerprint: hashValue({ ...core, extensions }),
};
}
function describeTexture(texture, index) {
const id = identify(texture, 'texture', index);
const image = texture.getImage();
const size = texture.getSize();
const [width, height] = size || [0, 0];
const bytes = image ? image.byteLength : 0;
const pixelHash = image ? hashBytes(image) : null;
return {
type: 'texture',
index,
name: id.name,
unnamed: id.unnamed,
mimeType: texture.getMimeType() || null,
uri: texture.getURI() || null,
width,
height,
bytes,
pixelHash,
key: id.key,
fingerprint: pixelHash || hashValue({ width, height, bytes, mime: texture.getMimeType() }),
};
}
// ── Motion ───────────────────────────────────────────────────────────────────
function samplerDuration(sampler) {
const input = sampler.getInput();
if (!input) return 0;
const max = input.getMax([]);
if (Array.isArray(max) && Number.isFinite(max[0])) return max[0];
const array = input.getArray();
return array && array.length ? array[array.length - 1] : 0;
}
function describeAnimation(animation, index) {
const id = identify(animation, 'animation', index);
const channels = animation.listChannels();
const samplers = animation.listSamplers();
let duration = 0;
for (const sampler of samplers) duration = Math.max(duration, samplerDuration(sampler));
// Which node each channel drives, and along which path. This is the list that
// decides whether a clip still plays after a rig edit, so it is compared
// entry by entry rather than summarized into a count.
const targets = channels
.map((ch) => {
const node = ch.getTargetNode();
return `${node ? nameOf(node, 'node') : '(none)'}.${ch.getTargetPath()}`;
})
.sort();
const interpolations = [...new Set(samplers.map((s) => s.getInterpolation()))].sort();
const keyframes = samplers.reduce((sum, s) => {
const input = s.getInput();
return sum + (input ? input.getCount() : 0);
}, 0);
return {
type: 'animation',
index,
name: id.name,
unnamed: id.unnamed,
duration: round(duration, 4),
channels: channels.length,
samplers: samplers.length,
keyframes,
interpolations,
targets,
key: id.key,
fingerprint: hashValue({ duration: round(duration, 4), targets, keyframes, interpolations }),
};
}
function describeSkin(skin, index) {
const id = identify(skin, 'skin', index);
const joints = skin.listJoints().map((j) => nameOf(j, 'joint'));
const ibm = skin.getInverseBindMatrices();
const bindHash = ibm ? hashNumbers(ibm.getArray()) : null;
const skeleton = skin.getSkeleton();
return {
type: 'skin',
index,
name: id.name,
unnamed: id.unnamed,
joints,
jointCount: joints.length,
skeleton: skeleton ? nameOf(skeleton, 'root') : null,
bindHash,
key: id.key,
fingerprint: hashValue({ joints, bindHash }),
};
}
// ── Entry point ──────────────────────────────────────────────────────────────
/**
* Describe a parsed Document.
* @param {import('@gltf-transform/core').Document} document
* @param {{ name?: string, sizeBytes?: number, container?: 'glb'|'gltf' }} [meta]
*/
export function describeDocument(document, meta = {}) {
const root = document.getRoot();
const asset = root.getAsset();
const materialProps = root.listMaterials();
const textureProps = root.listTextures();
const meshProps = root.listMeshes();
const materialIndex = new Map(materialProps.map((m, i) => [m, i]));
const textureByProp = new Map();
const textures = textureProps.map((t, i) => {
const desc = describeTexture(t, i);
textureByProp.set(t, desc);
return desc;
});
const materials = materialProps.map((m, i) => describeMaterial(m, i, textureByProp));
const meshByProp = new Map();
const meshes = meshProps.map((m, i) => {
const desc = describeMesh(m, i, materialIndex);
meshByProp.set(m, desc);
return desc;
});
const nodes = describeNodes(root, meshByProp);
const animations = root.listAnimations().map((a, i) => describeAnimation(a, i));
const skins = root.listSkins().map((s, i) => describeSkin(s, i));
const totals = {
scenes: root.listScenes().length,
nodes: nodes.length,
meshes: meshes.length,
materials: materials.length,
textures: textures.length,
animations: animations.length,
skins: skins.length,
joints: skins.reduce((sum, s) => sum + s.jointCount, 0),
vertices: meshes.reduce((sum, m) => sum + m.vertices, 0),
triangles: meshes.reduce((sum, m) => sum + m.triangles, 0),
textureBytes: textures.reduce((sum, t) => sum + t.bytes, 0),
sizeBytes: meta.sizeBytes ?? 0,
};
return {
version: DESCRIPTION_VERSION,
name: meta.name || null,
container: meta.container || null,
asset: {
generator: asset.generator || null,
version: asset.version || null,
copyright: asset.copyright || null,
},
extensionsUsed: root
.listExtensionsUsed()
.map((x) => x.extensionName)
.sort(),
extensionsRequired: root
.listExtensionsRequired()
.map((x) => x.extensionName)
.sort(),
totals,
nodes,
meshes,
materials,
textures,
animations,
skins,
};
}
/**
* Read bytes and describe them in one call.
* @param {Uint8Array} bytes
* @param {{ name?: string }} [meta]
*/
export async function describeModel(bytes, meta = {}) {
const document = await readDocument(bytes);
return describeDocument(document, {
...meta,
sizeBytes: bytes.byteLength,
container: isGLB(bytes) ? 'glb' : 'gltf',
});
}