@es3d/es3d 1.1.1 → 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.1",
+  "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/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);
         }
       }