poppygl 0.0.34 → 0.0.36

package/README.md

@@ -133,10 +133,44 @@ const png = await renderGLTFToPNGFromGLB(glb, {
 - `cull`: enable back-face culling (default `true`).
 - `backgroundColor`: a hex string such as `"#e5e7eb"`, or an RGB tuple with values from 0 to 1.
 - `grid`: show a ground grid (default `false`), or provide grid options.
+- `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`, 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).
 
 You can inspect the defaults via `getDefaultRenderOptions()` or reuse the internal merge logic with `resolveRenderOptions()`.
 
+### Thicker edges and hidden geometry
+
+Enable edges directly when rendering an ordinary glTF or GLB, without editing its metadata:
+
+```ts
+const png = await renderGLTFToPNGFromGLB(glb, {
+  showHiddenEdges: true,
+  edgeWidth: 2.5,
+  hiddenEdgeOpacity: 0.35,
+  supersampling: 2,
+  backgroundColor: "#ffffff",
+})
+```
+
+Use `showEdges: true` for solid visible edges alone. Hidden segments use the
+scene depth buffer and appear dashed; edge overlays never replace geometry depth.
+Boundary and crease edges are extracted from the original triangle geometry,
+excluding coplanar triangulation diagonals. Smooth curved silhouettes are not
+additional extracted edges.
+
+Widths stay constant in the final image when supersampling changes. Positive,
+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, finite grid lines,
+and explosion guides, including arrowhead strokes. The procedural infinite grid
+keeps its existing independent styling.
+
 ### Hidden edges for selected sub-models
 
 Set `showHiddenEdges` in a glTF node's `extras` to render that node with solid
@@ -205,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

@@ -31,6 +31,8 @@ interface DrawCall {
     colors?: Float32Array | null;
     mode?: number;
     showHiddenEdges?: boolean;
+    /** Source triangle third vertices for each extracted edge segment. */
+    edgeAdjacentVertices?: number[][];
 }
 interface GridOptions {
     size?: number | readonly [number, number, number];
@@ -67,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;
@@ -100,6 +117,17 @@ 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, finite grid lines, and explosion guides in output pixels. */
+    lineWidth: number;
+    /** Opacity of dashed, occluded mesh edges, from 0 to 1. */
+    hiddenEdgeOpacity: number;
 }
 type RenderOptionsInput = Partial<RenderOptions>;
 declare const DEFAULT_RENDER_OPTIONS: RenderOptions;
@@ -195,6 +223,8 @@ interface LightSettings {
     ambient: number;
 }
 interface LineRenderOptions {
+    /** Stroke width in this renderer's raster pixels. Defaults to one. */
+    width?: number;
     depthCompare?: "less" | "less-equal" | "greater";
     depthWrite?: boolean;
     depthBias?: number;
@@ -249,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

@@ -271,7 +271,7 @@ function triangleNormal(positions, i0, i1, i2) {
   if (length === 0) return null;
   return [nx / length, ny / length, nz / length];
 }
-function addEdge(edges, positions, i0, i1, normal) {
+function addEdge(edges, positions, i0, i1, thirdVertex, normal) {
   const key0 = positionKey(positions, i0);
   const key1 = positionKey(positions, i1);
   const isForward = key0 < key1;
@@ -280,8 +280,13 @@ function addEdge(edges, positions, i0, i1, normal) {
   const existing = edges.get(key);
   if (existing) {
     if (normal) existing.normals.push(normal);
+    existing.adjacentVertices.push(thirdVertex);
   } else {
-    edges.set(key, { indices, normals: normal ? [normal] : [] });
+    edges.set(key, {
+      indices,
+      normals: normal ? [normal] : [],
+      adjacentVertices: [thirdVertex]
+    });
   }
 }
 function hasCrease(normals, minimumDot) {
@@ -307,15 +312,17 @@ function createEdgeDrawCall(mesh, creaseAngleDegrees = DEFAULT_CREASE_ANGLE_DEGR
     const i1 = triangleIndices[i + 1];
     const i2 = triangleIndices[i + 2];
     const normal = triangleNormal(mesh.positions, i0, i1, i2);
-    addEdge(edges, mesh.positions, i0, i1, normal);
-    addEdge(edges, mesh.positions, i1, i2, normal);
-    addEdge(edges, mesh.positions, i2, i0, normal);
+    addEdge(edges, mesh.positions, i0, i1, i2, normal);
+    addEdge(edges, mesh.positions, i1, i2, i0, normal);
+    addEdge(edges, mesh.positions, i2, i0, i1, normal);
   }
   const minimumDot = Math.cos(creaseAngleDegrees * Math.PI / 180);
   const edgeIndices = [];
+  const edgeAdjacentVertices = [];
   for (const edge2 of edges.values()) {
     if (!hasCrease(edge2.normals, minimumDot)) continue;
     edgeIndices.push(edge2.indices[0], edge2.indices[1]);
+    edgeAdjacentVertices.push(edge2.adjacentVertices);
   }
   if (edgeIndices.length === 0) return null;
   return {
@@ -329,7 +336,8 @@ function createEdgeDrawCall(mesh, creaseAngleDegrees = DEFAULT_CREASE_ANGLE_DEGR
       baseColorTexture: null,
       alphaMode: "BLEND"
     },
-    mode: 1
+    mode: 1,
+    edgeAdjacentVertices
   };
 }
 
@@ -490,7 +498,13 @@ var DEFAULT_RENDER_OPTIONS = {
   debugPoints: null,
   debugFontSize: null,
   debugPointColor: null,
-  debugLabelColor: null
+  debugLabelColor: null,
+  explosionLines: null,
+  showEdges: false,
+  showHiddenEdges: null,
+  edgeWidth: 1,
+  lineWidth: 1,
+  hiddenEdgeOpacity: 0.35
 };
 function getDefaultRenderOptions() {
   return { ...DEFAULT_RENDER_OPTIONS };
@@ -679,6 +693,98 @@ var GeometryDenoiser = class {
   }
 };
 
+// lib/render/rasterizeWideLine.ts
+function clipLine(start, end, marginX, marginY) {
+  if (![...start, ...end].every(Number.isFinite)) return null;
+  const distances = (p) => [
+    p[3] * (1 + marginX) + p[0],
+    p[3] * (1 + marginX) - p[0],
+    p[3] * (1 + marginY) + p[1],
+    p[3] * (1 + marginY) - p[1],
+    p[3] + p[2],
+    p[3] - p[2]
+  ];
+  const a = distances(start);
+  const b = distances(end);
+  let from = 0;
+  let to = 1;
+  for (let plane = 0; plane < 6; plane++) {
+    if (a[plane] < 0 && b[plane] < 0) return null;
+    if (a[plane] < 0 !== b[plane] < 0) {
+      const t = a[plane] / (a[plane] - b[plane]);
+      if (a[plane] < 0) from = Math.max(from, t);
+      else to = Math.min(to, t);
+    }
+  }
+  if (from > to) return null;
+  return [from, to].map(
+    (t) => Array.from(start, (value, axis) => value + t * (end[axis] - value))
+  );
+}
+function rasterizeWideLine(start, end, width, height, strokeWidth, dashed, dashLength, fragment) {
+  const radius = strokeWidth / 2;
+  const padding = radius + 0.5;
+  const clipped = clipLine(
+    start,
+    end,
+    2 * padding / Math.max(1, width - 1),
+    2 * padding / Math.max(1, height - 1)
+  );
+  if (!clipped) return;
+  const project = (p) => [
+    (p[0] / p[3] * 0.5 + 0.5) * (width - 1),
+    (0.5 - p[1] / p[3] * 0.5) * (height - 1),
+    // Clipping guarantees this range; absorb near/far-plane roundoff so an
+    // endpoint's round cap is not discarded at z = -epsilon.
+    Math.max(0, Math.min(1, p[2] / p[3] * 0.5 + 0.5))
+  ];
+  const a = project(clipped[0]);
+  const b = project(clipped[1]);
+  if (![...a, ...b].every(Number.isFinite)) return;
+  const [x0, y0, z0] = a;
+  const [x1, y1, z1] = b;
+  const dx = x1 - x0;
+  const dy = y1 - y0;
+  const lengthSquared = dx * dx + dy * dy;
+  const length = Math.sqrt(lengthSquared);
+  const original = start[3] > 0 ? project(start) : a;
+  const phase = Math.hypot(x0 - original[0], y0 - original[1]);
+  const drawPixel = (x, y) => {
+    const t = lengthSquared === 0 ? 0 : Math.max(
+      0,
+      Math.min(1, ((x - x0) * dx + (y - y0) * dy) / lengthSquared)
+    );
+    if (dashed && Math.floor((phase + t * length) / dashLength) % 2 === 1)
+      return;
+    const distance = Math.hypot(x - (x0 + t * dx), y - (y0 + t * dy));
+    const coverage = Math.min(1, padding - distance);
+    if (coverage > 0) fragment(x, y, z0 + t * (z1 - z0), coverage);
+  };
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    const band = length === 0 ? padding : padding * length / Math.abs(dx);
+    const first = Math.max(0, Math.ceil(Math.min(x0, x1) - padding));
+    const last = Math.min(width - 1, Math.floor(Math.max(x0, x1) + padding));
+    for (let x = first; x <= last; x++) {
+      const t = dx === 0 ? 0 : Math.max(0, Math.min(1, (x - x0) / dx));
+      const centerY = y0 + t * dy;
+      const top = Math.max(0, Math.ceil(centerY - band));
+      const bottom = Math.min(height - 1, Math.floor(centerY + band));
+      for (let y = top; y <= bottom; y++) drawPixel(x, y);
+    }
+  } else {
+    const band = padding * length / Math.abs(dy);
+    const first = Math.max(0, Math.ceil(Math.min(y0, y1) - padding));
+    const last = Math.min(height - 1, Math.floor(Math.max(y0, y1) + padding));
+    for (let y = first; y <= last; y++) {
+      const t = Math.max(0, Math.min(1, (y - y0) / dy));
+      const centerX = x0 + t * dx;
+      const left = Math.max(0, Math.ceil(centerX - band));
+      const right = Math.min(width - 1, Math.floor(centerX + band));
+      for (let x = left; x <= right; x++) drawPixel(x, y);
+    }
+  }
+}
+
 // lib/render/SoftwareRenderer.ts
 var SoftwareRenderer = class {
   width;
@@ -731,6 +837,7 @@ var SoftwareRenderer = class {
     const vScreen = new Array(vertexCount);
     const vInvW = new Float32Array(vertexCount);
     const vNDCz = new Float32Array(vertexCount);
+    const clipVertices = [];
     for (let i = 0; i < vertexCount; i++) {
       const p = vec42.fromValues(
         positions[i * 3 + 0],
@@ -740,6 +847,7 @@ var SoftwareRenderer = class {
       );
       const c = vec42.create();
       vec42.transformMat4(c, p, mvp);
+      clipVertices.push(c);
       const invW = 1 / c[3];
       vInvW[i] = invW;
       if (!isFinite(invW)) {
@@ -774,9 +882,76 @@ var SoftwareRenderer = class {
     const depthWrite = options.depthWrite ?? true;
     const depthBias = options.depthBias ?? 0;
     const dashLength = Math.max(1, options.dashLength ?? 4);
+    const strokeWidth = typeof options.width === "number" && Number.isFinite(options.width) && options.width > 0 ? options.width : 1;
+    const drawFragment = (xi, yi, z, coverage = 1) => {
+      if (z < 0 || z > 1) return;
+      const di = yi * this.width + xi;
+      const currentDepth = this.depth[di];
+      const passesDepth = depthCompare === "greater" ? z > currentDepth + depthBias : depthCompare === "less-equal" ? z <= currentDepth + depthBias : z < currentDepth - depthBias;
+      if (!passesDepth) return;
+      if (depthWrite) this.depth[di] = z;
+      const pixelIndex = di * 4;
+      const destinationAlpha = this.buffer[pixelIndex + 3] / 255;
+      const alpha = sourceAlpha * coverage;
+      const oneMinusSourceAlpha = 1 - alpha;
+      const outAlpha = alpha + destinationAlpha * oneMinusSourceAlpha;
+      const blend = (channel, offset) => outAlpha === 0 ? 0 : (channel * alpha + this.buffer[pixelIndex + offset] * destinationAlpha * oneMinusSourceAlpha) / outAlpha;
+      this.setPixel(
+        xi,
+        yi,
+        blend(r255, 0),
+        blend(g255, 1),
+        blend(b255, 2),
+        outAlpha * 255
+      );
+    };
     for (let i = 0; i < indices.length; i += 2) {
       const i0 = indices[i + 0];
       const i1 = indices[i + 1];
+      if (strokeWidth !== 1) {
+        const sourceFaces = (mesh.edgeAdjacentVertices?.[i / 2] ?? []).flatMap(
+          (third) => {
+            if (clipVertices[i0][3] <= 0 || clipVertices[i1][3] <= 0 || clipVertices[third][3] <= 0)
+              return [];
+            const a2 = vScreen[i0];
+            const b2 = vScreen[i1];
+            const c = vScreen[third];
+            const area = edge(a2, b2, c);
+            if (!Number.isFinite(area) || area === 0) return [];
+            return [{ a: a2, b: b2, c, inverseArea: 1 / area, third }];
+          }
+        );
+        rasterizeWideLine(
+          clipVertices[i0],
+          clipVertices[i1],
+          this.width,
+          this.height,
+          strokeWidth,
+          options.dashed ?? false,
+          dashLength,
+          sourceFaces.length === 0 ? drawFragment : (x2, y2, z2, coverage) => {
+            let surfaceDepth = Infinity;
+            const sample = [x2 + 0.5, y2 + 0.5];
+            for (const face of sourceFaces) {
+              const l0 = edge(face.b, face.c, sample) * face.inverseArea;
+              const l1 = edge(face.c, face.a, sample) * face.inverseArea;
+              const l2 = 1 - l0 - l1;
+              if (l0 < -1e-6 || l1 < -1e-6 || l2 < -1e-6) continue;
+              const depth = (l0 * vNDCz[i0] + l1 * vNDCz[i1] + l2 * vNDCz[face.third]) * 0.5 + 0.5;
+              if (depth >= 0 && depth <= 1) {
+                surfaceDepth = Math.min(surfaceDepth, depth);
+              }
+            }
+            drawFragment(
+              x2,
+              y2,
+              surfaceDepth === Infinity ? z2 : surfaceDepth,
+              coverage
+            );
+          }
+        );
+        continue;
+      }
       const v0s = vScreen[i0];
       const v1s = vScreen[i1];
       const z0_ndc = vNDCz[i0];
@@ -809,20 +984,7 @@ var SoftwareRenderer = class {
         const xi = Math.round(x);
         const yi = Math.round(y);
         if (xi >= 0 && xi < this.width && yi >= 0 && yi < this.height && z >= 0 && z <= 1) {
-          const di = yi * this.width + xi;
-          const currentDepth = this.depth[di];
-          const passesDepth = depthCompare === "greater" ? z > currentDepth + depthBias : depthCompare === "less-equal" ? z <= currentDepth + depthBias : z < currentDepth - depthBias;
-          if (passesDepth) {
-            if (depthWrite) this.depth[di] = z;
-            const pixelIndex = di * 4;
-            const destinationAlpha = this.buffer[pixelIndex + 3] / 255;
-            const oneMinusSourceAlpha = 1 - sourceAlpha;
-            const outAlpha = sourceAlpha + destinationAlpha * oneMinusSourceAlpha;
-            const outR = outAlpha === 0 ? 0 : (r255 * sourceAlpha + this.buffer[pixelIndex + 0] * destinationAlpha * oneMinusSourceAlpha) / outAlpha;
-            const outG = outAlpha === 0 ? 0 : (g255 * sourceAlpha + this.buffer[pixelIndex + 1] * destinationAlpha * oneMinusSourceAlpha) / outAlpha;
-            const outB = outAlpha === 0 ? 0 : (b255 * sourceAlpha + this.buffer[pixelIndex + 2] * destinationAlpha * oneMinusSourceAlpha) / outAlpha;
-            this.setPixel(xi, yi, outR, outG, outB, outAlpha * 255);
-          }
+          drawFragment(xi, yi, z);
         }
         x += xinc;
         y += yinc;
@@ -1495,9 +1657,17 @@ function resolveRenderOptions(options = {}) {
     camPos: options.camPos !== void 0 ? options.camPos : DEFAULT_RENDER_OPTIONS.camPos,
     lookAt: options.lookAt !== void 0 ? options.lookAt : DEFAULT_RENDER_OPTIONS.lookAt,
     up: resolveCameraUp(options.up),
-    cameraRotation: resolveCameraRotation(options.cameraRotation)
+    cameraRotation: resolveCameraRotation(options.cameraRotation),
+    showEdges: options.showEdges === true,
+    showHiddenEdges: typeof options.showHiddenEdges === "boolean" ? options.showHiddenEdges : null,
+    edgeWidth: resolveWidth(options.edgeWidth),
+    lineWidth: resolveWidth(options.lineWidth),
+    hiddenEdgeOpacity: typeof options.hiddenEdgeOpacity === "number" && Number.isFinite(options.hiddenEdgeOpacity) ? Math.max(0, Math.min(1, options.hiddenEdgeOpacity)) : DEFAULT_RENDER_OPTIONS.hiddenEdgeOpacity
   };
 }
+function resolveWidth(width) {
+  return typeof width === "number" && Number.isFinite(width) && width > 0 ? width : 1;
+}
 
 // lib/render/StudioLighting.ts
 import { mat4 as mat46 } from "gl-matrix";
@@ -2200,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,
@@ -2306,7 +2653,9 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
     for (let i = 0; i < dcs.length; i++) {
       const dc = dcs[i];
       if (dc.mode === 1) {
-        renderer.drawLines(dc, camera, options.gamma);
+        renderer.drawLines(dc, camera, options.gamma, {
+          width: options.lineWidth * options.supersampling
+        });
       } else {
         renderer.drawMesh(
           dc,
@@ -2342,23 +2691,64 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
   renderGroup(blendDraws);
   renderer.denoise(options.gamma);
   for (const dc of drawCalls) {
-    if (!dc.showHiddenEdges) continue;
+    const showHiddenEdges = options.showHiddenEdges ?? dc.showHiddenEdges;
+    if (!options.showEdges && !showHiddenEdges) continue;
     const edgeDrawCall = createEdgeDrawCall(dc);
     if (!edgeDrawCall) continue;
     renderer.drawLines(edgeDrawCall, camera, options.gamma, {
       depthCompare: "less-equal",
       depthWrite: false,
-      depthBias: 1e-4
+      depthBias: 1e-4,
+      width: options.edgeWidth * options.supersampling
     });
+    if (!showHiddenEdges) continue;
     renderer.drawLines(edgeDrawCall, camera, options.gamma, {
       depthCompare: "greater",
       depthWrite: false,
       depthBias: 1e-4,
       dashed: true,
       dashLength: 4 * options.supersampling,
-      opacity: 0.35
+      opacity: options.hiddenEdgeOpacity,
+      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,
@@ -2379,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;
@@ -2403,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,
@@ -2430,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",
@@ -2637,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) {
@@ -2690,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) {
@@ -2730,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.34",
+  "version": "0.0.36",
   "repository": {
     "type": "git",
     "url": "https://github.com/tscircuit/poppygl.git"