@es3d/es3d 1.1.0 → 1.1.2

package/docs/SPEC.md

@@ -195,7 +195,7 @@ The reference reader keeps up to four levels. At quality 1 the segment count is
 
 A `segments` attribute (or both torus segment counts) requests one fixed tessellation, which is part of the shape. A `segments="6"` cylinder is a hexagonal prism at every distance. Exact shapes (box, plane, polygon, hairline, authored mesh) have one level and a bound of 0.
 
-Each level stores its bound. A frame may draw a level only while `bound × scale × pixelsPerUnit` is at most 1. `scale` is the longest column of the instance matrix. `pixelsPerUnit` is the projected size of one canonical unit. The reference reader picks the coarsest level that satisfies that test. A renderer `lodBias` above 1 (default 1) divides the one-pixel budget; it is not a document attribute. While a level is still being generated, a renderer may draw a coarser one in its place for a few frames (progressive refinement), as long as it keeps drawing until every level passes the test. For a unit sphere the switches fall near 59, 15 and 7 pixels of the sphere's own radius.
+Each level stores its bound. A frame may draw a level only while `bound × scale × pixelsPerUnit` is at most 1. `scale` is the longest column of the instance matrix. `pixelsPerUnit` is the largest projected size, in CSS pixels, of a unit length at the centre of the instance's bounding sphere. For a perspective view it is F·d/z², where F = viewportHeight / (2·tan(verticalFov/2)), d is the distance from the eye to the centre and z is its depth along the view axis; d²/z² is limited to its value at the corners of the view, and that limit is used when z ≤ 0. For an orthographic view it is viewportHeight divided by the view's height. The reference reader picks the coarsest level that satisfies that test. A renderer `lodBias` above 1 (default 1) divides the one-pixel budget; it is not a document attribute. While a level is still being generated, a renderer may draw a coarser one in its place for a few frames (progressive refinement), as long as it keeps drawing until every level passes the test. For a unit sphere on the view axis the switches fall near 59, 15 and 7 pixels of the sphere's own radius.
 
 Closed shapes must produce closed, outward-facing surfaces. Open or flat shapes (planes, polygons, paths, open revolves, `caps="false"`) are rendered double-sided.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@es3d/es3d",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "ES3D (Extensible Scalable 3D): a declarative, SVG-inspired 3D scene format with a WebGPU/WebGL2 reference renderer, editor and converter.",
   "type": "module",
   "license": "Apache-2.0",

package/src/io/threejs.js

