poppygl 0.0.34 → 0.0.35

package/README.md

@@ -133,10 +133,43 @@ 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` and finite grid lines 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 and finite grid lines;
+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

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];
@@ -100,6 +102,16 @@ interface RenderOptions {
     debugFontSize?: number | null;
     debugPointColor?: readonly [number, number, number] | null;
     debugLabelColor?: readonly [number, number, number] | 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. */
+    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 +207,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;

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,12 @@ var DEFAULT_RENDER_OPTIONS = {
   debugPoints: null,
   debugFontSize: null,
   debugPointColor: null,
-  debugLabelColor: null
+  debugLabelColor: null,
+  showEdges: false,
+  showHiddenEdges: null,
+  edgeWidth: 1,
+  lineWidth: 1,
+  hiddenEdgeOpacity: 0.35
 };
 function getDefaultRenderOptions() {
   return { ...DEFAULT_RENDER_OPTIONS };
@@ -679,6 +692,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 +836,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 +846,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 +881,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 +983,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 +1656,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";
@@ -2306,7 +2475,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,21 +2513,25 @@ 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
     });
   }
   if (options.debugPoints?.length) {

package/package.json

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