@es3d/es3d 0.0.0-stage → 1.0.0

package/src/io/convert.js

@@ -0,0 +1,236 @@
+// File conversion to and from ES3D, shared by the website's converter and
+// the command-line tool. Works in browsers and in Node.
+//
+//   const r = await importFiles([{ name: 'logo.svg', bytes }]);   // → ES3D markup in r.text
+//   const out = exportFormat(r.text, 'glb', { baseName: 'logo' });  // → { files: [{ name, data, mime }] }
+
+import { isGzip, gunzip } from './compression.js';
+import { parse } from '../format/parse.js';
+import { serialize } from '../format/serializer.js';
+import { isGLB, glbToScene, gltfToScene, exportGLB } from './gltf.js';
+import { objToScene, exportOBJ } from './obj.js';
+import { isBinarySTL, isAsciiSTL, stlToScene, exportSTL } from './stl.js';
+import { isSTEP, stepToScene, exportSTEP } from './step.js';
+import { stepToExact } from './step-exact.js';
+import { svgToES3D } from './svg-import.js';
+import { sceneToMeshDocument } from './mesh-import.js';
+import { compile } from '../pipeline.js';
+import { exportableInstances } from './external-scene.js';
+
+/** OBJ and STL repeat every copy's triangles; beyond this the file gets too large for a browser tab. */
+const OBJ_TRIANGLE_LIMIT = 4e6;
+
+export const INPUT_KINDS = {
+  es3d: 'ES3D text',
+  svg: 'SVG drawing',
+  obj: 'Wavefront OBJ',
+  stl: 'STL',
+  gltf: 'glTF (JSON)',
+  glb: 'glTF binary (GLB)',
+  step: 'STEP',
+};
+
+export const OUTPUT_FORMATS = {
+  es3d: { label: 'ES3D markup (.es3d)', ext: '.es3d', mime: 'model/vnd.es3d', text: true },
+  'es3d-min': { label: 'ES3D markup, minified (.es3d)', ext: '.es3d', mime: 'model/vnd.es3d', text: true },
+  'es3d-compact': { label: 'ES3D compact syntax (.es3d)', ext: '.es3d', mime: 'model/vnd.es3d', text: true },
+  glb: { label: 'glTF binary (.glb)', ext: '.glb', mime: 'model/gltf-binary' },
+  obj: { label: 'Wavefront OBJ + MTL (.obj)', ext: '.obj', mime: 'model/obj', text: true },
+  stl: { label: 'STL for 3D printing (.stl)', ext: '.stl', mime: 'model/stl' },
+  step: { label: 'STEP, tessellated (.step)', ext: '.step', mime: 'model/step', text: true },
+};
+
+/** Files that only accompany a main file (OBJ materials, glTF buffers and textures). */
+const COMPANION = /\.(mtl|bin|png|jpe?g|webp|gif|ktx2|dds|tga|bmp)$/i;
+
+const decode = (bytes) => new TextDecoder('utf-8').decode(bytes).replace(/^/, '');
+
+/**
+ * The kind of a file, from its content first and its extension second.
+ * @returns {keyof INPUT_KINDS | null}
+ */
+export function detectKind(name, bytes) {
+  if (isGLB(bytes)) return 'glb';
+  const ext = ((/\.([a-z0-9]+)$/i.exec(name) || [])[1] || '').toLowerCase();
+  const head = decode(bytes.subarray(0, 4096));
+  if (isSTEP(head)) return 'step';
+  if (isBinarySTL(bytes) && !['es3d', 'svg', 'obj', 'gltf'].includes(ext)) return 'stl';
+  const es3dText = /^\s*(<\?xml[^>]*\?>\s*)?(<!--[\s\S]*?-->\s*)*<es3d[\s>/]/.test(head) || /^\s*((\/\/[^\n]*|\/\*[\s\S]*?\*\/)\s*)*es3d\b/.test(head);
+  if (ext === 'es3d' || es3dText) return 'es3d';
+  if (ext === 'svg' || /<svg[\s>/]/.test(head)) return 'svg';
+  if (ext === 'stl' || isAsciiSTL(bytes)) return 'stl';
+  if (ext === 'gltf' || /^\s*\{[\s\S]*"asset"\s*:/.test(head)) return 'gltf';
+  if (ext === 'obj' || /^\s*(#[^\n]*\n\s*)*(mtllib|o|g|v|vt|vn|f|usemtl|s)\s/.test(head)) return 'obj';
+  if (ext === 'step' || ext === 'stp' || ext === 'p21') return 'step';
+  return null;
+}
+
+/** Options of the importers, with their defaults. */
+export const IMPORT_DEFAULTS = {
+  svg: { size: 10, depth: 0.04, bevel: 0, strokes: true, base: false },
+  mesh: { precision: 'auto', normals: 'auto', uvs: true, smooth: 30 },
+  stl: { up: 'z' },
+};
+
+/**
+ * Convert input files into an ES3D document.
+ * @param {{name: string, bytes: Uint8Array}[]} files the main file plus companions (.mtl, .bin)
+ * @param {{svg?: object, mesh?: object, stl?: object}} [opts] see IMPORT_DEFAULTS
+ * @returns {Promise<{kind: string, name: string, title: string, text: string, warnings: string[], notes: string[]}>}
+ */
+export async function importFiles(files, opts = {}) {
+  if (!files.length) throw new Error('No file was given.');
+  const list = [];
+  for (const f of files) {
+    let bytes = f.bytes instanceof Uint8Array ? f.bytes : new Uint8Array(f.bytes);
+    let name = f.name || 'untitled';
+    if (isGzip(bytes)) {
+      bytes = await gunzip(bytes);
+      name = name.replace(/\.svgz$/i, '.svg').replace(/\.gz$/i, '');
+    }
+    list.push({ name, bytes });
+  }
+  const main = list.find((f) => !COMPANION.test(f.name)) || list[0];
+  const companions = list.filter((f) => f !== main);
+  const kind = detectKind(main.name, main.bytes);
+  if (!kind) throw new Error(`${main.name}: unknown file type. The converter reads SVG, OBJ, STL, STEP (.step, .stp) and glTF (.gltf, .glb) and ES3D (.es3d) files.`);
+  const title = main.name.replace(/\.[^.]+$/, '') || 'untitled';
+  const svgOpts = { ...IMPORT_DEFAULTS.svg, ...(opts.svg || {}) };
+  const meshOpts = { ...IMPORT_DEFAULTS.mesh, ...(opts.mesh || {}) };
+  const stlOpts = { ...IMPORT_DEFAULTS.stl, ...(opts.stl || {}) };
+  const warnings = [];
+  const notes = [];
+  const meshDocument = (s, sourceHasNormals) => {
+    const normals = meshOpts.normals === 'auto' ? sourceHasNormals : !!meshOpts.normals;
+    const digits = meshOpts.precision === 'exact' ? null : meshOpts.precision;
+    if (!normals) notes.push(`Normals are not stored; viewers compute them with a ${meshOpts.smooth}° crease angle.`);
+    return sceneToMeshDocument(s.scene, s.meshOf, title, { digits, normals, uvs: meshOpts.uvs ? 'auto' : false, smooth: meshOpts.smooth });
+  };
+  let text;
+  switch (kind) {
+    case 'es3d':
+      text = decode(main.bytes);
+      break;
+    case 'svg': {
+      const r = svgToES3D(decode(main.bytes), { name: main.name, ...svgOpts });
+      text = r.text;
+      warnings.push(...r.warnings);
+      notes.push(`${r.stats.fills} filled shape${r.stats.fills === 1 ? '' : 's'} extruded, ${r.stats.strokes} stroke${r.stats.strokes === 1 ? '' : 's'} turned into tubes, ${r.stats.materials} material${r.stats.materials === 1 ? '' : 's'}.`);
+      break;
+    }
+    case 'obj': {
+      const objText = decode(main.bytes);
+      const lib = (/^mtllib\s+(.+?)\s*$/m.exec(objText) || [])[1];
+      const mtlFile = companions.find((f) => /\.mtl$/i.test(f.name) && (!lib || f.name.toLowerCase() === lib.split(/[\\/]/).pop().toLowerCase())) || companions.find((f) => /\.mtl$/i.test(f.name));
+      if (lib && !mtlFile) warnings.push(`The material library ${lib} was not given; default colors are used. Select the .obj and .mtl files together to keep the materials.`);
+      if (companions.some((f) => /\.(png|jpe?g|webp|gif|tga|bmp)$/i.test(f.name)) || /^\s*map_/m.test(mtlFile ? decode(mtlFile.bytes) : '')) warnings.push('Textures are not converted; the materials keep their base colors.');
+      const s = objToScene(objText, mtlFile ? decode(mtlFile.bytes) : '');
+      const hasNormals = /^vn\s/m.test(objText);
+      text = meshDocument(s, hasNormals);
+      break;
+    }
+    case 'stl': {
+      const s = stlToScene(main.bytes, { up: stlOpts.up, smooth: meshOpts.smooth });
+      if (s.info.degenerate) warnings.push(`${s.info.degenerate} degenerate triangle${s.info.degenerate === 1 ? '' : 's'} (with two identical corners) ${s.info.degenerate === 1 ? 'was' : 'were'} dropped.`);
+      notes.push(`${s.info.format === 'binary' ? 'Binary' : 'ASCII'} STL with ${s.info.triangles.toLocaleString('en-US')} triangles, welded to ${s.info.vertices.toLocaleString('en-US')} vertices${stlOpts.up === 'z' ? '; turned from Z-up to Y-up' : ''}.`);
+      text = meshDocument(s, false);
+      break;
+    }
+    case 'step': {
+      // a B-rep (what CAD tools export) becomes ES3D shapes; tessellated STEP stays a mesh
+      const exact = stepToExact(main.bytes, { up: stlOpts.up, name: title });
+      if (exact) {
+        notes.push(exact.note);
+        text = exact.text;
+        break;
+      }
+      const s = stepToScene(main.bytes, { up: stlOpts.up, smooth: meshOpts.smooth });
+      if (s.info.curved) warnings.push(`${s.info.curved} curved face${s.info.curved === 1 ? '' : 's'} skipped. ES3D tessellates planar faces, circles and cylinders; re-export other curved solids as tessellated STEP or STL to keep them.`);
+      const unit = s.info.unit ? ` Coordinates are in ${s.info.unit} and were not rescaled.` : ' The file does not name a length unit; coordinates were used as written.';
+      notes.push(`STEP with ${s.info.triangles.toLocaleString('en-US')} triangles in ${s.info.meshes} mesh${s.info.meshes === 1 ? '' : 'es'}${stlOpts.up === 'z' ? '; turned from Z-up to Y-up' : ''}.${unit}`);
+      text = meshDocument(s, false);
+      break;
+    }
+    case 'gltf':
+    case 'glb': {
+      const resources = Object.fromEntries(companions.map((f) => [f.name, f.bytes]));
+      const s = kind === 'glb' ? glbToScene(main.bytes) : gltfToScene(decode(main.bytes), resources);
+      if (s.skipped.textures) warnings.push(`Textures are not converted (${s.skipped.textures} textured material${s.skipped.textures === 1 ? '' : 's'}); the materials keep their base colors.`);
+      if (s.skipped.points) warnings.push(`${s.skipped.points} point cloud primitive${s.skipped.points === 1 ? ' was' : 's were'} skipped.`);
+      const lines = s.scene.geometries.filter((g) => g.kind === 'lines').length;
+      if (lines) warnings.push(`${lines} line primitive${lines === 1 ? ' was' : 's were'} skipped (ES3D meshes hold triangles).`);
+      if ((s.json.skins || []).length || (s.json.animations || []).length) warnings.push('Skins and animations are not converted; the model is shown in its rest pose.');
+      if (s.json.extensionsRequired && s.json.extensionsRequired.length) warnings.push(`The file requires extensions that are not supported: ${s.json.extensionsRequired.join(', ')}.`);
+      const hasNormals = (s.json.meshes || []).some((m) => m.primitives.some((p) => p.attributes && p.attributes.NORMAL !== undefined));
+      text = meshDocument(s, hasNormals);
+      break;
+    }
+  }
+  return { kind, name: main.name, title, text, warnings, notes };
+}
+
+/** Parse and validate ES3D text; throws with the first diagnostics on errors. */
+function validDocument(source) {
+  const doc = parse(source);
+  if (!doc.ok) throw new Error(describeErrors(doc.diagnostics, doc.lineIndex));
+  return doc;
+}
+
+function describeErrors(diagnostics, lineIndex) {
+  const errors = diagnostics.filter((d) => d.severity === 'error');
+  const shown = errors.slice(0, 3).map((d) => d.format(lineIndex)).join('\n\n');
+  return `The ES3D document has ${errors.length} error${errors.length === 1 ? '' : 's'}:\n\n${shown}${errors.length > 3 ? `\n\n… and ${errors.length - 3} more` : ''}`;
+}
+
+/**
+ * Write an ES3D document in another format.
+ * @param {string|Uint8Array} source ES3D text
+ * @param {keyof OUTPUT_FORMATS} format
+ * @param {{baseName?: string, lod?: number, compiled?: object, instancing?: boolean}} [opts]
+ *        compiled: an existing compile() result for the same source (saves compiling twice)
+ * @returns {{files: {name: string, data: Uint8Array|string, mime: string}[], triangles?: number}}
+ */
+export function exportFormat(source, format, { baseName = 'scene', lod = 0, compiled = null, instancing = true } = {}) {
+  const spec = OUTPUT_FORMATS[format];
+  if (!spec) throw new Error(`Unknown output format ${format}.`);
+  const name = baseName + spec.ext;
+  const one = (data) => ({ files: [{ name, data, mime: spec.mime }] });
+  switch (format) {
+    case 'es3d':
+      return one(serialize(validDocument(source), { syntax: 'xml', pretty: true, comments: true }));
+    case 'es3d-min':
+      return one(serialize(validDocument(source), { syntax: 'xml', pretty: false }));
+    case 'es3d-compact':
+      return one(serialize(validDocument(source), { syntax: 'compact', pretty: true, comments: true }));
+    default: {
+      const r = compiled || compile(source);
+      if (!r.ok) throw new Error(describeErrors(r.diagnostics, r.doc && r.doc.lineIndex));
+      const meshOf = (e, l) => r.cache.mesh(e, Math.min(l, e.lods - 1));
+      if (format === 'glb') return one(exportGLB(r.scene, meshOf, { lod, instancing }));
+      if (format === 'obj') {
+        let triangles = 0;
+        for (const i of exportableInstances(r.scene)) {
+          const m = meshOf(r.scene.geometries[r.scene.geom[i]], lod);
+          if (m.kind === 'triangles') triangles += m.primitiveCount;
+        }
+        if (triangles > OBJ_TRIANGLE_LIMIT) throw new Error(`At this level of detail the scene has ${triangles.toLocaleString('en-US')} triangles, too many for an OBJ file (limit ${OBJ_TRIANGLE_LIMIT.toLocaleString('en-US')}). Choose a coarser detail, or glTF, which stores repeated shapes once.`);
+      }
+      if (format === 'stl') {
+        const s = exportSTL(r.scene, meshOf, { lod, name: baseName, maxTriangles: OBJ_TRIANGLE_LIMIT });
+        return { ...one(s.data), triangles: s.triangles };
+      }
+      if (format === 'step') {
+        const s = exportSTEP(r.scene, meshOf, { lod, name: baseName, maxTriangles: OBJ_TRIANGLE_LIMIT });
+        return { ...one(s.data), triangles: s.triangles };
+      }
+      const o = exportOBJ(r.scene, meshOf, { lod, name: baseName });
+      return {
+        files: [
+          { name, data: o.obj, mime: spec.mime },
+          { name: `${baseName}.mtl`, data: o.mtl, mime: 'text/plain' },
+        ],
+        triangles: o.triangles,
+      };
+    }
+  }
+}

package/src/io/download.js

@@ -0,0 +1,13 @@
+// Browser download helper.
+
+export function download(name, data, mime = 'application/octet-stream') {
+  const blob = data instanceof Blob ? data : new Blob([data], { type: mime });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = name;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 2000);
+}

package/src/io/external-scene.js

@@ -0,0 +1,127 @@
+// Shared helpers for exporters and importers of conventional mesh formats.
+
+import { RenderScene } from '../scene/flatten.js';
+import { Material, DEFAULT_MATERIAL_PARAMS } from '../material/materials.js';
+
+/**
+ * Instances that a static exporter should write: every instance outside <lod>
+ * switches, and the most detailed alternative (child 0) inside them.
+ */
+export function exportableInstances(scene) {
+  const sw = scene.lodSwitches;
+  const visible = new Uint8Array(sw.length);
+  for (let s = 0; s < sw.length; s++) {
+    const w = sw[s];
+    visible[s] = w.parent < 0 ? 1 : visible[w.parent] && w.parentChild === 0 ? 1 : 0;
+  }
+  const out = [];
+  for (let i = 0; i < scene.count; i++) {
+    const ln = scene.lodNode[i];
+    if (ln >= 0 && !(visible[ln] && scene.lodChild[i] === 0)) continue;
+    out.push(i);
+  }
+  return out;
+}
+
+/**
+ * Geometry indices that are drawn with a textured material. Exporters write
+ * texture coordinates only for these (with `uvs: 'auto'`): UVs of untextured
+ * procedural geometry are dead weight in a mesh file.
+ */
+export function texturedGeometries(scene) {
+  const out = new Set();
+  for (let i = 0; i < scene.count; i++) {
+    const m = scene.materials[scene.mat[i]];
+    if (m && (m.map || m.normalMap)) out.add(scene.geom[i]);
+  }
+  return out;
+}
+
+/** Stable, unique names for materials (OBJ usemtl / glTF material names). */
+export function materialNames(materials) {
+  const used = new Set();
+  return materials.map((m, i) => {
+    let base = String(m.name || `material${i}`).replace(/[^A-Za-z0-9_.-]/g, '_') || `material${i}`;
+    let name = base;
+    let k = 1;
+    while (used.has(name)) name = `${base}_${k++}`;
+    used.add(name);
+    return name;
+  });
+}
+
+/** Growable flat instance table (no per-instance allocations for large imports). */
+export class InstanceTable {
+  constructor(capacity = 64) {
+    this.count = 0;
+    this.geom = new Int32Array(capacity);
+    this.mat = new Int32Array(capacity);
+    this.matrices = new Float64Array(capacity * 16);
+  }
+
+  push(geom, mat, matrix) {
+    if (this.count === this.geom.length) {
+      const cap = this.geom.length * 2;
+      const g = new Int32Array(cap), m = new Int32Array(cap), x = new Float64Array(cap * 16);
+      g.set(this.geom);
+      m.set(this.mat);
+      x.set(this.matrices);
+      this.geom = g;
+      this.mat = m;
+      this.matrices = x;
+    }
+    const i = this.count++;
+    this.geom[i] = geom;
+    this.mat[i] = mat;
+    const o = i * 16, x = this.matrices;
+    for (let k = 0; k < 16; k++) x[o + k] = matrix[k];
+  }
+}
+
+/**
+ * Build a RenderScene from already tessellated meshes (OBJ / glTF imports).
+ * @param {{geometries: {mesh: import('../geometry/mesh.js').Mesh, key?: string}[],
+ *          materials: object[], instances: InstanceTable}} data
+ *        materials are parameter objects in the ES3D material model (sRGB colors)
+ */
+export function buildExternalScene(data) {
+  const table = data.instances;
+  const scene = new RenderScene(Math.max(16, table.count));
+  scene.environment = { background: [0.09, 0.1, 0.12, 1], sky: [0.8, 0.86, 0.95, 1], ground: [0.25, 0.22, 0.2, 1], intensity: 0.5, exposure: 1 };
+  scene.materials = data.materials.map((p, i) => new Material({ ...DEFAULT_MATERIAL_PARAMS, ...p }, i, p.name || `material${i}`));
+  if (!scene.materials.length) scene.materials.push(new Material({ ...DEFAULT_MATERIAL_PARAMS }, 0, 'default'));
+  const entries = data.geometries.map((g, i) => ({
+    id: i + 1,
+    key: g.key || `external:${i}`,
+    kind: g.mesh.kind,
+    lods: 1,
+    doubleSided: false,
+    bounds: g.mesh.bounds,
+    meshes: [g.mesh],
+  }));
+  const gIndex = entries.map((e) => scene.geometryIndex(e));
+  const lastMat = scene.materials.length - 1;
+  const world = new Float64Array(16);
+  for (let i = 0; i < table.count; i++) {
+    for (let k = 0; k < 16; k++) world[k] = table.matrices[i * 16 + k];
+    scene.setInstance(i, gIndex[table.geom[i]], Math.min(table.mat[i], lastMat), world, 0, -1, 0);
+  }
+  scene.count = table.count;
+  if (!(scene.bounds.min[0] <= scene.bounds.max[0])) scene.bounds = { min: [-1, -1, -1], max: [1, 1, 1] };
+  scene.version++;
+  return { scene, meshOf: (entry) => entry.meshes[0] };
+}
+
+/** Trimmed fixed-point number formatting (used by text exporters). */
+export function fixed(v, digits) {
+  if (!Number.isFinite(v)) return '0';
+  let s = v.toFixed(digits);
+  if (s.indexOf('.') >= 0) {
+    let e = s.length;
+    while (s.charCodeAt(e - 1) === 48) e--;
+    if (s.charCodeAt(e - 1) === 46) e--;
+    s = s.slice(0, e);
+  }
+  if (s === '-0') return '0';
+  return s;
+}

package/src/io/file-loader.js

@@ -0,0 +1,28 @@
+// File loading for ES3D Studio: detects the content type from magic bytes and
+// extension, transparently decompresses gzip, and converts foreign formats
+// (SVG, OBJ, STL, STEP, glTF) into ES3D text with the same importers as the
+// converter page, so they can be inspected and edited like any other document.
+
+import { isGzip, gunzip } from './compression.js';
+import { detectKind, importFiles, INPUT_KINDS } from './convert.js';
+
+/**
+ * @param {File|{name:string, arrayBuffer:()=>Promise<ArrayBuffer>}} file
+ * @returns {Promise<{name:string, kind:string, text?:string, bytes:Uint8Array, originalSize:number, note?:string}>}
+ */
+export async function loadFile(file) {
+  let bytes = new Uint8Array(await file.arrayBuffer());
+  const originalSize = bytes.length;
+  let name = file.name || 'untitled.es3d';
+  let note = '';
+  if (isGzip(bytes)) {
+    bytes = await gunzip(bytes);
+    name = name.replace(/\.svgz$/i, '.svg').replace(/\.gz$/i, '');
+    note = `decompressed from ${originalSize.toLocaleString('en-US')} gzip bytes`;
+  }
+  const kind = detectKind(name, bytes) || 'es3d';
+  if (kind === 'es3d') return { name, kind, text: new TextDecoder('utf-8').decode(bytes), bytes, originalSize, note };
+  const r = await importFiles([{ name, bytes }]);
+  const warn = r.warnings.length ? ` (${r.warnings.join(' ')})` : '';
+  return { name, kind, bytes, originalSize, text: r.text, note: (note ? note + '; ' : '') + `converted from ${INPUT_KINDS[kind]} to ES3D${warn}` };
+}