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(forge): add a geometry pass that cuts the floor slab image-to-3D models fuse under a resting object
nirholasb5e2aec093d4
diff --git a/api/_lib/glb-floor-slab.js b/api/_lib/glb-floor-slab.jsnew file mode 100644index 000000000..68a63c755--- /dev/null+++ b/api/_lib/glb-floor-slab.js@@ -0,0 +1,277 @@+// Strip the floor slab an image-to-3D reconstructor fuses under a resting object.+//+// TRELLIS and Hunyuan3D both read "an object sitting on the ground" into their+// input, even from a clean alpha cutout, and answer with the subject standing on+// a thin, wide plate: a teapot on a marble square, a telescope on a grey sheet.+// The plate belongs to the same mesh, so every viewer, download and AR launch+// shows it. glb-quality.js already notices the resulting shape (`planar`) and+// asks vision QA to judge it, but that only helps while a vision provider+// answers; this pass removes the defect itself, on geometry alone.+//+// What counts as a fused slab, measured in world space with +Y up (glTF):+// - a bottom band, the lowest SLAB_BAND of the model's height, holds a real+// share of the triangles;+// - the geometry ABOVE that band is a real subject, not a sliver;+// - the band is a solid sheet: seen from above it fills its bounding rectangle+// (SLAB_FILL). Measured on live results, a fused plate fills 1.000 of it,+// while feet, legs and a rigged figure's soles fill 0.03 to 0.42, and even a+// round lamp foot tops out near 0.79;+// - the sheet is wider than the subject standing on it (SLAB_FOOTPRINT_RATIO).+// A genuinely flat subject (a plate, a rug, a coin) has almost nothing above the+// band and is left alone. A thick base (a plinth) rises above the band, so its+// top face widens the subject's footprint and the model is left alone too.+//+// Only the part of the plate outside where the subject touches down is cut; the+// patch directly under it stays, so the subject never loses its own underside. The+// pass is pure, CPU-only and best-effort: anything it cannot read or decide+// returns the original bytes.++import { Buffer } from 'node:buffer';++// The bottom band, as a fraction of the model's height. A fused plate measured+// on live results is 1-3% of the height thick.+export const SLAB_BAND = 0.05;+// Geometry counts as "subject" only above this fraction of the height, which+// keeps the plate's own rim out of the subject's footprint.+const SUBJECT_FLOOR = 0.08;+// The subject's contact footprint: the part of it below this fraction of the+// height, which is where it rests on the plate. The cut keeps the plate only+// under this, so a teapot keeps a patch under its body, not spout to spout.+const CONTACT_CEILING = 0.2;+// The band must fill at least this share of its bounding rectangle, seen from+// above, to be a sheet rather than feet, legs or a rounded foot.+export const SLAB_FILL = 0.9;+// And be at least this many times wider (by XZ footprint area) than the subject.+export const SLAB_FOOTPRINT_RATIO = 1.25;+// Resolution of the top-down coverage grid the fill is measured on.+const FILL_GRID = 48;+// Minimum shares of all triangles for the band and for the subject.+const MIN_BAND_SHARE = 0.01;+const MIN_SUBJECT_SHARE = 0.2;+// The subject's footprint grows by this fraction of its extent before cutting,+// so a flared foot or a soft shadow edge on the subject is never trimmed.+const FOOTPRINT_MARGIN = 0.1;++function worldPositions(prim, matrix) {+ const pos = prim.getAttribute('POSITION');+ const n = pos.getCount();+ const out = new Float64Array(n * 3);+ const v = [0, 0, 0];+ const m = matrix;+ for (let i = 0; i < n; i++) {+ pos.getElement(i, v);+ out[i * 3] = m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12];+ out[i * 3 + 1] = m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13];+ out[i * 3 + 2] = m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14];+ }+ return out;+}++function triangleIndices(prim) {+ const idx = prim.getIndices();+ if (idx) return Array.from(idx.getArray());+ const n = prim.getAttribute('POSITION').getCount();+ return Array.from({ length: n - (n % 3) }, (_, i) => i);+}++function emptyBox() {+ return { minX: Infinity, maxX: -Infinity, minZ: Infinity, maxZ: -Infinity };+}++function grow(box, x, z) {+ if (x < box.minX) box.minX = x;+ if (x > box.maxX) box.maxX = x;+ if (z < box.minZ) box.minZ = z;+ if (z > box.maxZ) box.maxZ = z;+}++function area(box) {+ return box.maxX > box.minX && box.maxZ > box.minZ ? (box.maxX - box.minX) * (box.maxZ - box.minZ) : 0;+}++// Share of the band's bounding rectangle its triangles cover, seen from above:+// each grid cell whose centre falls inside any band triangle counts.+function coverage(parts, isBand, box) {+ const w = box.maxX - box.minX;+ const d = box.maxZ - box.minZ;+ if (!(w > 0 && d > 0)) return 0;+ const g = FILL_GRID;+ const cells = new Uint8Array(g * g);+ const cell = (v, lo, span) => Math.min(g - 1, Math.max(0, Math.floor(((v - lo) / span) * g)));+ for (const { positions: p, indices } of parts) {+ for (let t = 0; t + 2 < indices.length; t += 3) {+ if (!isBand(p, indices, t)) continue;+ const ax = p[indices[t] * 3], az = p[indices[t] * 3 + 2];+ const bx = p[indices[t + 1] * 3], bz = p[indices[t + 1] * 3 + 2];+ const cx = p[indices[t + 2] * 3], cz = p[indices[t + 2] * 3 + 2];+ const den = (bz - cz) * (ax - cx) + (cx - bx) * (az - cz);+ if (Math.abs(den) < 1e-12) continue;+ const x0 = cell(Math.min(ax, bx, cx), box.minX, w), x1 = cell(Math.max(ax, bx, cx), box.minX, w);+ const z0 = cell(Math.min(az, bz, cz), box.minZ, d), z1 = cell(Math.max(az, bz, cz), box.minZ, d);+ for (let gz = z0; gz <= z1; gz++) {+ const pz = box.minZ + ((gz + 0.5) / g) * d;+ for (let gx = x0; gx <= x1; gx++) {+ if (cells[gz * g + gx]) continue;+ const px = box.minX + ((gx + 0.5) / g) * w;+ const l1 = ((bz - cz) * (px - cx) + (cx - bx) * (pz - cz)) / den;+ const l2 = ((cz - az) * (px - cx) + (ax - cx) * (pz - cz)) / den;+ if (l1 >= -1e-6 && l2 >= -1e-6 && 1 - l1 - l2 >= -1e-6) cells[gz * g + gx] = 1;+ }+ }+ }+ }+ let covered = 0;+ for (const c of cells) covered += c;+ return covered / (g * g);+}++/**+ * Decide whether a set of triangles is a subject fused onto a floor slab, and+ * which triangles are the slab outside the subject's footprint. Pure: takes+ * world-space positions and triangle index lists, returns a verdict.+ *+ * @param {Array<{ positions: Float64Array, indices: number[] }>} parts+ * @returns {{ slab: boolean, reason: string, remove?: Array<Set<number>>, removedTriangles?: number, footprintRatio?: number, fill?: number }}+ */+export function detectFloorSlab(parts) {+ let minY = Infinity;+ let maxY = -Infinity;+ for (const { positions } of parts) {+ for (let i = 1; i < positions.length; i += 3) {+ if (positions[i] < minY) minY = positions[i];+ if (positions[i] > maxY) maxY = positions[i];+ }+ }+ const height = maxY - minY;+ if (!(height > 0)) return { slab: false, reason: 'no_height' };+ const bandTop = minY + SLAB_BAND * height;+ const subjectFloor = minY + SUBJECT_FLOOR * height;+ const contactTop = minY + CONTACT_CEILING * height;+ const inBand = (p, idx, t) =>+ Math.max(p[idx[t] * 3 + 1], p[idx[t + 1] * 3 + 1], p[idx[t + 2] * 3 + 1]) <= bandTop;++ let total = 0;+ let bandTris = 0;+ let subjectTris = 0;+ const band = emptyBox();+ const subject = emptyBox();+ const contact = emptyBox();+ for (const { positions: p, indices } of parts) {+ for (let t = 0; t + 2 < indices.length; t += 3) {+ total++;+ const a = indices[t] * 3;+ const b = indices[t + 1] * 3;+ const c = indices[t + 2] * 3;+ const low = Math.max(p[a + 1], p[b + 1], p[c + 1]) <= bandTop;+ const high = Math.min(p[a + 1], p[b + 1], p[c + 1]) > subjectFloor;+ if (low) {+ bandTris++;+ for (const k of [a, b, c]) grow(band, p[k], p[k + 2]);+ } else if (high) {+ subjectTris++;+ for (const k of [a, b, c]) grow(subject, p[k], p[k + 2]);+ }+ if (!low && Math.min(p[a + 1], p[b + 1], p[c + 1]) <= contactTop) {+ for (const k of [a, b, c]) grow(contact, p[k], p[k + 2]);+ }+ }+ }+ if (!total) return { slab: false, reason: 'no_triangles' };+ if (bandTris / total < MIN_BAND_SHARE) return { slab: false, reason: 'no_floor_band' };+ if (subjectTris / total < MIN_SUBJECT_SHARE) return { slab: false, reason: 'flat_subject' };+ const subjectArea = area(subject);+ const footprintRatio = subjectArea > 0 ? area(band) / subjectArea : Infinity;+ if (footprintRatio < SLAB_FOOTPRINT_RATIO) return { slab: false, reason: 'base_fits_subject', footprintRatio };+ const fill = coverage(parts, inBand, band);+ if (fill < SLAB_FILL) return { slab: false, reason: 'band_not_a_sheet', footprintRatio, fill };++ const rest = area(contact) > 0 ? contact : subject;+ const mx = (rest.maxX - rest.minX) * FOOTPRINT_MARGIN;+ const mz = (rest.maxZ - rest.minZ) * FOOTPRINT_MARGIN;+ const keep = { minX: rest.minX - mx, maxX: rest.maxX + mx, minZ: rest.minZ - mz, maxZ: rest.maxZ + mz };+ let removedTriangles = 0;+ const remove = parts.map(({ positions: p, indices }) => {+ const drop = new Set();+ for (let t = 0; t + 2 < indices.length; t += 3) {+ const a = indices[t] * 3;+ const b = indices[t + 1] * 3;+ const c = indices[t + 2] * 3;+ if (Math.max(p[a + 1], p[b + 1], p[c + 1]) > bandTop) continue;+ const cx = (p[a] + p[b] + p[c]) / 3;+ const cz = (p[a + 2] + p[b + 2] + p[c + 2]) / 3;+ const inside = cx >= keep.minX && cx <= keep.maxX && cz >= keep.minZ && cz <= keep.maxZ;+ if (!inside) {+ drop.add(t);+ removedTriangles++;+ }+ }+ return drop;+ });+ if (!removedTriangles) return { slab: false, reason: 'nothing_outside_footprint', footprintRatio, fill };+ return { slab: true, reason: 'floor_slab', remove, removedTriangles, footprintRatio, fill };+}++/**+ * Remove a fused floor slab from a GLB. Returns the original bytes untouched+ * when no slab is found.+ *+ * @param {Buffer|Uint8Array} buf - source GLB bytes+ * @returns {Promise<{ buffer: Buffer, stripped: boolean, reason: string, removedTriangles: number, footprintRatio?: number, fill?: number }>}+ */+export async function stripFloorSlab(buf) {+ const input = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);+ const { NodeIO } = await import('@gltf-transform/core');+ const { ALL_EXTENSIONS } = await import('@gltf-transform/extensions');+ const { compactPrimitive, prune } = await import('@gltf-transform/functions');+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);+ const doc = await io.readBinary(new Uint8Array(input.buffer, input.byteOffset, input.byteLength));++ // A primitive can be drawn by several nodes; measure every placement, but+ // only a primitive drawn exactly once can be edited without changing the+ // other copies, so a shared primitive vetoes the edit.+ const entries = [];+ const seen = new Map();+ 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.getMode() !== 4 || !prim.getAttribute('POSITION')) continue;+ seen.set(prim, (seen.get(prim) || 0) + 1);+ entries.push({ prim, positions: worldPositions(prim, matrix), indices: triangleIndices(prim) });+ }+ }+ const unchanged = (reason, extra = {}) => ({ buffer: input, stripped: false, reason, removedTriangles: 0, ...extra });+ if (!entries.length) return unchanged('no_triangles');++ const verdict = detectFloorSlab(entries);+ if (!verdict.slab) return unchanged(verdict.reason, { footprintRatio: verdict.footprintRatio, fill: verdict.fill });+ if (entries.some(({ prim }) => seen.get(prim) > 1)) return unchanged('shared_primitive');++ entries.forEach(({ prim, indices }, i) => {+ const drop = verdict.remove[i];+ if (!drop.size) return;+ const kept = [];+ for (let t = 0; t + 2 < indices.length; t += 3) {+ if (!drop.has(t)) kept.push(indices[t], indices[t + 1], indices[t + 2]);+ }+ const vertexCount = prim.getAttribute('POSITION').getCount();+ const array = vertexCount > 65535 ? new Uint32Array(kept) : new Uint16Array(kept);+ // A fresh accessor, never an in-place write: an index accessor can be+ // shared with a primitive this pass is not editing. prune() drops the old one.+ const buffer = doc.getRoot().listBuffers()[0] || doc.createBuffer();+ prim.setIndices(doc.createAccessor().setType('SCALAR').setArray(array).setBuffer(buffer));+ // Drop the vertices only the cut triangles used, so the file shrinks too.+ compactPrimitive(prim);+ });+ await doc.transform(prune());+ const out = Buffer.from(await io.writeBinary(doc));+ return {+ buffer: out,+ stripped: true,+ reason: verdict.reason,+ removedTriangles: verdict.removedTriangles,+ footprintRatio: verdict.footprintRatio,+ fill: verdict.fill,+ };+}