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
// 3MF: the format that carries the print, not just the shape.
//
// STL is what every bureau accepts; 3MF is what makes a print worth ordering.
// It is an OPC package (a zip with a relationship graph) holding one XML model
// that declares real units, indexed vertices, and per-vertex color through the
// Materials and Properties extension. That last part is the whole reason this
// writer exists: full-color sandstone and binder-jet machines reproduce color
// per vertex, so a generated model whose color lives in a 2K albedo texture can
// only be printed in color if something samples that texture per vertex and
// writes it into the manufacturing file. mesh-io.js does the sampling; this
// module writes it out. A download button that hands over a GLB leaves the
// color behind.
//
// Spec subset, deliberately small and deliberately exact:
// [Content_Types].xml default parts for .rels and .model
// _rels/.rels one 3D-model start-part relationship
// 3D/3dmodel.model unit="millimeter", resources, one build item
//
// The color group is declared in the material namespace but NOT listed in
// `requiredextensions`. A color-capable slicer reads it; a mono slicer ignores
// the attributes and still prints the geometry. Requiring the extension would
// make a monochrome printer reject a file it could have printed.
//
// The 3MF spec puts the build volume in the positive octant, so the mesh is
// translated to sit at the origin corner before it is written.
import { Buffer } from 'node:buffer';
import { zipSync, strToU8 } from 'fflate';
const MM_PER_METER = 1000;
export const CONTENT_TYPES_PART = '[Content_Types].xml';
export const RELS_PART = '_rels/.rels';
export const MODEL_PART = '3D/3dmodel.model';
export const CORE_NAMESPACE = 'http://schemas.microsoft.com/3dmanufacturing/core/2015/02';
export const MATERIAL_NAMESPACE = 'http://schemas.microsoft.com/3dmanufacturing/material/2015/02';
const MODEL_RELATIONSHIP = 'http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel';
const MODEL_CONTENT_TYPE = 'application/vnd.ms-package.3dmanufacturing-3dmodel+xml';
const RELS_CONTENT_TYPE = 'application/vnd.openxmlformats-package.relationships+xml';
// Resource ids. 3MF requires them unique within the model; two constants are
// clearer than a counter for a package that always holds exactly one object.
const COLOR_GROUP_ID = 1;
const OBJECT_ID = 2;
// Coordinates are written at micron resolution. Finer is noise no printer can
// hit, and it keeps the XML (the dominant cost of a 3MF) roughly a third
// smaller than full float printing on a large mesh.
const COORD_DECIMALS = 3;
// The earliest instant a zip's DOS timestamp can express. Used as a constant so
// two exports of one mesh differ in no byte at all.
const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
export class ThreeMfExportError extends Error {
constructor(code, message) {
super(message);
this.name = 'ThreeMfExportError';
this.code = code;
}
}
function xmlEscape(value) {
return String(value)
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"');
}
// Trim the trailing zeros a fixed-decimal render leaves behind: on a 200k
// triangle mesh that is megabytes of "000".
function coord(value) {
const fixed = value.toFixed(COORD_DECIMALS);
return fixed.includes('.') ? fixed.replace(/\.?0+$/, '') || '0' : fixed;
}
function hex2(v) {
return Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0').toUpperCase();
}
/**
* Collapse per-vertex RGB into the palette a 3MF colorgroup holds, plus the
* per-vertex index into it. Identical colors share one entry, which is what
* keeps a flat-shaded model's group at a handful of colors instead of one per
* vertex.
*/
export function buildColorGroup(colors, vertexCount) {
if (!colors || colors.length < vertexCount * 3) return null;
const palette = [];
const seen = new Map();
const indexOf = new Uint32Array(vertexCount);
for (let v = 0; v < vertexCount; v += 1) {
const key = `${hex2(colors[v * 3])}${hex2(colors[v * 3 + 1])}${hex2(colors[v * 3 + 2])}`;
let id = seen.get(key);
if (id === undefined) {
id = palette.length;
seen.set(key, id);
palette.push(key);
}
indexOf[v] = id;
}
return { palette, indexOf };
}
function buildModelXml({ positions, indices, colorGroup, scale, metadata }) {
const vertexCount = positions.length / 3;
// The positive-octant shift the spec asks for.
let minX = Infinity;
let minY = Infinity;
let minZ = Infinity;
for (let i = 0; i < positions.length; i += 3) {
if (positions[i] < minX) minX = positions[i];
if (positions[i + 1] < minY) minY = positions[i + 1];
if (positions[i + 2] < minZ) minZ = positions[i + 2];
}
const parts = [];
parts.push('<?xml version="1.0" encoding="UTF-8"?>\n');
parts.push(
`<model unit="millimeter" xml:lang="en-US" xmlns="${CORE_NAMESPACE}" xmlns:m="${MATERIAL_NAMESPACE}">`,
);
for (const [name, value] of Object.entries(metadata)) {
if (value === null || value === undefined || value === '') continue;
parts.push(`<metadata name="${xmlEscape(name)}">${xmlEscape(value)}</metadata>`);
}
parts.push('<resources>');
if (colorGroup) {
parts.push(`<m:colorgroup id="${COLOR_GROUP_ID}">`);
for (const hex of colorGroup.palette) parts.push(`<m:color color="#${hex}FF"/>`);
parts.push('</m:colorgroup>');
}
// pid/pindex give the object a default color, so a reader that ignores the
// per-triangle indices still shows something rather than untextured grey.
const objectAttrs = colorGroup
? `id="${OBJECT_ID}" type="model" pid="${COLOR_GROUP_ID}" pindex="0"`
: `id="${OBJECT_ID}" type="model"`;
parts.push(`<object ${objectAttrs}><mesh><vertices>`);
for (let v = 0; v < vertexCount; v += 1) {
const x = coord((positions[v * 3] - minX) * scale);
const y = coord((positions[v * 3 + 1] - minY) * scale);
const z = coord((positions[v * 3 + 2] - minZ) * scale);
parts.push(`<vertex x="${x}" y="${y}" z="${z}"/>`);
}
parts.push('</vertices><triangles>');
for (let t = 0; t < indices.length; t += 3) {
const a = indices[t];
const b = indices[t + 1];
const c = indices[t + 2];
if (colorGroup) {
parts.push(
`<triangle v1="${a}" v2="${b}" v3="${c}" p1="${colorGroup.indexOf[a]}" p2="${colorGroup.indexOf[b]}" p3="${colorGroup.indexOf[c]}"/>`,
);
} else {
parts.push(`<triangle v1="${a}" v2="${b}" v3="${c}"/>`);
}
}
parts.push('</triangles></mesh></object>');
parts.push('</resources>');
parts.push(`<build><item objectid="${OBJECT_ID}"/></build>`);
parts.push('</model>');
return parts.join('');
}
const CONTENT_TYPES_XML =
'<?xml version="1.0" encoding="UTF-8"?>\n' +
'<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
`<Default Extension="rels" ContentType="${RELS_CONTENT_TYPE}"/>` +
`<Default Extension="model" ContentType="${MODEL_CONTENT_TYPE}"/>` +
'</Types>';
const RELS_XML =
'<?xml version="1.0" encoding="UTF-8"?>\n' +
'<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
`<Relationship Id="rel0" Target="/${MODEL_PART}" Type="${MODEL_RELATIONSHIP}"/>` +
'</Relationships>';
/**
* Write a 3MF package.
*
* @param {{positions: Float64Array|number[], indices: Uint32Array|number[], colors?: Uint8Array|null}} mesh
* Indexed triangles in glTF meters; `colors` is per-vertex RGB bytes as
* mesh-io.js samples them.
* @param {{scale?: number, color?: boolean, title?: string, designer?: string,
* description?: string, license?: string}} [opts]
* @returns {Buffer} the .3mf bytes
*/
export function export3mf(mesh, opts = {}) {
const positions = mesh?.positions;
const indices = mesh?.indices;
if (!positions || !indices || indices.length < 3) {
throw new ThreeMfExportError('empty_mesh', 'no triangles to export');
}
if (indices.length % 3 !== 0) {
throw new ThreeMfExportError('bad_indices', 'index buffer is not a whole number of triangles');
}
const vertexCount = positions.length / 3;
for (let i = 0; i < indices.length; i += 1) {
if (indices[i] >= vertexCount) {
throw new ThreeMfExportError('bad_indices', 'index buffer references a vertex that does not exist');
}
}
const colorGroup = opts.color === false ? null : buildColorGroup(mesh.colors, vertexCount);
const modelXml = buildModelXml({
positions,
indices,
colorGroup,
scale: opts.scale ?? MM_PER_METER,
metadata: {
Application: 'three.ws Materialize',
Title: opts.title ?? '',
Designer: opts.designer ?? '',
Description: opts.description ?? '',
LicenseTerms: opts.license ?? '',
},
});
// Deterministic package: a fixed timestamp, one compression level, parts in
// a fixed order. Two prepares of the same mesh must produce the same bytes,
// because the print certificate hashes exactly this file. The zip clock only
// spans 1980-2099, so the DOS epoch stands in for "no time".
const zipped = zipSync(
{
[CONTENT_TYPES_PART]: strToU8(CONTENT_TYPES_XML),
[RELS_PART]: strToU8(RELS_XML),
[MODEL_PART]: strToU8(modelXml),
},
{ level: 6, mtime: ZIP_EPOCH },
);
return Buffer.from(zipped);
}
/** Colors survived the round trip only if the group was actually written. */
export function threeMfHasColor(modelXml) {
return modelXml.includes('<m:colorgroup') && modelXml.includes('<m:color color="#');
}