@@ -44,7 +44,11 @@ export function exportThree(model) {
   const tally = new Map();
   const add = (key, k = 1) => tally.set(key, (tally.get(key) || 0) + k);
   const lines = [];
+  // Geometries and materials are declared once, at the top of createScene(), so a
+  // repeat factory and the code after it can both use them.
+  const defs = [];
   const geos = new Map();
+  const bakedGeos = new Map();
   const mats = new Map();
   let seq = 0;
   const fresh = (p) => `${p}${seq++}`;
@@ -59,10 +63,10 @@ export function exportThree(model) {
     const c = m.baseColorSrgb;
     const side = (m.doubleSided || forceDouble) ? ', side: THREE.DoubleSide' : '';
     if (m.unlit) {
-      lines.push(`  const ${id} = new THREE.MeshBasicMaterial({ color: new THREE.Color(${n(c[0])}, ${n(c[1])}, ${n(c[2])}), transparent: ${m.opacity < 0.999}, opacity: ${n(m.opacity)}${side} });`);
+      defs.push(`  const ${id} = new THREE.MeshBasicMaterial({ color: new THREE.Color(${n(c[0])}, ${n(c[1])}, ${n(c[2])}), transparent: ${m.opacity < 0.999}, opacity: ${n(m.opacity)}${side} });`);
       return id;
     }
-    lines.push(`  const ${id} = new THREE.MeshStandardMaterial({ color: new THREE.Color(${n(c[0])}, ${n(c[1])}, ${n(c[2])}), metalness: ${n(m.metallic)}, roughness: ${n(m.roughness)}, transparent: ${m.opacity < 0.999}, opacity: ${n(m.opacity)}${side} });`);
+    defs.push(`  const ${id} = new THREE.MeshStandardMaterial({ color: new THREE.Color(${n(c[0])}, ${n(c[1])}, ${n(c[2])}), metalness: ${n(m.metallic)}, roughness: ${n(m.roughness)}, transparent: ${m.opacity < 0.999}, opacity: ${n(m.opacity)}${side} });`);
     return id;
   };
 
@@ -71,7 +75,7 @@ export function exportThree(model) {
     if (geos.has(key)) return geos.get(key);
     const id = fresh('g');
     geos.set(key, id);
-    lines.push(`  const ${id} = ${geometryExpr(solid)};`);
+    defs.push(`  const ${id} = ${geometryExpr(solid)};`);
     return id;
   };
 
@@ -116,12 +120,17 @@ export function exportThree(model) {
   const baked = (node) => {
     const mesh = node.solid.kind === 'mesh' || node.solid.kind === 'lines' ? node.solid : model.bakedMesh(node.entry);
     add(node.solid.kind === 'mesh' || node.solid.kind === 'lines' ? 'mesh' : node.solid.kind);
-    const g = fresh('g');
-    const positions = `new Float32Array([${nums(mesh.positions)}])`;
-    lines.push(`  const ${g} = new THREE.BufferGeometry();`);
-    lines.push(`  ${g}.setAttribute('position', new THREE.BufferAttribute(${positions}, 3));`);
-    if (mesh.normals) lines.push(`  ${g}.setAttribute('normal', new THREE.BufferAttribute(new Float32Array([${nums(mesh.normals)}]), 3));`);
-    lines.push(`  ${g}.setIndex([${Array.from(mesh.indices).join(', ')}]);`);
+    const geoKey = mesh.key || mesh;
+    let g = bakedGeos.get(geoKey);
+    if (!g) {
+      g = fresh('g');
+      bakedGeos.set(geoKey, g);
+      const positions = `new Float32Array([${nums(mesh.positions)}])`;
+      defs.push(`  const ${g} = new THREE.BufferGeometry();`);
+      defs.push(`  ${g}.setAttribute('position', new THREE.BufferAttribute(${positions}, 3));`);
+      if (mesh.normals) defs.push(`  ${g}.setAttribute('normal', new THREE.BufferAttribute(new Float32Array([${nums(mesh.normals)}]), 3));`);
+      defs.push(`  ${g}.setIndex([${Array.from(mesh.indices).join(', ')}]);`);
+    }
     const m = material(node.material, node.doubleSided);
     const id = fresh('o');
     const kind = mesh.kind === 'lines' ? 'LineSegments' : 'Mesh';
@@ -289,6 +298,7 @@ export function exportThree(model) {
 ${helper}
 export function createScene() {
   const root = new THREE.Group();
+${defs.join('\n')}
 ${lines.join('\n')}
   return root;
 }

package/src/io/usd.js

@@ -220,7 +220,7 @@ export function exportUSD(model) {
     const inst = g.matrix || matrix;
     if ((uses.get(key) || 0) > 1) {
       const id = ensureProto(shape);
-      return `        def Xform "${name}" (\n            prepend references = </World/Prototypes/${id}>\n        ) {\n            token visibility = "inherited"\n${indent(xformBlock(inst, ''), 12)}${indent(bind, 12)}        }`;
+      return `        def "${name}" (\n            prepend references = </World/Prototypes/${id}>\n        ) {\n            token visibility = "inherited"\n${indent(xformBlock(inst, ''), 12)}${indent(bind, 12)}        }`;
     }
     const combined = g.matrix ? inst : combine(matrix, g.local);
     return `        def ${g.type} "${name}" {\n${indent(g.body, 12)}${indent(xformBlock(combined, ''), 12)}${indent(bind, 12)}        }`;
@@ -439,6 +439,27 @@ function blockNamed(text, type, name) {
   return sliceBlock(text, open);
 }
 
+/** The text of a prim's body without the bodies of the prims defined inside it. */
+function ownText(body) {
+  let out = '';
+  let i = 0;
+  while (i < body.length) {
+    const at = body.indexOf('def ', i);
+    if (at < 0) { out += body.slice(i); break; }
+    out += body.slice(i, at);
+    const open = body.indexOf('{', at);
+    if (open < 0) break;
+    let depth = 0;
+    let j = open;
+    for (; j < body.length; j++) {
+      if (body[j] === '{') depth++;
+      else if (body[j] === '}' && --depth === 0) break;
+    }
+    i = j + 1;
+  }
+  return out;
+}
+
 function listPrims(text) {
   const out = [];
   let i = 0;
@@ -447,22 +468,25 @@ function listPrims(text) {
     if (at < 0) break;
     const before = text.slice(i, at);
     if ((before.match(/\{/g) || []).length !== (before.match(/\}/g) || []).length) { i = at + 4; continue; }
-    const head = /^def\s+([A-Za-z0-9_]+)\s+"([^"]+)"\s*(\([^)]*\))?/.exec(text.slice(at));
+    const head = /^def\s+(?:([A-Za-z0-9_]+)\s+)?"([^"]+)"\s*(\([^)]*\))?/.exec(text.slice(at));
     if (!head) { i = at + 4; continue; }
     const open = text.indexOf('{', at + head[0].length - 1);
     if (open < 0) break;
     const body = sliceBlock(text, open);
-    out.push({ type: head[1], name: head[2], meta: head[3] || '', body });
+    out.push({ type: head[1] || '', name: head[2], meta: head[3] || '', body });
     i = open + body.length + 2;
   }
   return out;
 }
 
 function emitPrim(prim, lib, materials, paint, notes, parent, inherited) {
-  const local = readXform(prim.body);
+  // A prim's own transform and binding, not those of the prims nested in it.
+  const own = ownText(prim.body);
+  const local = readXform(own);
   const matrix = combine(parent, local);
-  const style = paint(prim.body, materials) || inherited || '';
-  if (prim.type === 'Xform') {
+  const style = paint(own, materials) || inherited || '';
+  // A typeless def takes its type from the prototype it references.
+  if (prim.type === 'Xform' || prim.type === '') {
     const ref = /references\s*=\s*<([^>]+)>/.exec(prim.meta);
     const target = ref ? lib.get(ref[1].split('/').pop()) : null;
     if (target) return emitPrim(target, lib, materials, paint, notes, matrix, style);

package/src/io/x3d.js

@@ -592,7 +592,7 @@ export function importX3D(text) {
     i = step.i;
   }
   materialAttrs.materials = [];
-  const parts = nodes.map((node) => emitEs3d(node, notes)).filter(Boolean);
+  const parts = nodes.map((node) => emitEs3d(node, notes, defs)).filter(Boolean);
   const mats = materialAttrs.materials;
   materialAttrs.materials = [];
   const markup = `<es3d version="1">\n${mats.join('\n')}${mats.length ? '\n' : ''}${parts.join('\n')}\n</es3d>\n`;
@@ -734,7 +734,7 @@ function numAttr(list, count) {
   return nums.slice(0, count);
 }
 
-function emitEs3d(node, notes) {
+function emitEs3d(node, notes, defs) {
   if (!node) return '';
   if (node.use) return `<use ref="${esc(node.use)}"/>`;
   const f = node.fields || {};
@@ -743,11 +743,13 @@ function emitEs3d(node, notes) {
   if (node.name === 'Transform' || node.name === 'Group' || node.name === 'Anchor' || node.name === 'Collision' || node.name === 'Switch' || node.name === 'Billboard') {
     if (node.name !== 'Transform' && node.name !== 'Group') notes.push(`<${node.name}> was written as a group.`);
     const tr = x3dTransform(f);
-    const body = kids.map((c) => emitEs3d(c, notes)).filter(Boolean).join('\n');
+    const body = kids.map((c) => emitEs3d(c, notes, defs)).filter(Boolean).join('\n');
     return `<group${id}${tr}>\n${body}\n</group>`;
   }
   if (node.name === 'Shape') {
-    const geom = f.geometry && f.geometry.name ? f.geometry : null;
+    // geometry USE G names a node defined earlier; draw that geometry here too.
+    const used = f.geometry && f.geometry.use && defs ? defs.get(f.geometry.use) : null;
+    const geom = f.geometry && f.geometry.name ? f.geometry : (used && used.name ? used : null);
     const style = materialAttrs(f.appearance, notes);
     if (!geom) return '';
     return emitGeom(geom, id, style, notes);

package/src/render/frame-builder.js

@@ -21,6 +21,41 @@ function length3(x, y, z) {
   return Math.sqrt(x * x + y * y + z * z);
 }
 
+/**
+ * Per-frame constants for `instancePixelsPerUnit`.
+ * `ppuFactor` is F = viewportHeight / (2 tan(verticalFov / 2)) for a perspective
+ * camera, or the constant scale for an orthographic one. `cornerStretch` is
+ * 1/cos^2 of the angle to the frustum's corner.
+ */
+export function lodFrameConstants(camera, viewportHeight) {
+  const aspect = camera.aspect || 1;
+  const tanV = Math.tan(camera.verticalFov(aspect) / 2);
+  return {
+    orthographic: camera.type === 'orthographic',
+    ppuFactor: camera.pixelsPerUnit(1, viewportHeight),
+    view: camera.view,
+    cornerStretch: 1 + tanV * tanV * (1 + aspect * aspect),
+  };
+}
+
+/**
+ * Largest projected size, in CSS pixels, of a unit length at the centre
+ * (cx, cy, cz) of an instance's bounding sphere; `d` is the distance from the
+ * eye to that centre. A flat image plane stretches a displacement at angle a
+ * from the view axis by up to 1/cos^2(a) = d^2/z^2 (z = depth along the axis)
+ * radially. Inside the view that never exceeds its value at the frustum's
+ * corners, which is also used when the centre is at or behind the eye plane
+ * while the sphere is still visible. Orthographic views do not stretch.
+ * Allocation-free: it runs once per instance.
+ */
+export function instancePixelsPerUnit(k, cx, cy, cz, d) {
+  if (k.orthographic) return k.ppuFactor;
+  const V = k.view;
+  const z = -(V[2] * cx + V[6] * cy + V[10] * cz + V[14]);
+  const stretch = z > 0 ? Math.min((d * d) / (z * z), k.cornerStretch) : k.cornerStretch;
+  return (k.ppuFactor * stretch) / Math.max(d, 1e-6);
+}
+
 /**
  * The level to draw while `lod` is not generated yet: the nearest coarser
  * level that exists, else the nearest finer one, else the coarsest level
@@ -159,8 +194,8 @@ export class FrameBuilder {
     const vh = p.viewportHeight;
     const bias = options.lodBias || 1;
     const fixedLod = options.autoLod === false ? options.fixedLod || 0 : -1;
-    // pixels per world unit at distance 1 (perspective) or everywhere (orthographic)
-    const ppuFactor = camera.pixelsPerUnit(1, vh);
+    // pixels per world unit: depth based for perspective, constant for orthographic
+    const lodK = lodFrameConstants(camera, vh);
 
     for (let i = 0; i < n; i++) {
       keys[i] = -1;
@@ -189,7 +224,7 @@ export class FrameBuilder {
         else {
           const dx = cx - camPos[0], dy = cy - camPos[1], dz = cz - camPos[2];
           const d = length3(dx, dy, dz);
-          const ppu = camera.type === 'orthographic' ? ppuFactor : ppuFactor / Math.max(d, 1e-6);
+          const ppu = instancePixelsPerUnit(lodK, cx, cy, cz, d);
           lod = selectLod(entry.lodDeviation, entry.lods, axisScale(scene.matrices, i), ppu, bias);
         }
       }