poppygl 0.0.35 → 0.0.36

package/README.md

@@ -136,7 +136,7 @@ const png = await renderGLTFToPNGFromGLB(glb, {
 - `showEdges`: draw visible boundary and crease edges on all triangle meshes (default `false`).
 - `showHiddenEdges`: draw visible edges plus faint dashed occluded edges on all meshes. Omit it or use `null` to preserve each model's flag; `false` disables those flags.
 - `edgeWidth`: width of both visible and hidden mesh edges in output pixels (default `1`).
-- `lineWidth`: width of glTF `LINES` and finite grid lines in output pixels (default `1`).
+- `lineWidth`: width of glTF `LINES`, finite grid lines, and explosion guides in output pixels (default `1`).
 - `hiddenEdgeOpacity`: opacity of dashed occluded mesh edges, from `0` to `1` (default `0.35`).
 - `fetchImpl`: optional override for resource loading (must match the `fetch` signature).
 
@@ -167,8 +167,9 @@ finite fractional widths are supported; invalid widths fall back to one pixel.
 Wider strokes use antialiased screen-space coverage with round caps in the
 software renderer. They are clipped before the perspective divide and remain
 depth tested across their full width. No GPU or shader runtime is required.
-`lineWidth` also applies to ordinary glTF line primitives and finite grid lines;
-the procedural infinite grid keeps its existing independent styling.
+`lineWidth` also applies to ordinary glTF line primitives, finite grid lines,
+and explosion guides, including arrowhead strokes. The procedural infinite grid
+keeps its existing independent styling.
 
 ### Hidden edges for selected sub-models
 
@@ -238,6 +239,53 @@ const png = await encodePNG(bitmap)
 
 The only contract is that `buffers` is an array of `Uint8Array` instances and `images` is an array of `BitmapLike` textures (PNG and JPEG are supported out of the box via `decodeImageFromBuffer`).
 
+## Explosion guide lines
+
+Pass `explosionLines` to any render entrypoint to draw polylines between assembled
+and displaced part positions. The caller moves the geometry and supplies the
+points in the same glTF scene frame and units (normally right-handed, +Y up).
+
+This lamp is adapted from [core's reference-surface lamp](https://github.com/tscircuit/core/blob/81bef4337570e3ac4d7dd6d30ab63481304e8147/tests/assembly/fixtures/reference-surface-lamp.tsx).
+Its base, hollow blue stem, and bulb stay in place while the hollow shade,
+mounting collar, and three spokes move together by **+60 mm on scene Y**. The
+shade mount moves from Y=92 to Y=152. Two dashed guides join corresponding points
+on its lower rim, from Y=68 to Y=128. Arrowheads at the displaced endpoints show
+the upward movement:
+
+![Assembled lamp and shade lifted 60 mm with dashed upward arrow guides](tests/render/__snapshots__/explosion-lamp.snap.png)
+
+```ts
+// explodedLampGlb already contains the shade translated +60 mm on scene Y.
+const rimPoints = [[-36 / Math.SQRT2, 36 / Math.SQRT2], [36, 0]] as const
+const png = await renderGLTFToPNGFromGLB(explodedLampGlb, {
+  explosionLines: rimPoints.map(([x, z]) => ({
+    points: [[x, 68, z], [x, 128, z]],
+    color: [0.015, 0.04, 0.08], // Linear RGB, 0..1; optional.
+    dashed: true, // Default; false gives a solid guide.
+    arrow: true, // Optional; false by default.
+  })),
+})
+```
+
+The deterministic [lamp fixture](tests/fixtures/reference-lamp.ts) and
+[visual test](tests/render/explosion-lamp.test.ts) generate the comparison without
+network assets. Open the `explosion-lamp` Cosmos example to toggle shade movement,
+guides, and arrows interactively. The separate synthetic explosion-lines snapshot
+exercises elbows, geometry occlusion, and camera clipping.
+
+Guides respect scene depth, do not write to the depth buffer, and render after
+geometry denoising. Their points contribute to automatic camera framing. Lines
+are clipped to the camera frustum before rasterization; dash length scales with
+supersampling. Omitting the option or passing an empty list preserves the existing
+rendering behavior. Each guide needs at least two finite XYZ points.
+
+Set `arrow: true` to draw a solid open arrowhead at the final authored point,
+following the final nonzero-length segment's direction. Arrowheads are at most
+10 output pixels long, capped for short segments, and scale with supersampling.
+They respect scene depth and remain solid when the shaft is dashed. `lineWidth`
+controls both the shaft and arrowhead stroke width. Omit `arrow` or set it to
+`false` for a guide without an arrow.
+
 ## Additional utilities
 
 - `loadGLTFWithResourcesFromURL` returns `{ gltf, resources }` if you prefer to inspect or cache the parsed data before rendering.

package/dist/index.d.ts

@@ -69,6 +69,21 @@ interface DebugPoint {
         z: number;
     };
 }
+/** Guide polyline in right-handed glTF scene coordinates (normally +Y up),
+ * using the model's scene units. Each vertex is a point, not a displacement.
+ */
+interface ExplosionLine {
+    points: readonly (readonly [number, number, number])[];
+    /** Linear RGB, 0..1; defaults to a muted blue. */
+    color?: readonly [number, number, number];
+    /** Defaults to true. Visible segments respect scene depth. */
+    dashed?: boolean;
+    /** Add a solid arrowhead at the last point, following the final segment.
+     * Defaults to false. The arrowhead is 10 output pixels long (or shorter for
+     * short segments), independent of camera distance and supersampling.
+     */
+    arrow?: boolean;
+}
 type CameraUp = "y+" | "y-" | "x+" | "x-" | "z+" | "z-";
 interface CameraRotation {
     x: number;
@@ -102,13 +117,14 @@ interface RenderOptions {
     debugFontSize?: number | null;
     debugPointColor?: readonly [number, number, number] | null;
     debugLabelColor?: readonly [number, number, number] | null;
+    explosionLines?: readonly ExplosionLine[] | null;
     /** Draw visible boundary and crease edges on every triangle mesh. */
     showEdges: boolean;
     /** Override model showHiddenEdges flags; null preserves each model's flag. */
     showHiddenEdges: boolean | null;
     /** Width of visible and hidden mesh edges in output pixels. */
     edgeWidth: number;
-    /** Width of glTF LINES and finite grid lines in output pixels. */
+    /** Width of glTF LINES, finite grid lines, and explosion guides in output pixels. */
     lineWidth: number;
     /** Opacity of dashed, occluded mesh edges, from 0 to 1. */
     hiddenEdgeOpacity: number;
@@ -263,4 +279,4 @@ declare function renderGLTFToPNGFromGLB(glb: ArrayBuffer | Uint8Array, options?:
 
 declare function renderSceneFromGLTF(scene: GLTFScene, options?: RenderOptionsInput, imageFactory?: ImageFactory): RenderResult;
 
-export { type BitmapLike, type Camera, type CameraRotation, type CameraUp, DEFAULT_LIGHT_DIR, DEFAULT_RENDER_OPTIONS, type DebugPoint, type DrawCall, type FetchLike, type GLTFResources, type GLTFScene, type GridOptions, type ImageFactory, type LightSettings, type LineRenderOptions, type LoadGLTFWithResourcesFromURLOptions, type Material, type MutableRGBA, type RGBA, type RenderGLTFToPNGFromGLBOptions, type RenderGLTFToPNGFromURLOptions, type RenderOptions, type RenderOptionsInput, type RenderResult, SoftwareRenderer, bufferFromDataURI, buildCamera, computeSmoothNormals, computeWorldAABB, createEdgeDrawCall, createGrid, createInfiniteGrid, createSceneFromGLTF, createUint8Bitmap, decodeImageFromBuffer, drawInfiniteGrid, encodePNG, getDefaultRenderOptions, hexToRgb, isJPG, isPNG, loadGLTFWithResourcesFromURL, renderDrawCalls, renderGLTFToPNGFromGLB, renderGLTFToPNGFromURL, renderSceneFromGLTF, resolveRenderOptions };
+export { type BitmapLike, type Camera, type CameraRotation, type CameraUp, DEFAULT_LIGHT_DIR, DEFAULT_RENDER_OPTIONS, type DebugPoint, type DrawCall, type ExplosionLine, type FetchLike, type GLTFResources, type GLTFScene, type GridOptions, type ImageFactory, type LightSettings, type LineRenderOptions, type LoadGLTFWithResourcesFromURLOptions, type Material, type MutableRGBA, type RGBA, type RenderGLTFToPNGFromGLBOptions, type RenderGLTFToPNGFromURLOptions, type RenderOptions, type RenderOptionsInput, type RenderResult, SoftwareRenderer, bufferFromDataURI, buildCamera, computeSmoothNormals, computeWorldAABB, createEdgeDrawCall, createGrid, createInfiniteGrid, createSceneFromGLTF, createUint8Bitmap, decodeImageFromBuffer, drawInfiniteGrid, encodePNG, getDefaultRenderOptions, hexToRgb, isJPG, isPNG, loadGLTFWithResourcesFromURL, renderDrawCalls, renderGLTFToPNGFromGLB, renderGLTFToPNGFromURL, renderSceneFromGLTF, resolveRenderOptions };

package/dist/index.js

@@ -499,6 +499,7 @@ var DEFAULT_RENDER_OPTIONS = {
   debugFontSize: null,
   debugPointColor: null,
   debugLabelColor: null,
+  explosionLines: null,
   showEdges: false,
   showHiddenEdges: null,
   edgeWidth: 1,
@@ -2369,13 +2370,190 @@ var StudioLighting = class {
   }
 };
 
+// lib/render/createExplosionLineDrawCall.ts
+import { mat4 as mat47, vec4 as vec45 } from "gl-matrix";
+function createExplosionLineDrawCall(line) {
+  if (line.points.length < 2 || line.points.some(
+    (point) => point.length !== 3 || !point.every(Number.isFinite)
+  )) {
+    throw new Error("Explosion lines need at least two finite XYZ points");
+  }
+  const color = line.color ?? [0.08, 0.2, 0.35];
+  if (color.length !== 3 || color.some(
+    (channel) => !Number.isFinite(channel) || channel < 0 || channel > 1
+  )) {
+    throw new Error(
+      "Explosion line colors must be linear RGB values from 0 to 1"
+    );
+  }
+  const indices = [];
+  for (let vertex = 1; vertex < line.points.length; vertex++) {
+    indices.push(vertex - 1, vertex);
+  }
+  return {
+    positions: new Float32Array(line.points.flatMap((point) => [...point])),
+    indices: new Uint32Array(indices),
+    normals: null,
+    uvs: null,
+    model: mat47.create(),
+    material: { baseColorFactor: [...color, 1], baseColorTexture: null },
+    mode: 1
+  };
+}
+function clipExplosionLineDrawCall(drawCall, camera) {
+  const viewProjection = mat47.multiply(mat47.create(), camera.proj, camera.view);
+  const positions = [];
+  const indices = [];
+  const distances = (point) => [
+    point[3] + point[0],
+    point[3] - point[0],
+    point[3] + point[1],
+    point[3] - point[1],
+    point[3] + point[2],
+    point[3] - point[2]
+  ];
+  for (let segment = 0; segment < drawCall.indices.length; segment += 2) {
+    const startIndex = drawCall.indices[segment] * 3;
+    const endIndex = drawCall.indices[segment + 1] * 3;
+    const start = vec45.fromValues(
+      drawCall.positions[startIndex],
+      drawCall.positions[startIndex + 1],
+      drawCall.positions[startIndex + 2],
+      1
+    );
+    const end = vec45.fromValues(
+      drawCall.positions[endIndex],
+      drawCall.positions[endIndex + 1],
+      drawCall.positions[endIndex + 2],
+      1
+    );
+    const startDistances = distances(
+      vec45.transformMat4(vec45.create(), start, viewProjection)
+    );
+    const endDistances = distances(
+      vec45.transformMat4(vec45.create(), end, viewProjection)
+    );
+    let from = 0;
+    let to = 1;
+    for (let plane = 0; plane < 6; plane++) {
+      const a = startDistances[plane];
+      const b = endDistances[plane];
+      if (a < 0 && b < 0) {
+        to = -1;
+        break;
+      }
+      if (a < 0 !== b < 0) {
+        const intersection = a / (a - b);
+        if (a < 0) from = Math.max(from, intersection);
+        else to = Math.min(to, intersection);
+      }
+    }
+    if (from > to) continue;
+    const vertex = positions.length / 3;
+    for (const progress of [from, to]) {
+      for (let axis = 0; axis < 3; axis++) {
+        positions.push(start[axis] + progress * (end[axis] - start[axis]));
+      }
+    }
+    indices.push(vertex, vertex + 1);
+  }
+  return {
+    ...drawCall,
+    positions: new Float32Array(positions),
+    indices: new Uint32Array(indices)
+  };
+}
+
+// lib/render/createExplosionArrowDrawCall.ts
+import { mat4 as mat48, vec4 as vec46 } from "gl-matrix";
+function createExplosionArrowDrawCall(drawCall, camera, width, height, supersampling) {
+  if (width <= 1 || height <= 1) return null;
+  const points = drawCall.positions;
+  const end = points.length - 3;
+  let start = end - 3;
+  while (start >= 0 && points[start] === points[end] && points[start + 1] === points[end + 1] && points[start + 2] === points[end + 2]) {
+    start -= 3;
+  }
+  if (start < 0) return null;
+  const viewProjection = mat48.multiply(mat48.create(), camera.proj, camera.view);
+  const tip = vec46.transformMat4(
+    vec46.create(),
+    vec46.fromValues(points[end], points[end + 1], points[end + 2], 1),
+    viewProjection
+  );
+  if (!Array.from(tip).every(Number.isFinite) || tip[3] <= 0 || Math.abs(tip[0]) > tip[3] || Math.abs(tip[1]) > tip[3] || Math.abs(tip[2]) > tip[3]) {
+    return null;
+  }
+  const clipped = clipExplosionLineDrawCall(
+    {
+      ...drawCall,
+      positions: new Float32Array([
+        points[start],
+        points[start + 1],
+        points[start + 2],
+        points[end],
+        points[end + 1],
+        points[end + 2]
+      ]),
+      indices: new Uint32Array([0, 1])
+    },
+    camera
+  );
+  if (!clipped.indices?.length) return null;
+  const tail = vec46.transformMat4(
+    vec46.create(),
+    vec46.fromValues(
+      clipped.positions[0],
+      clipped.positions[1],
+      clipped.positions[2],
+      1
+    ),
+    viewProjection
+  );
+  if (tail[3] <= 0) return null;
+  const dx = (tip[0] / tip[3] - tail[0] / tail[3]) * (width - 1) / 2;
+  const dy = (tip[1] / tip[3] - tail[1] / tail[3]) * (height - 1) / 2;
+  const length = Math.hypot(dx, dy);
+  if (!Number.isFinite(length) || length < 1e-3) return null;
+  const arrowLength = Math.min(10 * supersampling, length / 2);
+  const ux = dx / length;
+  const uy = dy / length;
+  const inverse = mat48.invert(mat48.create(), viewProjection);
+  if (!inverse) return null;
+  const positions = [points[end], points[end + 1], points[end + 2]];
+  for (const side of [-1, 1]) {
+    const offsetX = -ux * arrowLength - side * uy * arrowLength * 0.45;
+    const offsetY = -uy * arrowLength + side * ux * arrowLength * 0.45;
+    const wing = vec46.transformMat4(
+      vec46.create(),
+      vec46.fromValues(
+        tip[0] / tip[3] + 2 * offsetX / (width - 1),
+        tip[1] / tip[3] + 2 * offsetY / (height - 1),
+        tip[2] / tip[3],
+        1
+      ),
+      inverse
+    );
+    if (!Array.from(wing).every(Number.isFinite) || wing[3] === 0) return null;
+    positions.push(wing[0] / wing[3], wing[1] / wing[3], wing[2] / wing[3]);
+  }
+  return {
+    ...drawCall,
+    positions: new Float32Array(positions),
+    indices: new Uint32Array([0, 1, 0, 2])
+  };
+}
+
 // lib/render/renderDrawCalls.ts
 function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint8Bitmap) {
   const options = resolveRenderOptions(optionsInput);
   const renderWidth = options.width * options.supersampling;
   const renderHeight = options.height * options.supersampling;
+  const explosionDrawCalls = (options.explosionLines ?? []).map(
+    createExplosionLineDrawCall
+  );
   const camera = buildCamera(
-    drawCalls,
+    [...drawCalls, ...explosionDrawCalls],
     renderWidth,
     renderHeight,
     options.fov,
@@ -2534,6 +2712,43 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
       width: options.edgeWidth * options.supersampling
     });
   }
+  for (const [index, drawCall] of explosionDrawCalls.entries()) {
+    renderer.drawLines(
+      clipExplosionLineDrawCall(drawCall, camera),
+      camera,
+      options.gamma,
+      {
+        depthCompare: "less-equal",
+        depthWrite: false,
+        depthBias: 1e-4,
+        dashed: options.explosionLines[index].dashed ?? true,
+        dashLength: 4 * options.supersampling,
+        width: options.lineWidth * options.supersampling
+      }
+    );
+    if (options.explosionLines[index].arrow) {
+      const arrow = createExplosionArrowDrawCall(
+        drawCall,
+        camera,
+        renderWidth,
+        renderHeight,
+        options.supersampling
+      );
+      if (arrow) {
+        renderer.drawLines(
+          clipExplosionLineDrawCall(arrow, camera),
+          camera,
+          options.gamma,
+          {
+            depthCompare: "less-equal",
+            depthWrite: false,
+            depthBias: 1e-4,
+            width: options.lineWidth * options.supersampling
+          }
+        );
+      }
+    }
+  }
   if (options.debugPoints?.length) {
     drawDebugPoints(
       renderer,
@@ -2554,7 +2769,7 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
 }
 
 // lib/gltf/createInfiniteGrid.ts
-import { mat4 as mat47 } from "gl-matrix";
+import { mat4 as mat49 } from "gl-matrix";
 function createInfiniteGrid(options = {}) {
   const cellSize = options.cellSize ?? 1;
   const sectionSize = options.sectionSize ?? 10;
@@ -2578,9 +2793,9 @@ function createInfiniteGrid(options = {}) {
     size
   ]);
   const indices = new Uint32Array([0, 1, 2, 0, 2, 3]);
-  const model = mat47.create();
+  const model = mat49.create();
   const offset = options.offset ?? {};
-  mat47.fromTranslation(model, [offset.x ?? 0, offset.y ?? 0, offset.z ?? 0]);
+  mat49.fromTranslation(model, [offset.x ?? 0, offset.y ?? 0, offset.z ?? 0]);
   return {
     positions,
     indices,
@@ -2605,7 +2820,7 @@ function createInfiniteGrid(options = {}) {
 }
 
 // lib/gltf/createSceneFromGLTF.ts
-import { mat4 as mat48 } from "gl-matrix";
+import { mat4 as mat410 } from "gl-matrix";
 var COMPONENT_INFO = {
   5120: {
     name: "BYTE",
@@ -2812,17 +3027,17 @@ function readIndices(ctx, accessorIndex) {
 }
 function nodeLocalMatrix(node) {
   if (node.matrix) {
-    const m2 = mat48.create();
+    const m2 = mat410.create();
     for (let i = 0; i < 16; i++) m2[i] = node.matrix[i];
     return m2;
   }
   const translation = node.translation || [0, 0, 0];
   const rotation = node.rotation || [0, 0, 0, 1];
   const scale = node.scale || [1, 1, 1];
-  const m = mat48.create();
-  const tmp = mat48.create();
-  mat48.fromRotationTranslationScale(tmp, rotation, translation, scale);
-  mat48.copy(m, tmp);
+  const m = mat410.create();
+  const tmp = mat410.create();
+  mat410.fromRotationTranslationScale(tmp, rotation, translation, scale);
+  mat410.copy(m, tmp);
   return m;
 }
 function getMaterial(gltf, textures, images, materialIndex) {
@@ -2865,8 +3080,8 @@ function createSceneFromGLTF(gltf, resources) {
     const node = nodes[nodeIndex];
     if (!node) return;
     const local = nodeLocalMatrix(node);
-    const world = mat48.create();
-    mat48.multiply(world, parentMatrix, local);
+    const world = mat410.create();
+    mat410.multiply(world, parentMatrix, local);
     if (Number.isInteger(node.mesh)) {
       const mesh = meshes[node.mesh];
       if (mesh) {
@@ -2905,7 +3120,7 @@ function createSceneFromGLTF(gltf, resources) {
       traverse(childIndex, world);
     }
   }
-  const identity = mat48.create();
+  const identity = mat410.create();
   for (const rootIndex of scene.nodes || []) {
     traverse(rootIndex, identity);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poppygl",
   "main": "dist/index.js",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "repository": {
     "type": "git",
     "url": "https://github.com/tscircuit/poppygl.git"