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
// Fit a delivered GLB inside a caller-requested [x, y, z] bounding box.
//
// Some integrations (a game engine's prop slot, an AR anchor, a print bed) need
// the delivered mesh to occupy a known footprint rather than whatever scale the
// generator happened to produce. forge-options.js's `bbox` field carries that
// request in meters; this module performs the fit: the mesh is uniformly scaled
// (never stretched: a non-uniform scale would distort the subject) so its
// longest-relative-to-box axis exactly fills that axis of the box, then
// recentered so it sits in the middle of X/Z and rests on the floor at Y=0,
// matching the convention every other forge delivery already uses (see
// glb-floor-slab.js).
//
// Pure, CPU-only and best-effort, same contract as glb-floor-slab.js: anything
// this pass cannot read or decide returns the original bytes unchanged.
import { Buffer } from 'node:buffer';
function worldBounds(prim, matrix) {
const pos = prim.getAttribute('POSITION');
const n = pos.getCount();
const v = [0, 0, 0];
let minX = Infinity, minY = Infinity, minZ = Infinity;
let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
for (let i = 0; i < n; i++) {
pos.getElement(i, v);
const x = matrix[0] * v[0] + matrix[4] * v[1] + matrix[8] * v[2] + matrix[12];
const y = matrix[1] * v[0] + matrix[5] * v[1] + matrix[9] * v[2] + matrix[13];
const z = matrix[2] * v[0] + matrix[6] * v[1] + matrix[10] * v[2] + matrix[14];
if (x < minX) minX = x;
if (x > maxX) maxX = x;
if (y < minY) minY = y;
if (y > maxY) maxY = y;
if (z < minZ) minZ = z;
if (z > maxZ) maxZ = z;
}
return { minX, minY, minZ, maxX, maxY, maxZ };
}
function mergeBounds(a, b) {
return {
minX: Math.min(a.minX, b.minX),
minY: Math.min(a.minY, b.minY),
minZ: Math.min(a.minZ, b.minZ),
maxX: Math.max(a.maxX, b.maxX),
maxY: Math.max(a.maxY, b.maxY),
maxZ: Math.max(a.maxZ, b.maxZ),
};
}
/**
* Compute the uniform scale and recentering translation that fits `bounds`
* inside `[bx, by, bz]` meters, preserving aspect ratio, centered on X/Z and
* floored at Y=0. Pure: takes world-space bounds, returns a transform.
*
* @param {{minX:number,minY:number,minZ:number,maxX:number,maxY:number,maxZ:number}} bounds
* @param {[number, number, number]} bbox
* @returns {{ fit: boolean, reason: string, scale?: number, translate?: [number, number, number] }}
*/
export function computeBboxFit(bounds, bbox) {
const sizeX = bounds.maxX - bounds.minX;
const sizeY = bounds.maxY - bounds.minY;
const sizeZ = bounds.maxZ - bounds.minZ;
if (!(sizeX > 0 || sizeY > 0 || sizeZ > 0)) return { fit: false, reason: 'no_extent' };
const [bx, by, bz] = bbox;
if (!(bx > 0 && by > 0 && bz > 0)) return { fit: false, reason: 'invalid_bbox' };
// Only the axes with real extent constrain the scale: a flat plane (sizeY
// near 0) would otherwise force an infinite scale trying to fill a height
// it has none of.
const ratios = [];
if (sizeX > 0) ratios.push(bx / sizeX);
if (sizeY > 0) ratios.push(by / sizeY);
if (sizeZ > 0) ratios.push(bz / sizeZ);
const scale = Math.min(...ratios);
if (!(scale > 0 && Number.isFinite(scale))) return { fit: false, reason: 'degenerate_scale' };
const centerX = (bounds.minX + bounds.maxX) / 2;
const centerZ = (bounds.minZ + bounds.maxZ) / 2;
return {
fit: true,
reason: 'fitted',
scale,
// Translate in the mesh's own (pre-scale) units: the root node applies
// scale then translate as separate TRS channels, so this offset must
// already be divided by `scale` to land the scaled mesh centered and
// floored once both transforms are composed.
translate: [-centerX, -bounds.minY, -centerZ],
};
}
/**
* Fit a GLB's content inside a caller-requested [x, y, z] box in meters, via a
* single wrapping root node (scale + translate), so the source geometry itself
* is never resampled. Returns the original bytes unchanged when there is
* nothing to fit or the request is degenerate.
*
* @param {Buffer|Uint8Array} buf - source GLB bytes
* @param {[number, number, number]} bbox - requested [x, y, z] in meters
* @returns {Promise<{ buffer: Buffer, fitted: boolean, reason: string, scale?: number }>}
*/
export async function fitBbox(buf, bbox) {
const input = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
const unchanged = (reason) => ({ buffer: input, fitted: false, reason });
if (!Array.isArray(bbox) || bbox.length !== 3) return unchanged('no_bbox_requested');
const { NodeIO } = await import('@gltf-transform/core');
const { ALL_EXTENSIONS } = await import('@gltf-transform/extensions');
const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
const doc = await io.readBinary(new Uint8Array(input.buffer, input.byteOffset, input.byteLength));
const scene = doc.getRoot().listScenes()[0];
const topNodes = scene ? scene.listChildren() : doc.getRoot().listNodes().filter((n) => !n.getParentNode?.());
if (!topNodes.length) return unchanged('no_nodes');
let bounds = null;
for (const node of doc.getRoot().listNodes()) {
const mesh = node.getMesh();
if (!mesh) continue;
const matrix = node.getWorldMatrix();
for (const prim of mesh.listPrimitives()) {
if (!prim.getAttribute('POSITION')) continue;
const b = worldBounds(prim, matrix);
bounds = bounds ? mergeBounds(bounds, b) : b;
}
}
if (!bounds) return unchanged('no_triangles');
const verdict = computeBboxFit(bounds, bbox);
if (!verdict.fit) return unchanged(verdict.reason);
// Wrap every top-level node under one new root that carries the scale and
// translation, rather than editing vertex data: cheap, lossless, and never
// fights an existing node hierarchy or skin.
const wrapper = doc.createNode('BboxFit').setScale([verdict.scale, verdict.scale, verdict.scale]);
wrapper.setTranslation(verdict.translate.map((v) => v * verdict.scale));
for (const node of topNodes) {
scene.removeChild(node);
wrapper.addChild(node);
}
if (scene) scene.addChild(wrapper);
const out = Buffer.from(await io.writeBinary(doc));
return { buffer: out, fitted: true, reason: 'fitted', scale: verdict.scale };
}