poppygl 0.0.18 → 0.0.19

package/README.md

@@ -53,6 +53,10 @@ const png = await renderGLTFToPNGBufferFromGLBBuffer(glb, {
 - `supersampling`: render at `width * supersampling` / `height * supersampling`, then downsample (default `1`).
 - `fov`: vertical field of view in degrees (defaults to `35`).
 - `camPos` and `lookAt`: override the auto-framed camera position and target.
+- `debugPoints`: optional `{ label, position }[]` overlay rendered on top of the final PNG for world-space debugging markers.
+- `debugFontSize`: optional pixel size for `debugPoints` labels; when omitted the renderer derives a size from the image dimensions.
+- `debugPointColor`: optional RGB tuple for debug point markers.
+- `debugLabelColor`: optional RGB tuple for debug point labels.
 - `lightDir`: normalized directional light vector (defaults to a top-right key light).
 - `ambient`: ambient lighting contribution (0–1, defaults to `0.2`).
 - `gamma`: gamma correction applied to the output (defaults to `2.2`).

package/dist/index.d.ts

@@ -53,6 +53,14 @@ interface GLTFScene {
 }
 
 declare const DEFAULT_LIGHT_DIR: readonly [-0.4, -0.9, -0.2];
+interface DebugPoint {
+    label: string;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
 /**
  * Convert a hex color string to RGB array with values 0-1
  * @param hex - Hex color string like "#ffffff" or "ffffff"
@@ -72,6 +80,10 @@ interface RenderOptions {
     lookAt?: readonly [number, number, number] | null;
     backgroundColor?: readonly [number, number, number] | string | null;
     grid?: boolean | GridOptions;
+    debugPoints?: DebugPoint[] | null;
+    debugFontSize?: number | null;
+    debugPointColor?: readonly [number, number, number] | null;
+    debugLabelColor?: readonly [number, number, number] | null;
 }
 type RenderOptionsInput = Partial<RenderOptions>;
 declare const DEFAULT_RENDER_OPTIONS: RenderOptions;
@@ -188,4 +200,4 @@ declare function renderGLTFToPNGBuffer(gltfPathOrString: string, options?: Rende
 
 declare function renderSceneFromGLTF(scene: GLTFScene, options?: RenderOptionsInput, imageFactory?: ImageFactory): RenderResult;
 
-export { type BitmapLike, type Camera, DEFAULT_LIGHT_DIR, DEFAULT_RENDER_OPTIONS, type DrawCall, type FetchLike, type GLTFResources, type GLTFScene, type GridOptions, type ImageFactory, type LightSettings, type LoadGLTFWithResourcesFromURLOptions, type Material, type MutableRGBA, type RGBA, type RenderGLTFToPNGBufferFromGLBBufferOptions, type RenderGLTFToPNGBufferFromURLOptions, type RenderOptions, type RenderOptionsInput, type RenderResult, SoftwareRenderer, bufferFromDataURI, buildCamera, computeSmoothNormals, computeWorldAABB, createGrid, createInfiniteGrid, createSceneFromGLTF, createUint8Bitmap, decodeImageFromBuffer, drawInfiniteGrid, encodePNGToBuffer, getDefaultRenderOptions, hexToRgb, isJPG, isPNG, loadGLTFWithResourcesFromURL, pureImageFactory, renderDrawCalls, renderGLTFToPNGBuffer, renderGLTFToPNGBufferFromGLBBuffer, renderGLTFToPNGBufferFromURL, renderSceneFromGLTF, resolveRenderOptions };
+export { type BitmapLike, type Camera, 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 RenderGLTFToPNGBufferFromGLBBufferOptions, type RenderGLTFToPNGBufferFromURLOptions, type RenderOptions, type RenderOptionsInput, type RenderResult, SoftwareRenderer, bufferFromDataURI, buildCamera, computeSmoothNormals, computeWorldAABB, createGrid, createInfiniteGrid, createSceneFromGLTF, createUint8Bitmap, decodeImageFromBuffer, drawInfiniteGrid, encodePNGToBuffer, getDefaultRenderOptions, hexToRgb, isJPG, isPNG, loadGLTFWithResourcesFromURL, pureImageFactory, renderDrawCalls, renderGLTFToPNGBuffer, renderGLTFToPNGBufferFromGLBBuffer, renderGLTFToPNGBufferFromURL, renderSceneFromGLTF, resolveRenderOptions };

package/dist/index.js

@@ -174,207 +174,16 @@ function downsampleBitmap(source, targetWidth, targetHeight, imageFactory) {
   return target;
 }
 
-// lib/render/drawInfiniteGrid.ts
-import { mat4 as mat43, vec4 as vec42 } from "gl-matrix";
-
-// lib/utils/srgbEncodeLinear01.ts
-function srgbEncodeLinear01(linear) {
-  if (linear <= 31308e-7) return 12.92 * linear;
-  return 1.055 * Math.pow(linear, 1 / 2.4) - 0.055;
-}
-
-// lib/utils/clamp.ts
-var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
-
-// lib/render/drawInfiniteGrid.ts
-function computeGridLineIntensity(params) {
-  const rx = params.world_x / params.cell_size;
-  const rz = params.world_z / params.cell_size;
-  const fract_x = rx - Math.floor(rx + 0.5);
-  const fract_z = rz - Math.floor(rz + 0.5);
-  const grid_x = Math.abs(fract_x);
-  const grid_z = Math.abs(fract_z);
-  const pixel_size_in_world = params.dist / Math.min(params.screen_width, params.screen_height);
-  const fwidth_x = pixel_size_in_world / params.cell_size;
-  const fwidth_z = pixel_size_in_world / params.cell_size;
-  const line_x = grid_x / (fwidth_x + 1e-4);
-  const line_z = grid_z / (fwidth_z + 1e-4);
-  const line = Math.min(line_x, line_z);
-  return 1 - Math.min(line * params.line_thickness_multiplier, 1);
-}
-function computeGridFadeAlpha(params) {
-  const fade_start = params.fade_distance;
-  const fade_end = params.fade_distance * params.fade_strength;
-  return 1 - Math.min(
-    1,
-    Math.max(0, (params.dist - fade_start) / (fade_end - fade_start))
-  );
-}
-function drawInfiniteGrid(software_renderer, params) {
-  const grid_y = params.grid_y ?? 0;
-  const cell_size = params.cell_size ?? 1;
-  const section_size = params.section_size ?? 10;
-  const fade_distance = params.fade_distance ?? 100;
-  const fade_strength = params.fade_strength ?? 1.5;
-  const grid_color = params.grid_color ?? [0.93, 0.93, 0.93];
-  const section_color = params.section_color ?? [0.8, 0.8, 1];
-  const gamma_out = params.gamma_out ?? true;
-  const camera = params.camera;
-  const view = camera.view;
-  const proj = camera.proj;
-  const inv_view = mat43.create();
-  mat43.invert(inv_view, view);
-  const cam_pos_x = inv_view[12];
-  const cam_pos_y = inv_view[13];
-  const cam_pos_z = inv_view[14];
-  const vp = mat43.create();
-  mat43.multiply(vp, proj, view);
-  const inv_vp = mat43.create();
-  mat43.invert(inv_vp, vp);
-  for (let y = 0; y < software_renderer.height; y++) {
-    for (let x = 0; x < software_renderer.width; x++) {
-      const ndc_x = x / (software_renderer.width - 1) * 2 - 1;
-      const ndc_y = 1 - y / (software_renderer.height - 1) * 2;
-      const near_point = vec42.fromValues(ndc_x, ndc_y, -1, 1);
-      const far_point = vec42.fromValues(ndc_x, ndc_y, 1, 1);
-      vec42.transformMat4(near_point, near_point, inv_vp);
-      vec42.transformMat4(far_point, far_point, inv_vp);
-      near_point[0] /= near_point[3];
-      near_point[1] /= near_point[3];
-      near_point[2] /= near_point[3];
-      far_point[0] /= far_point[3];
-      far_point[1] /= far_point[3];
-      far_point[2] /= far_point[3];
-      const ray_dir_x = far_point[0] - near_point[0];
-      const ray_dir_y = far_point[1] - near_point[1];
-      const ray_dir_z = far_point[2] - near_point[2];
-      if (Math.abs(ray_dir_y) < 1e-6) continue;
-      const t = (grid_y - near_point[1]) / ray_dir_y;
-      if (t < 0 || t > 1) continue;
-      const world_x = near_point[0] + t * ray_dir_x;
-      const world_z = near_point[2] + t * ray_dir_z;
-      const world_pt = vec42.fromValues(world_x, grid_y, world_z, 1);
-      const clip_pt = vec42.create();
-      vec42.transformMat4(clip_pt, world_pt, vp);
-      const ndc_z = clip_pt[2] / clip_pt[3];
-      const depth_01 = ndc_z * 0.5 + 0.5;
-      const di = y * software_renderer.width + x;
-      if (depth_01 >= software_renderer.depth[di]) continue;
-      const dx = world_x - cam_pos_x;
-      const dy = grid_y - cam_pos_y;
-      const dz = world_z - cam_pos_z;
-      const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
-      const alpha = computeGridFadeAlpha({
-        dist,
-        fade_distance,
-        fade_strength
-      });
-      if (alpha <= 0) continue;
-      const g1 = computeGridLineIntensity({
-        world_x,
-        world_z,
-        cell_size,
-        dist,
-        screen_width: software_renderer.width,
-        screen_height: software_renderer.height,
-        line_thickness_multiplier: 0.8
-      });
-      const g2 = computeGridLineIntensity({
-        world_x,
-        world_z,
-        cell_size: section_size,
-        dist,
-        screen_width: software_renderer.width,
-        screen_height: software_renderer.height,
-        line_thickness_multiplier: 0.5
-        // Thicker section lines
-      });
-      const grid_strength = Math.max(g1, g2);
-      if (grid_strength <= 0) continue;
-      const final_r = grid_color[0] * (1 - g2) + section_color[0] * g2;
-      const final_g = grid_color[1] * (1 - g2) + section_color[1] * g2;
-      const final_b = grid_color[2] * (1 - g2) + section_color[2] * g2;
-      const final_alpha = grid_strength * alpha;
-      if (final_alpha <= 0.01) continue;
-      let out_r = final_r;
-      let out_g = final_g;
-      let out_b = final_b;
-      if (gamma_out) {
-        out_r = srgbEncodeLinear01(clamp(out_r, 0, 1));
-        out_g = srgbEncodeLinear01(clamp(out_g, 0, 1));
-        out_b = srgbEncodeLinear01(clamp(out_b, 0, 1));
-      } else {
-        out_r = clamp(out_r, 0, 1);
-        out_g = clamp(out_g, 0, 1);
-        out_b = clamp(out_b, 0, 1);
-      }
-      const dst_idx = (y * software_renderer.width + x) * 4;
-      const dst_r = (software_renderer.buffer[dst_idx + 0] ?? 0) / 255;
-      const dst_g = (software_renderer.buffer[dst_idx + 1] ?? 0) / 255;
-      const dst_b = (software_renderer.buffer[dst_idx + 2] ?? 0) / 255;
-      const dst_a = (software_renderer.buffer[dst_idx + 3] ?? 0) / 255;
-      const one_minus_a = 1 - final_alpha;
-      const blend_r = out_r * final_alpha + dst_r * one_minus_a;
-      const blend_g = out_g * final_alpha + dst_g * one_minus_a;
-      const blend_b = out_b * final_alpha + dst_b * one_minus_a;
-      const blend_a = final_alpha + dst_a * one_minus_a;
-      software_renderer.setPixel(
-        x,
-        y,
-        clamp(blend_r, 0, 1) * 255 | 0,
-        clamp(blend_g, 0, 1) * 255 | 0,
-        clamp(blend_b, 0, 1) * 255 | 0,
-        clamp(blend_a, 0, 1) * 255 | 0
-      );
-    }
-  }
-}
-
-// lib/render/getDefaultRenderOptions.ts
-var DEFAULT_LIGHT_DIR = [-0.4, -0.9, -0.2];
-function hexToRgb(hex) {
-  const cleanHex = hex.replace(/^#/, "");
-  if (!/^[0-9A-Fa-f]{6}$/.test(cleanHex)) {
-    return null;
-  }
-  const r = Number.parseInt(cleanHex.substring(0, 2), 16) / 255;
-  const g = Number.parseInt(cleanHex.substring(2, 4), 16) / 255;
-  const b = Number.parseInt(cleanHex.substring(4, 6), 16) / 255;
-  return [r, g, b];
-}
-var DEFAULT_RENDER_OPTIONS = {
-  width: 800,
-  height: 600,
-  supersampling: 1,
-  fov: 60,
-  cull: true,
-  gamma: true,
-  ambient: 0.15,
-  lightDir: DEFAULT_LIGHT_DIR,
-  camPos: null,
-  lookAt: null,
-  backgroundColor: null,
-  grid: false
-};
-function getDefaultRenderOptions() {
-  return { ...DEFAULT_RENDER_OPTIONS };
-}
-
-// lib/render/resolveRenderOptions.ts
-function resolveRenderOptions(options = {}) {
-  const supersampling = typeof options.supersampling === "number" && Number.isFinite(options.supersampling) ? Math.max(1, Math.floor(options.supersampling)) : DEFAULT_RENDER_OPTIONS.supersampling;
-  return {
-    ...DEFAULT_RENDER_OPTIONS,
-    ...options,
-    supersampling,
-    lightDir: options.lightDir != null ? options.lightDir : DEFAULT_RENDER_OPTIONS.lightDir,
-    camPos: options.camPos !== void 0 ? options.camPos : DEFAULT_RENDER_OPTIONS.camPos,
-    lookAt: options.lookAt !== void 0 ? options.lookAt : DEFAULT_RENDER_OPTIONS.lookAt
-  };
-}
+// lib/render/drawDebugPoints.ts
+import {
+  glyphAdvanceRatio,
+  glyphLineAlphabet,
+  textMetrics
+} from "@tscircuit/alphabet";
+import { mat4 as mat44, vec4 as vec43 } from "gl-matrix";
 
 // lib/render/SoftwareRenderer.ts
-import { mat3, mat4 as mat44, vec3 as vec32, vec4 as vec43 } from "gl-matrix";
+import { mat3, mat4 as mat43, vec3 as vec32, vec4 as vec42 } from "gl-matrix";
 
 // lib/gltf/computeSmoothNormals.ts
 function computeSmoothNormals(positions, indices) {
@@ -442,11 +251,54 @@ function computeSmoothNormals(positions, indices) {
   return normals;
 }
 
+// lib/render/getDefaultRenderOptions.ts
+var DEFAULT_LIGHT_DIR = [-0.4, -0.9, -0.2];
+function hexToRgb(hex) {
+  const cleanHex = hex.replace(/^#/, "");
+  if (!/^[0-9A-Fa-f]{6}$/.test(cleanHex)) {
+    return null;
+  }
+  const r = Number.parseInt(cleanHex.substring(0, 2), 16) / 255;
+  const g = Number.parseInt(cleanHex.substring(2, 4), 16) / 255;
+  const b = Number.parseInt(cleanHex.substring(4, 6), 16) / 255;
+  return [r, g, b];
+}
+var DEFAULT_RENDER_OPTIONS = {
+  width: 800,
+  height: 600,
+  supersampling: 1,
+  fov: 60,
+  cull: true,
+  gamma: true,
+  ambient: 0.15,
+  lightDir: DEFAULT_LIGHT_DIR,
+  camPos: null,
+  lookAt: null,
+  backgroundColor: null,
+  grid: false,
+  debugPoints: null,
+  debugFontSize: null,
+  debugPointColor: null,
+  debugLabelColor: null
+};
+function getDefaultRenderOptions() {
+  return { ...DEFAULT_RENDER_OPTIONS };
+}
+
 // lib/utils/mulColor.ts
 function mulColor(a, b) {
   return [a[0] * b[0], a[1] * b[1], a[2] * b[2], a[3] * b[3]];
 }
 
+// lib/utils/srgbEncodeLinear01.ts
+function srgbEncodeLinear01(linear) {
+  if (linear <= 31308e-7) return 12.92 * linear;
+  return 1.055 * Math.pow(linear, 1 / 2.4) - 0.055;
+}
+
+// lib/utils/clamp.ts
+var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
 // lib/render/SoftwareRenderer.ts
 var SoftwareRenderer = class {
   width;
@@ -486,21 +338,21 @@ var SoftwareRenderer = class {
     if (!indices) return;
     const view = camera.view;
     const proj = camera.proj;
-    const mvp = mat44.create();
-    mat44.multiply(mvp, proj, mat44.multiply(mat44.create(), view, model));
+    const mvp = mat43.create();
+    mat43.multiply(mvp, proj, mat43.multiply(mat43.create(), view, model));
     const vertexCount = positions.length / 3 | 0;
     const vScreen = new Array(vertexCount);
     const vInvW = new Float32Array(vertexCount);
     const vNDCz = new Float32Array(vertexCount);
     for (let i = 0; i < vertexCount; i++) {
-      const p = vec43.fromValues(
+      const p = vec42.fromValues(
         positions[i * 3 + 0],
         positions[i * 3 + 1],
         positions[i * 3 + 2],
         1
       );
-      const c = vec43.create();
-      vec43.transformMat4(c, p, mvp);
+      const c = vec42.create();
+      vec42.transformMat4(c, p, mvp);
       const invW = 1 / c[3];
       vInvW[i] = invW;
       if (!isFinite(invW)) {
@@ -600,8 +452,8 @@ var SoftwareRenderer = class {
     const { positions, normals, uvs, indices, model, colors } = mesh;
     const view = camera.view;
     const proj = camera.proj;
-    const mvp = mat44.create();
-    mat44.multiply(mvp, proj, mat44.multiply(mat44.create(), view, model));
+    const mvp = mat43.create();
+    mat43.multiply(mvp, proj, mat43.multiply(mat43.create(), view, model));
     const normalMat = mat3.create();
     mat3.normalFromMat4(normalMat, model);
     const vertexCount = positions.length / 3 | 0;
@@ -620,14 +472,14 @@ var SoftwareRenderer = class {
     const vWorldN = new Array(vertexCount);
     const vColor = new Array(vertexCount);
     for (let i = 0; i < vertexCount; i++) {
-      const p = vec43.fromValues(
+      const p = vec42.fromValues(
         positions[i * 3 + 0],
         positions[i * 3 + 1],
         positions[i * 3 + 2],
         1
       );
-      const c = vec43.create();
-      vec43.transformMat4(c, p, mvp);
+      const c = vec42.create();
+      vec42.transformMat4(c, p, mvp);
       const invW = 1 / c[3];
       const ndcX = c[0] * invW;
       const ndcY = c[1] * invW;
@@ -806,6 +658,333 @@ function edge(a, b, p) {
   return (p[0] - a[0]) * (b[1] - a[1]) - (p[1] - a[1]) * (b[0] - a[0]);
 }
 
+// lib/render/drawDebugPoints.ts
+var DEFAULT_MARKER_COLOR = [
+  255,
+  0,
+  170,
+  255
+];
+var DEFAULT_TEXT_COLOR = [
+  255,
+  24,
+  170,
+  255
+];
+var CHARACTER_WIDTH_RATIO = 0.62;
+function drawDebugPoints(renderer, camera, debugPoints, debugFontSize, debugPointColor, debugLabelColor) {
+  if (debugPoints.length === 0) return;
+  const viewProj = mat44.create();
+  mat44.multiply(viewProj, camera.proj, camera.view);
+  const markerColor = toColorRGBA(debugPointColor, DEFAULT_MARKER_COLOR);
+  const textColor = toColorRGBA(debugLabelColor, DEFAULT_TEXT_COLOR);
+  const labelScale = typeof debugFontSize === "number" && Number.isFinite(debugFontSize) ? Math.max(1, Math.round(debugFontSize)) : Math.max(
+    12,
+    Math.round(Math.min(renderer.width, renderer.height) * 0.028)
+  );
+  const textThickness = Math.max(
+    2,
+    Math.round(labelScale * textMetrics.strokeWidthRatio)
+  );
+  for (const debugPoint of debugPoints) {
+    const projected = projectWorldToScreen(
+      debugPoint.position,
+      viewProj,
+      renderer
+    );
+    if (!projected) continue;
+    drawMarker(renderer, projected, markerColor);
+    drawLabel(
+      renderer,
+      projected,
+      debugPoint.label,
+      textColor,
+      labelScale,
+      textThickness
+    );
+  }
+}
+function projectWorldToScreen(position, viewProj, renderer) {
+  const clip = vec43.fromValues(position.x, position.y, position.z, 1);
+  vec43.transformMat4(clip, clip, viewProj);
+  if (!Number.isFinite(clip[3]) || clip[3] <= 0) return null;
+  const invW = 1 / clip[3];
+  const ndcX = clip[0] * invW;
+  const ndcY = clip[1] * invW;
+  const ndcZ = clip[2] * invW;
+  if (!Number.isFinite(ndcX) || !Number.isFinite(ndcY) || !Number.isFinite(ndcZ) || ndcZ < -1 || ndcZ > 1) {
+    return null;
+  }
+  return {
+    x: (ndcX * 0.5 + 0.5) * (renderer.width - 1),
+    y: (1 - (ndcY * 0.5 + 0.5)) * (renderer.height - 1)
+  };
+}
+function drawMarker(renderer, projected, color) {
+  const centerX = Math.round(projected.x);
+  const centerY = Math.round(projected.y);
+  for (let offset = -5; offset <= 4; offset += 1) {
+    renderer.setPixel(
+      centerX + offset,
+      centerY,
+      color[0],
+      color[1],
+      color[2],
+      color[3]
+    );
+    renderer.setPixel(
+      centerX,
+      centerY + offset,
+      color[0],
+      color[1],
+      color[2],
+      color[3]
+    );
+  }
+}
+function drawLabel(renderer, projected, label, color, scale, textThickness) {
+  if (label.length === 0) return;
+  const scaleX = scale * CHARACTER_WIDTH_RATIO;
+  const labelWidth = measureLabelWidth(label, scaleX);
+  let x = projected.x + scale * 0.6;
+  let y = projected.y - scale * 1.1;
+  if (x + labelWidth > renderer.width - 2) {
+    x = projected.x - scale * 0.6 - labelWidth;
+  }
+  if (y < 2) {
+    y = projected.y + scale * 0.2;
+  }
+  drawStrokeText(renderer, label, x, y, scaleX, scale, color, textThickness);
+}
+function drawStrokeText(renderer, text, x, y, scaleX, scaleY, color, thickness) {
+  let cursorX = x;
+  for (const rawChar of text) {
+    const char = resolveGlyph(rawChar);
+    const glyph = glyphLineAlphabet[char];
+    const advanceRatio = glyphAdvanceRatio[char] ?? (char === " " ? textMetrics.spaceWidthRatio : textMetrics.glyphWidthRatio);
+    if (glyph) {
+      for (const segment of glyph) {
+        drawLine(
+          renderer,
+          cursorX + segment.x1 * scaleX,
+          y + (1 - segment.y1) * scaleY,
+          cursorX + segment.x2 * scaleX,
+          y + (1 - segment.y2) * scaleY,
+          color,
+          thickness
+        );
+      }
+    }
+    cursorX += advanceRatio * scaleX;
+  }
+}
+function resolveGlyph(char) {
+  if (glyphLineAlphabet[char]) return char;
+  const uppercase = char.toUpperCase();
+  if (glyphLineAlphabet[uppercase]) return uppercase;
+  return "?";
+}
+function measureLabelWidth(text, scaleX) {
+  let width = 0;
+  for (const rawChar of text) {
+    const char = resolveGlyph(rawChar);
+    width += glyphAdvanceRatio[char] ?? (char === " " ? textMetrics.spaceWidthRatio : textMetrics.glyphWidthRatio);
+  }
+  return width * scaleX;
+}
+function drawLine(renderer, x0, y0, x1, y1, color, thickness) {
+  const dx = x1 - x0;
+  const dy = y1 - y0;
+  const steps = Math.max(Math.abs(dx), Math.abs(dy));
+  if (steps === 0) {
+    drawBrush(renderer, x0, y0, color, thickness);
+    return;
+  }
+  for (let step = 0; step <= steps; step += 1) {
+    const t = step / steps;
+    drawBrush(renderer, x0 + dx * t, y0 + dy * t, color, thickness);
+  }
+}
+function drawBrush(renderer, x, y, color, thickness) {
+  const radius = Math.max(0, Math.floor((thickness - 1) / 2));
+  const centerX = Math.round(x);
+  const centerY = Math.round(y);
+  for (let offsetY = -radius; offsetY <= radius; offsetY += 1) {
+    for (let offsetX = -radius; offsetX <= radius; offsetX += 1) {
+      renderer.setPixel(
+        centerX + offsetX,
+        centerY + offsetY,
+        color[0],
+        color[1],
+        color[2],
+        color[3]
+      );
+    }
+  }
+}
+function toColorRGBA(color, fallback) {
+  if (!color) return fallback;
+  return [color[0], color[1], color[2], 255];
+}
+
+// lib/render/drawInfiniteGrid.ts
+import { mat4 as mat45, vec4 as vec44 } from "gl-matrix";
+function computeGridLineIntensity(params) {
+  const rx = params.world_x / params.cell_size;
+  const rz = params.world_z / params.cell_size;
+  const fract_x = rx - Math.floor(rx + 0.5);
+  const fract_z = rz - Math.floor(rz + 0.5);
+  const grid_x = Math.abs(fract_x);
+  const grid_z = Math.abs(fract_z);
+  const pixel_size_in_world = params.dist / Math.min(params.screen_width, params.screen_height);
+  const fwidth_x = pixel_size_in_world / params.cell_size;
+  const fwidth_z = pixel_size_in_world / params.cell_size;
+  const line_x = grid_x / (fwidth_x + 1e-4);
+  const line_z = grid_z / (fwidth_z + 1e-4);
+  const line = Math.min(line_x, line_z);
+  return 1 - Math.min(line * params.line_thickness_multiplier, 1);
+}
+function computeGridFadeAlpha(params) {
+  const fade_start = params.fade_distance;
+  const fade_end = params.fade_distance * params.fade_strength;
+  return 1 - Math.min(
+    1,
+    Math.max(0, (params.dist - fade_start) / (fade_end - fade_start))
+  );
+}
+function drawInfiniteGrid(software_renderer, params) {
+  const grid_y = params.grid_y ?? 0;
+  const cell_size = params.cell_size ?? 1;
+  const section_size = params.section_size ?? 10;
+  const fade_distance = params.fade_distance ?? 100;
+  const fade_strength = params.fade_strength ?? 1.5;
+  const grid_color = params.grid_color ?? [0.93, 0.93, 0.93];
+  const section_color = params.section_color ?? [0.8, 0.8, 1];
+  const gamma_out = params.gamma_out ?? true;
+  const camera = params.camera;
+  const view = camera.view;
+  const proj = camera.proj;
+  const inv_view = mat45.create();
+  mat45.invert(inv_view, view);
+  const cam_pos_x = inv_view[12];
+  const cam_pos_y = inv_view[13];
+  const cam_pos_z = inv_view[14];
+  const vp = mat45.create();
+  mat45.multiply(vp, proj, view);
+  const inv_vp = mat45.create();
+  mat45.invert(inv_vp, vp);
+  for (let y = 0; y < software_renderer.height; y++) {
+    for (let x = 0; x < software_renderer.width; x++) {
+      const ndc_x = x / (software_renderer.width - 1) * 2 - 1;
+      const ndc_y = 1 - y / (software_renderer.height - 1) * 2;
+      const near_point = vec44.fromValues(ndc_x, ndc_y, -1, 1);
+      const far_point = vec44.fromValues(ndc_x, ndc_y, 1, 1);
+      vec44.transformMat4(near_point, near_point, inv_vp);
+      vec44.transformMat4(far_point, far_point, inv_vp);
+      near_point[0] /= near_point[3];
+      near_point[1] /= near_point[3];
+      near_point[2] /= near_point[3];
+      far_point[0] /= far_point[3];
+      far_point[1] /= far_point[3];
+      far_point[2] /= far_point[3];
+      const ray_dir_x = far_point[0] - near_point[0];
+      const ray_dir_y = far_point[1] - near_point[1];
+      const ray_dir_z = far_point[2] - near_point[2];
+      if (Math.abs(ray_dir_y) < 1e-6) continue;
+      const t = (grid_y - near_point[1]) / ray_dir_y;
+      if (t < 0 || t > 1) continue;
+      const world_x = near_point[0] + t * ray_dir_x;
+      const world_z = near_point[2] + t * ray_dir_z;
+      const world_pt = vec44.fromValues(world_x, grid_y, world_z, 1);
+      const clip_pt = vec44.create();
+      vec44.transformMat4(clip_pt, world_pt, vp);
+      const ndc_z = clip_pt[2] / clip_pt[3];
+      const depth_01 = ndc_z * 0.5 + 0.5;
+      const di = y * software_renderer.width + x;
+      if (depth_01 >= software_renderer.depth[di]) continue;
+      const dx = world_x - cam_pos_x;
+      const dy = grid_y - cam_pos_y;
+      const dz = world_z - cam_pos_z;
+      const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+      const alpha = computeGridFadeAlpha({
+        dist,
+        fade_distance,
+        fade_strength
+      });
+      if (alpha <= 0) continue;
+      const g1 = computeGridLineIntensity({
+        world_x,
+        world_z,
+        cell_size,
+        dist,
+        screen_width: software_renderer.width,
+        screen_height: software_renderer.height,
+        line_thickness_multiplier: 0.8
+      });
+      const g2 = computeGridLineIntensity({
+        world_x,
+        world_z,
+        cell_size: section_size,
+        dist,
+        screen_width: software_renderer.width,
+        screen_height: software_renderer.height,
+        line_thickness_multiplier: 0.5
+        // Thicker section lines
+      });
+      const grid_strength = Math.max(g1, g2);
+      if (grid_strength <= 0) continue;
+      const final_r = grid_color[0] * (1 - g2) + section_color[0] * g2;
+      const final_g = grid_color[1] * (1 - g2) + section_color[1] * g2;
+      const final_b = grid_color[2] * (1 - g2) + section_color[2] * g2;
+      const final_alpha = grid_strength * alpha;
+      if (final_alpha <= 0.01) continue;
+      let out_r = final_r;
+      let out_g = final_g;
+      let out_b = final_b;
+      if (gamma_out) {
+        out_r = srgbEncodeLinear01(clamp(out_r, 0, 1));
+        out_g = srgbEncodeLinear01(clamp(out_g, 0, 1));
+        out_b = srgbEncodeLinear01(clamp(out_b, 0, 1));
+      } else {
+        out_r = clamp(out_r, 0, 1);
+        out_g = clamp(out_g, 0, 1);
+        out_b = clamp(out_b, 0, 1);
+      }
+      const dst_idx = (y * software_renderer.width + x) * 4;
+      const dst_r = (software_renderer.buffer[dst_idx + 0] ?? 0) / 255;
+      const dst_g = (software_renderer.buffer[dst_idx + 1] ?? 0) / 255;
+      const dst_b = (software_renderer.buffer[dst_idx + 2] ?? 0) / 255;
+      const dst_a = (software_renderer.buffer[dst_idx + 3] ?? 0) / 255;
+      const one_minus_a = 1 - final_alpha;
+      const blend_r = out_r * final_alpha + dst_r * one_minus_a;
+      const blend_g = out_g * final_alpha + dst_g * one_minus_a;
+      const blend_b = out_b * final_alpha + dst_b * one_minus_a;
+      const blend_a = final_alpha + dst_a * one_minus_a;
+      software_renderer.setPixel(
+        x,
+        y,
+        clamp(blend_r, 0, 1) * 255 | 0,
+        clamp(blend_g, 0, 1) * 255 | 0,
+        clamp(blend_b, 0, 1) * 255 | 0,
+        clamp(blend_a, 0, 1) * 255 | 0
+      );
+    }
+  }
+}
+
+// lib/render/resolveRenderOptions.ts
+function resolveRenderOptions(options = {}) {
+  const supersampling = typeof options.supersampling === "number" && Number.isFinite(options.supersampling) ? Math.max(1, Math.floor(options.supersampling)) : DEFAULT_RENDER_OPTIONS.supersampling;
+  return {
+    ...DEFAULT_RENDER_OPTIONS,
+    ...options,
+    supersampling,
+    lightDir: options.lightDir != null ? options.lightDir : DEFAULT_RENDER_OPTIONS.lightDir,
+    camPos: options.camPos !== void 0 ? options.camPos : DEFAULT_RENDER_OPTIONS.camPos,
+    lookAt: options.lookAt !== void 0 ? options.lookAt : DEFAULT_RENDER_OPTIONS.lookAt
+  };
+}
+
 // lib/render/renderDrawCalls.ts
 function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint8Bitmap) {
   const options = resolveRenderOptions(optionsInput);
@@ -915,6 +1094,16 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
     });
   }
   renderGroup(blendDraws);
+  if (options.debugPoints?.length) {
+    drawDebugPoints(
+      renderer,
+      camera,
+      options.debugPoints,
+      options.debugFontSize,
+      options.debugPointColor,
+      options.debugLabelColor
+    );
+  }
   const bitmap = options.supersampling > 1 ? downsampleBitmap(
     renderer.bitmap,
     options.width,
@@ -925,7 +1114,7 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
 }
 
 // lib/gltf/createInfiniteGrid.ts
-import { mat4 as mat45 } from "gl-matrix";
+import { mat4 as mat46 } from "gl-matrix";
 function createInfiniteGrid(options = {}) {
   const cellSize = options.cellSize ?? 1;
   const sectionSize = options.sectionSize ?? 10;
@@ -949,9 +1138,9 @@ function createInfiniteGrid(options = {}) {
     size
   ]);
   const indices = new Uint32Array([0, 1, 2, 0, 2, 3]);
-  const model = mat45.create();
+  const model = mat46.create();
   const offset = options.offset ?? {};
-  mat45.fromTranslation(model, [offset.x ?? 0, offset.y ?? 0, offset.z ?? 0]);
+  mat46.fromTranslation(model, [offset.x ?? 0, offset.y ?? 0, offset.z ?? 0]);
   return {
     positions,
     indices,
@@ -976,7 +1165,7 @@ function createInfiniteGrid(options = {}) {
 }
 
 // lib/gltf/createSceneFromGLTF.ts
-import { mat4 as mat46 } from "gl-matrix";
+import { mat4 as mat47 } from "gl-matrix";
 var COMPONENT_INFO = {
   5120: {
     name: "BYTE",
@@ -1174,17 +1363,17 @@ function readIndices(ctx, accessorIndex) {
 }
 function nodeLocalMatrix(node) {
   if (node.matrix) {
-    const m2 = mat46.create();
+    const m2 = mat47.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 = mat46.create();
-  const tmp = mat46.create();
-  mat46.fromRotationTranslationScale(tmp, rotation, translation, scale);
-  mat46.copy(m, tmp);
+  const m = mat47.create();
+  const tmp = mat47.create();
+  mat47.fromRotationTranslationScale(tmp, rotation, translation, scale);
+  mat47.copy(m, tmp);
   return m;
 }
 function getMaterial(gltf, textures, images, materialIndex) {
@@ -1222,8 +1411,8 @@ function createSceneFromGLTF(gltf, resources) {
     const node = nodes[nodeIndex];
     if (!node) return;
     const local = nodeLocalMatrix(node);
-    const world = mat46.create();
-    mat46.multiply(world, parentMatrix, local);
+    const world = mat47.create();
+    mat47.multiply(world, parentMatrix, local);
     if (Number.isInteger(node.mesh)) {
       const mesh = meshes[node.mesh];
       if (mesh) {
@@ -1261,7 +1450,7 @@ function createSceneFromGLTF(gltf, resources) {
       traverse(childIndex, world);
     }
   }
-  const identity = mat46.create();
+  const identity = mat47.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.18",
+  "version": "0.0.19",
   "repository": {
     "type": "git",
     "url": "https://github.com/tscircuit/poppygl.git"
@@ -20,6 +20,7 @@
   "type": "module",
   "devDependencies": {
     "@biomejs/biome": "^2.2.4",
+    "@tscircuit/alphabet": "^0.0.22",
     "@types/bun": "^1.2.23",
     "@types/readable-stream": "^4.0.21",
     "looks-same": "^10.0.1",