poppygl 0.0.26 → 0.0.27

package/README.md

@@ -67,6 +67,30 @@ const png = await renderGLTFToPNGFromGLB(glb, {
 
 You can inspect the defaults via `getDefaultRenderOptions()` or reuse the internal merge logic with `resolveRenderOptions()`.
 
+### Hidden edges for selected sub-models
+
+Set `showHiddenEdges` in a glTF node's `extras` to render that node with solid
+visible edges and faint dashed edges where its geometry is occluded:
+
+```json
+{
+  "nodes": [
+    { "name": "Housing", "mesh": 0 },
+    {
+      "name": "InternalBracket",
+      "mesh": 1,
+      "extras": { "showHiddenEdges": true }
+    }
+  ]
+}
+```
+
+The namespaced form `{ "extras": { "poppygl": { "showHiddenEdges": true } } }`
+is also supported. The setting can be placed on a mesh or primitive; primitive
+extras take precedence over node extras, which take precedence over mesh extras.
+PoppyGL derives boundary and crease edges from triangle geometry, so no line
+primitives need to be added to the asset.
+
 ## If you already have the GLTF JSON
 
 When the GLTF JSON object is already in memory (for example, bundled with your app), skip the network loader and supply resources directly:

package/dist/index.d.ts

@@ -25,6 +25,7 @@ interface DrawCall {
     material: Material;
     colors?: Float32Array | null;
     mode?: number;
+    showHiddenEdges?: boolean;
 }
 interface GridOptions {
     size?: number | readonly [number, number, number];
@@ -114,6 +115,13 @@ declare function resolveRenderOptions(options?: RenderOptionsInput): RenderOptio
 
 declare function createGrid(options?: GridOptions): DrawCall;
 
+/**
+ * Builds a line draw call from the boundary and crease edges of a triangle
+ * mesh. Vertices are welded by position so glTF meshes that duplicate vertices
+ * for normals or UV seams do not produce coplanar triangulation lines.
+ */
+declare function createEdgeDrawCall(mesh: DrawCall, creaseAngleDegrees?: number): DrawCall | null;
+
 /**
  * Creates an infinite grid that matches the appearance of the 3d-viewer reference.
  * This grid uses a special rendering approach with procedural generation and fading.
@@ -163,6 +171,14 @@ interface LightSettings {
     dir: readonly [number, number, number];
     ambient: number;
 }
+interface LineRenderOptions {
+    depthCompare?: "less" | "less-equal" | "greater";
+    depthWrite?: boolean;
+    depthBias?: number;
+    dashed?: boolean;
+    dashLength?: number;
+    opacity?: number;
+}
 declare class SoftwareRenderer {
     readonly width: number;
     readonly height: number;
@@ -172,7 +188,7 @@ declare class SoftwareRenderer {
     get buffer(): Uint8Array<ArrayBufferLike> | Uint8ClampedArray<ArrayBufferLike>;
     clear(colorRGBA?: [number, number, number, number]): void;
     setPixel(x: number, y: number, r: number, g: number, b: number, a: number): void;
-    drawLines(mesh: DrawCall, camera: Camera, gammaOut?: boolean): void;
+    drawLines(mesh: DrawCall, camera: Camera, gammaOut?: boolean, options?: LineRenderOptions): void;
     sampleTextureNearest(img: BitmapLike | null, u: number, v: number): MutableRGBA;
     perspInterp(attrs: number[][], invWs: number[], lambdas: number[]): number[];
     drawMesh(mesh: DrawCall, camera: Camera, light: LightSettings, material: Material, cullBackFaces?: boolean, gammaOut?: boolean): void;
@@ -204,4 +220,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 LoadGLTFWithResourcesFromURLOptions, type Material, type MutableRGBA, type RGBA, type RenderGLTFToPNGFromGLBOptions, type RenderGLTFToPNGFromURLOptions, type RenderOptions, type RenderOptionsInput, type RenderResult, SoftwareRenderer, bufferFromDataURI, buildCamera, computeSmoothNormals, computeWorldAABB, 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 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

@@ -249,6 +249,87 @@ function createGrid(options = {}) {
   };
 }
 
+// lib/gltf/createEdgeDrawCall.ts
+var DEFAULT_CREASE_ANGLE_DEGREES = 30;
+function positionKey(positions, index) {
+  return `${positions[index * 3 + 0]},${positions[index * 3 + 1]},${positions[index * 3 + 2]}`;
+}
+function triangleNormal(positions, i0, i1, i2) {
+  const ax = positions[i1 * 3 + 0] - positions[i0 * 3 + 0];
+  const ay = positions[i1 * 3 + 1] - positions[i0 * 3 + 1];
+  const az = positions[i1 * 3 + 2] - positions[i0 * 3 + 2];
+  const bx = positions[i2 * 3 + 0] - positions[i0 * 3 + 0];
+  const by = positions[i2 * 3 + 1] - positions[i0 * 3 + 1];
+  const bz = positions[i2 * 3 + 2] - positions[i0 * 3 + 2];
+  const nx = ay * bz - az * by;
+  const ny = az * bx - ax * bz;
+  const nz = ax * by - ay * bx;
+  const length = Math.hypot(nx, ny, nz);
+  if (length === 0) return null;
+  return [nx / length, ny / length, nz / length];
+}
+function addEdge(edges, positions, i0, i1, normal) {
+  const key0 = positionKey(positions, i0);
+  const key1 = positionKey(positions, i1);
+  const isForward = key0 < key1;
+  const key = isForward ? `${key0}|${key1}` : `${key1}|${key0}`;
+  const indices = isForward ? [i0, i1] : [i1, i0];
+  const existing = edges.get(key);
+  if (existing) {
+    if (normal) existing.normals.push(normal);
+  } else {
+    edges.set(key, { indices, normals: normal ? [normal] : [] });
+  }
+}
+function hasCrease(normals, minimumDot) {
+  if (normals.length < 2) return true;
+  for (let i = 0; i < normals.length; i++) {
+    for (let j = i + 1; j < normals.length; j++) {
+      const a = normals[i];
+      const b = normals[j];
+      const dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+      if (dot < minimumDot) return true;
+    }
+  }
+  return false;
+}
+function createEdgeDrawCall(mesh, creaseAngleDegrees = DEFAULT_CREASE_ANGLE_DEGREES) {
+  if (mesh.mode != null && mesh.mode !== 4) return null;
+  const vertexCount = Math.floor(mesh.positions.length / 3);
+  const triangleIndices = mesh.indices ?? Uint32Array.from({ length: vertexCount }, (_, i) => i);
+  if (triangleIndices.length < 3) return null;
+  const edges = /* @__PURE__ */ new Map();
+  for (let i = 0; i + 2 < triangleIndices.length; i += 3) {
+    const i0 = triangleIndices[i];
+    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);
+  }
+  const minimumDot = Math.cos(creaseAngleDegrees * Math.PI / 180);
+  const edgeIndices = [];
+  for (const edge2 of edges.values()) {
+    if (!hasCrease(edge2.normals, minimumDot)) continue;
+    edgeIndices.push(edge2.indices[0], edge2.indices[1]);
+  }
+  if (edgeIndices.length === 0) return null;
+  return {
+    positions: mesh.positions,
+    normals: null,
+    uvs: null,
+    indices: new Uint32Array(edgeIndices),
+    model: mesh.model,
+    material: {
+      baseColorFactor: [0, 0, 0, 1],
+      baseColorTexture: null,
+      alphaMode: "BLEND"
+    },
+    mode: 1
+  };
+}
+
 // lib/image/createUint8Bitmap.ts
 var createUint8Bitmap = (width, height) => ({
   width,
@@ -459,7 +540,7 @@ var SoftwareRenderer = class {
     this.buffer[idx + 2] = b;
     this.buffer[idx + 3] = a;
   }
-  drawLines(mesh, camera, gammaOut = true) {
+  drawLines(mesh, camera, gammaOut = true, options = {}) {
     const { positions, indices, model, material } = mesh;
     if (!indices) return;
     const view = camera.view;
@@ -507,7 +588,12 @@ var SoftwareRenderer = class {
     const r255 = r * 255 | 0;
     const g255 = g * 255 | 0;
     const b255 = b * 255 | 0;
-    const a255 = clamp(a, 0, 1) * 255 | 0;
+    const opacity = clamp(options.opacity ?? 1, 0, 1);
+    const sourceAlpha = clamp(a, 0, 1) * opacity;
+    const depthCompare = options.depthCompare ?? "less";
+    const depthWrite = options.depthWrite ?? true;
+    const depthBias = options.depthBias ?? 0;
+    const dashLength = Math.max(1, options.dashLength ?? 4);
     for (let i = 0; i < indices.length; i += 2) {
       const i0 = indices[i + 0];
       const i1 = indices[i + 1];
@@ -534,13 +620,28 @@ var SoftwareRenderer = class {
       let y = y0;
       let z = z0_01;
       for (let k = 0; k <= steps; k++) {
+        if (options.dashed && Math.floor(k / dashLength) % 2 === 1) {
+          x += xinc;
+          y += yinc;
+          z += zinc;
+          continue;
+        }
         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;
-          if (z < this.depth[di]) {
-            this.depth[di] = z;
-            this.setPixel(xi, yi, r255, g255, b255, a255);
+          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);
           }
         }
         x += xinc;
@@ -1249,6 +1350,24 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
     });
   }
   renderGroup(blendDraws);
+  for (const dc of drawCalls) {
+    if (!dc.showHiddenEdges) continue;
+    const edgeDrawCall = createEdgeDrawCall(dc);
+    if (!edgeDrawCall) continue;
+    renderer.drawLines(edgeDrawCall, camera, options.gamma, {
+      depthCompare: "less-equal",
+      depthWrite: false,
+      depthBias: 1e-4
+    });
+    renderer.drawLines(edgeDrawCall, camera, options.gamma, {
+      depthCompare: "greater",
+      depthWrite: false,
+      depthBias: 1e-4,
+      dashed: true,
+      dashLength: 4 * options.supersampling,
+      opacity: 0.35
+    });
+  }
   if (options.debugPoints?.length) {
     drawDebugPoints(
       renderer,
@@ -1363,6 +1482,15 @@ var NUM_COMPONENTS = {
   MAT3: 9,
   MAT4: 16
 };
+function readShowHiddenEdges(extras) {
+  if (typeof extras?.poppygl?.showHiddenEdges === "boolean") {
+    return extras.poppygl.showHiddenEdges;
+  }
+  if (typeof extras?.showHiddenEdges === "boolean") {
+    return extras.showHiddenEdges;
+  }
+  return void 0;
+}
 function getBufferViewSlice(ctx, bufferViewIndex, byteOffset) {
   const { gltf, buffers } = ctx;
   const bufferView = gltf.bufferViews?.[bufferViewIndex];
@@ -1596,7 +1724,8 @@ function createSceneFromGLTF(gltf, resources) {
             indices,
             model: world,
             material,
-            colors
+            colors,
+            showHiddenEdges: readShowHiddenEdges(primitive.extras) ?? readShowHiddenEdges(node.extras) ?? readShowHiddenEdges(mesh.extras) ?? false
           });
         }
       }
@@ -1954,6 +2083,7 @@ export {
   buildCamera,
   computeSmoothNormals,
   computeWorldAABB,
+  createEdgeDrawCall,
   createGrid,
   createInfiniteGrid,
   createSceneFromGLTF,

package/package.json

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