poppygl 0.0.35 → 0.0.37

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.
@@ -247,3 +295,57 @@ The only contract is that `buffers` is an array of `Uint8Array` instances and `i
 - `encodePNG` packs any `BitmapLike` into a `Uint8Array` PNG that can be written to disk or served over the network.
 
 Happy rendering!
+
+### Outline rendering
+
+```ts
+const png = await renderGLTFToPNGFromURL("https://example.com/housing.glb", {
+  renderStyle: "outline",
+  width: 1200,
+  height: 900,
+  supersampling: 2,
+  camPos: [80, 60, 100],
+  lookAt: [0, 0, 0],
+  showHiddenEdges: true,
+  edgeWidth: 1.5,
+})
+```
+
+`renderStyle: "outline"` uses white opaque surfaces, black boundary/crease
+edges and view-dependent silhouettes, and orthographic projection by default.
+Hidden edges are omitted by default, including model-level hidden-edge flags;
+`showHiddenEdges: true` adds dashed occluded strokes with `hiddenEdgeOpacity`.
+Materials, textures, vertex colors, transparency and lighting are ignored in this
+style. Input meshes are not modified. Existing shaded rendering defaults stay
+unchanged. The same options work with `renderDrawCalls`, GLB bytes, and glTF/GLB URLs.
+
+`projection: "orthographic"` also works independently of outline style.
+`orthographicHeight` sets the vertical field of view in model scene units; omit it
+to fit the transformed scene bounds with a margin. Orthographic projection preserves
+parallel edges and apparent size with distance. `camPos`, `lookAt`, `up` and
+`cameraRotation` keep their existing meanings. For an axis-aligned view choose a
+camera on that axis and an `up` axis that is not parallel to it.
+
+Section views are available in outline style:
+
+```ts
+const png = await renderGLTFToPNGFromGLB(glbBytes, {
+  renderStyle: "outline",
+  up: "y+",
+  section: { axis: "x", offset: 5, keepSide: "less", hatchSpacing: 1 },
+})
+```
+
+The plane is specified in **world glTF coordinates**, normally +Y up, using model
+scene units. `less` retains axis coordinates <= offset; `greater` retains >= offset.
+Closed cut surfaces receive diagonal hatching in the section plane (spacing defaults
+to one scene unit). Nested loops preserve cavities. Open cut chains remain uncapped; non-manifold inputs are unsupported. `createOutlineSection` exposes the prepared draw calls and
+`openChains` count for callers that need to report incomplete caps. Primitives are
+capped independently; surfaces split across separate primitives cannot form a cap.
+Sections outside or tangent to a mesh do not create artificial caps. Section cuts
+currently require outline style; shaded sections are not supported.
+
+These are raster outline illustrations, not CAD/B-rep exports: silhouettes
+follow the input tessellation, crease extraction uses a 30-degree threshold, and
+hidden lines are resolved against raster depth. Dimension annotations, paper sheet
+layout and TSX/core integration are separate downstream work.

package/dist/index.d.ts

@@ -13,6 +13,8 @@ declare const createUint8Bitmap: ImageFactory;
 interface Material {
     baseColorFactor: [number, number, number, number];
     baseColorTexture: BitmapLike | null;
+    /** Repeat rather than clamp the base-color texture (used by section hatching). */
+    baseColorTextureWrap?: "repeat" | "clamp";
     metallicFactor?: number;
     roughnessFactor?: number;
     emissiveFactor?: [number, number, number];
@@ -22,6 +24,8 @@ interface Material {
     alphaCutoff?: number;
 }
 interface DrawCall {
+    /** Generated section cap; preserve its hatch material in outline style. */
+    outlineSectionCap?: boolean;
     positions: Float32Array;
     normals: Float32Array | null;
     uvs: Float32Array | null;
@@ -60,6 +64,23 @@ interface GLTFScene {
     gltf: any;
 }
 
+type SectionAxis = "x" | "y" | "z";
+/** Axis-aligned plane in world/glTF coordinates, in model scene units. */
+interface OutlineSection {
+    axis: SectionAxis;
+    offset: number;
+    keepSide: "less" | "greater";
+    /** Distance between diagonal hatch strokes in scene units; defaults to 1. */
+    hatchSpacing?: number;
+}
+/** Prepare opaque monochrome section geometry without modifying the input.
+ * Separate primitives are capped independently; open surfaces remain uncapped.
+ */
+declare function createOutlineSection(drawCalls: DrawCall[], spec: OutlineSection): {
+    drawCalls: DrawCall[];
+    openChains: number;
+};
+
 declare const DEFAULT_LIGHT_DIR: readonly [-0.4, -0.9, -0.2];
 interface DebugPoint {
     label: string;
@@ -69,6 +90,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;
@@ -82,6 +118,14 @@ interface CameraRotation {
  */
 declare function hexToRgb(hex: string): [number, number, number] | null;
 interface RenderOptions {
+    /** White opaque surfaces with black boundary, crease and silhouette edges. */
+    renderStyle: "shaded" | "outline";
+    /** Section cuts are supported in outline style only. */
+    section: OutlineSection | null;
+    /** Outline defaults to orthographic; existing renders stay perspective. */
+    projection: "perspective" | "orthographic";
+    /** Vertical span in scene units. Null automatically fits the world bounds. */
+    orthographicHeight: number | null;
     /** Opt into metallic/roughness studio lighting and geometry-based soft shadows. */
     realistic: boolean;
     width: number;
@@ -102,13 +146,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;
@@ -121,7 +166,7 @@ interface Camera {
     view: mat4;
     proj: mat4;
 }
-declare function buildCamera(drawCalls: DrawCall[], width: number, height: number, fovDeg: number, camPos: readonly [number, number, number] | null | undefined, lookAt: readonly [number, number, number] | null | undefined, up?: CameraUp | null | undefined, cameraRotation?: CameraRotation | null | undefined): Camera;
+declare function buildCamera(drawCalls: DrawCall[], width: number, height: number, fovDeg: number, camPos: readonly [number, number, number] | null | undefined, lookAt: readonly [number, number, number] | null | undefined, up?: CameraUp | null | undefined, cameraRotation?: CameraRotation | null | undefined, projection?: "perspective" | "orthographic", orthographicHeight?: number | null): Camera;
 
 interface RenderResult {
     bitmap: BitmapLike;
@@ -139,7 +184,12 @@ declare function createGrid(options?: GridOptions): DrawCall;
  * 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;
+declare function createEdgeDrawCall(mesh: DrawCall, creaseAngleDegrees?: number, 
+/** Include view-dependent silhouettes, with crease angles measured after transforms. */
+camera?: {
+    view: mat4;
+    projection: "perspective" | "orthographic";
+}): DrawCall | null;
 
 /**
  * Creates an infinite grid that matches the appearance of the 3d-viewer reference.
@@ -263,4 +313,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 OutlineSection, type RGBA, type RenderGLTFToPNGFromGLBOptions, type RenderGLTFToPNGFromURLOptions, type RenderOptions, type RenderOptionsInput, type RenderResult, SoftwareRenderer, bufferFromDataURI, buildCamera, computeSmoothNormals, computeWorldAABB, createEdgeDrawCall, createGrid, createInfiniteGrid, createOutlineSection, createSceneFromGLTF, createUint8Bitmap, decodeImageFromBuffer, drawInfiniteGrid, encodePNG, getDefaultRenderOptions, hexToRgb, isJPG, isPNG, loadGLTFWithResourcesFromURL, renderDrawCalls, renderGLTFToPNGFromGLB, renderGLTFToPNGFromURL, renderSceneFromGLTF, resolveRenderOptions };