poppygl 0.0.19 → 0.0.21

package/README.md

@@ -53,6 +53,8 @@ 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.
+- `up`: choose the world-up axis for the camera with `"y+" | "y-" | "x+" | "x-" | "z+" | "z-"`.
+- `cameraRotation`: apply Euler degrees `{ x, y, z }` to define camera orientation directly. When set, it takes precedence over `lookAt`.
 - `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.

package/dist/index.d.ts

@@ -61,6 +61,12 @@ interface DebugPoint {
         z: number;
     };
 }
+type CameraUp = "y+" | "y-" | "x+" | "x-" | "z+" | "z-";
+interface CameraRotation {
+    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"
@@ -78,6 +84,8 @@ interface RenderOptions {
     lightDir: readonly [number, number, number];
     camPos?: readonly [number, number, number] | null;
     lookAt?: readonly [number, number, number] | null;
+    up: CameraUp;
+    cameraRotation: CameraRotation | null;
     backgroundColor?: readonly [number, number, number] | string | null;
     grid?: boolean | GridOptions;
     debugPoints?: DebugPoint[] | null;
@@ -93,7 +101,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): 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): Camera;
 
 interface RenderResult {
     bitmap: BitmapLike;
@@ -200,4 +208,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 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 };
+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 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

@@ -36,49 +36,173 @@ function computeWorldAABB(drawCalls) {
 var toRad = (degrees) => degrees * Math.PI / 180;
 
 // lib/camera/buildCamera.ts
-function buildCamera(drawCalls, width, height, fovDeg, camPos, lookAt) {
-  const aspect = width / height;
-  const near = 0.01;
-  const far = 1e3;
-  const proj = mat4.create();
-  mat4.perspective(proj, toRad(fovDeg), aspect, near, far);
-  let eye;
-  let center;
-  if (camPos) {
-    eye = vec3.fromValues(camPos[0], camPos[1], camPos[2]);
-    if (lookAt) {
-      center = vec3.fromValues(lookAt[0], lookAt[1], lookAt[2]);
-    } else {
-      const aabb = computeWorldAABB(drawCalls);
-      center = vec3.fromValues(
-        0.5 * (aabb.min[0] + aabb.max[0]),
-        0.5 * (aabb.min[1] + aabb.max[1]),
-        0.5 * (aabb.min[2] + aabb.max[2])
-      );
+function getWorldUpVector(up) {
+  switch (up) {
+    case "y-":
+      return vec3.fromValues(0, -1, 0);
+    case "x+":
+      return vec3.fromValues(1, 0, 0);
+    case "x-":
+      return vec3.fromValues(-1, 0, 0);
+    case "z+":
+      return vec3.fromValues(0, 0, 1);
+    case "z-":
+      return vec3.fromValues(0, 0, -1);
+    case "y+":
+    default:
+      return vec3.fromValues(0, 1, 0);
+  }
+}
+function buildCameraWorldMatrix(eye, forward, up) {
+  const normalizedForward = vec3.normalize(vec3.create(), forward);
+  const right = vec3.cross(vec3.create(), normalizedForward, up);
+  if (vec3.squaredLength(right) === 0) {
+    return null;
+  }
+  vec3.normalize(right, right);
+  const correctedUp = vec3.cross(vec3.create(), right, normalizedForward);
+  if (vec3.squaredLength(correctedUp) === 0) {
+    return null;
+  }
+  vec3.normalize(correctedUp, correctedUp);
+  return mat4.fromValues(
+    right[0],
+    right[1],
+    right[2],
+    0,
+    correctedUp[0],
+    correctedUp[1],
+    correctedUp[2],
+    0,
+    -normalizedForward[0],
+    -normalizedForward[1],
+    -normalizedForward[2],
+    0,
+    eye[0],
+    eye[1],
+    eye[2],
+    1
+  );
+}
+function getDefaultForwardForUp(up) {
+  const zForward = vec3.fromValues(0, 0, -1);
+  if (Math.abs(vec3.dot(up, zForward)) < 0.999) {
+    return zForward;
+  }
+  return vec3.fromValues(1, 0, 0);
+}
+function buildViewFromRotation(eye, up, rotation) {
+  const cameraWorld = buildCameraWorldMatrix(
+    eye,
+    getDefaultForwardForUp(up),
+    up
+  );
+  if (!cameraWorld) {
+    return mat4.create();
+  }
+  if (rotation.x !== 0) {
+    mat4.rotateX(cameraWorld, cameraWorld, toRad(rotation.x));
+  }
+  if (rotation.y !== 0) {
+    mat4.rotateY(cameraWorld, cameraWorld, toRad(rotation.y));
+  }
+  if (rotation.z !== 0) {
+    mat4.rotateZ(cameraWorld, cameraWorld, toRad(rotation.z));
+  }
+  const view = mat4.create();
+  mat4.invert(view, cameraWorld);
+  return view;
+}
+function buildViewFromLookAt(eye, center, up) {
+  const forward = vec3.subtract(vec3.create(), center, eye);
+  if (vec3.squaredLength(forward) === 0) {
+    return mat4.create();
+  }
+  const cameraWorld = buildCameraWorldMatrix(eye, forward, up);
+  if (!cameraWorld) {
+    return mat4.create();
+  }
+  const view = mat4.create();
+  mat4.invert(view, cameraWorld);
+  return view;
+}
+function getAutoDistance(drawCalls, fovDeg) {
+  const aabb = computeWorldAABB(drawCalls);
+  const diag = vec3.distance(
+    vec3.fromValues(aabb.min[0], aabb.min[1], aabb.min[2]),
+    vec3.fromValues(aabb.max[0], aabb.max[1], aabb.max[2])
+  );
+  const radius = diag * 0.5;
+  const fov = toRad(fovDeg);
+  return radius / Math.tan(fov * 0.5) + radius * 0.5;
+}
+function getAABBCornerDistances(aabb, eye) {
+  const xs = [aabb.min[0], aabb.max[0]];
+  const ys = [aabb.min[1], aabb.max[1]];
+  const zs = [aabb.min[2], aabb.max[2]];
+  let nearest = Infinity;
+  let farthest = 0;
+  for (const x of xs) {
+    for (const y of ys) {
+      for (const z of zs) {
+        const distance = vec3.distance(eye, vec3.fromValues(x, y, z));
+        nearest = Math.min(nearest, distance);
+        farthest = Math.max(farthest, distance);
+      }
     }
-  } else {
-    const aabb = computeWorldAABB(drawCalls);
-    center = vec3.fromValues(
-      0.5 * (aabb.min[0] + aabb.max[0]),
-      0.5 * (aabb.min[1] + aabb.max[1]),
-      0.5 * (aabb.min[2] + aabb.max[2])
-    );
-    const diag = vec3.distance(
-      vec3.fromValues(aabb.min[0], aabb.min[1], aabb.min[2]),
-      vec3.fromValues(aabb.max[0], aabb.max[1], aabb.max[2])
+  }
+  return { nearest, farthest };
+}
+function getCameraForwardFromView(view) {
+  const cameraWorld = mat4.create();
+  mat4.invert(cameraWorld, view);
+  return vec3.fromValues(-cameraWorld[8], -cameraWorld[9], -cameraWorld[10]);
+}
+function buildCamera(drawCalls, width, height, fovDeg, camPos, lookAt, up = "y+", cameraRotation = null) {
+  const aspect = width / height;
+  const worldUp = getWorldUpVector(up);
+  const aabb = computeWorldAABB(drawCalls);
+  const center = vec3.fromValues(
+    0.5 * (aabb.min[0] + aabb.max[0]),
+    0.5 * (aabb.min[1] + aabb.max[1]),
+    0.5 * (aabb.min[2] + aabb.max[2])
+  );
+  const autoDistance = getAutoDistance(drawCalls, fovDeg);
+  if (cameraRotation) {
+    const provisionalEye = camPos ? vec3.fromValues(camPos[0], camPos[1], camPos[2]) : vec3.clone(center);
+    const provisionalView = buildViewFromRotation(
+      provisionalEye,
+      worldUp,
+      cameraRotation
     );
-    const radius = diag * 0.5;
-    const fov = toRad(fovDeg);
-    const dist = radius / Math.tan(fov * 0.5) + radius * 0.5;
-    eye = vec3.fromValues(
-      center[0] + dist,
-      center[1] + dist * 0.3,
-      center[2] + dist
+    const eye2 = camPos ? provisionalEye : vec3.scaleAndAdd(
+      vec3.create(),
+      center,
+      getCameraForwardFromView(provisionalView),
+      -autoDistance
     );
+    const { nearest: nearest2, farthest: farthest2 } = getAABBCornerDistances(aabb, eye2);
+    const near2 = Math.max(0.01, nearest2 * 0.5);
+    const far2 = Math.max(1e3, farthest2 * 1.1);
+    const proj2 = mat4.create();
+    mat4.perspective(proj2, toRad(fovDeg), aspect, near2, far2);
+    return {
+      view: buildViewFromRotation(eye2, worldUp, cameraRotation),
+      proj: proj2
+    };
   }
-  const up = vec3.fromValues(0, 1, 0);
-  const view = mat4.create();
-  mat4.lookAt(view, eye, center, up);
+  const eye = camPos ? vec3.fromValues(camPos[0], camPos[1], camPos[2]) : vec3.fromValues(
+    center[0] + autoDistance,
+    center[1] + autoDistance * 0.3,
+    center[2] + autoDistance
+  );
+  const target = lookAt ? vec3.fromValues(lookAt[0], lookAt[1], lookAt[2]) : center;
+  const { nearest, farthest } = getAABBCornerDistances(aabb, eye);
+  const near = Math.max(0.01, nearest * 0.5);
+  const far = Math.max(1e3, farthest * 1.1);
+  const proj = mat4.create();
+  mat4.perspective(proj, toRad(fovDeg), aspect, near, far);
+  const view = buildViewFromLookAt(eye, target, worldUp);
   return { view, proj };
 }
 
@@ -274,6 +398,8 @@ var DEFAULT_RENDER_OPTIONS = {
   lightDir: DEFAULT_LIGHT_DIR,
   camPos: null,
   lookAt: null,
+  up: "y+",
+  cameraRotation: null,
   backgroundColor: null,
   grid: false,
   debugPoints: null,
@@ -484,8 +610,8 @@ var SoftwareRenderer = class {
       const ndcX = c[0] * invW;
       const ndcY = c[1] * invW;
       const ndcZ = c[2] * invW;
-      const sx = Math.round((ndcX * 0.5 + 0.5) * (this.width - 1));
-      const sy = Math.round((1 - (ndcY * 0.5 + 0.5)) * (this.height - 1));
+      const sx = (ndcX * 0.5 + 0.5) * (this.width - 1);
+      const sy = (1 - (ndcY * 0.5 + 0.5)) * (this.height - 1);
       vScreen[i] = [sx, sy];
       vInvW[i] = invW;
       vNDCz[i] = ndcZ;
@@ -515,10 +641,16 @@ var SoftwareRenderer = class {
       const area = edge(v0, v1, v2);
       if (area === 0) continue;
       if (cullBackFaces && area < 0) continue;
-      let minX = Math.max(0, Math.min(v0[0], v1[0], v2[0]) | 0);
-      let maxX = Math.min(this.width - 1, Math.max(v0[0], v1[0], v2[0]) | 0);
-      let minY = Math.max(0, Math.min(v0[1], v1[1], v2[1]) | 0);
-      let maxY = Math.min(this.height - 1, Math.max(v0[1], v1[1], v2[1]) | 0);
+      const minX = Math.max(0, Math.floor(Math.min(v0[0], v1[0], v2[0])));
+      const maxX = Math.min(
+        this.width - 1,
+        Math.ceil(Math.max(v0[0], v1[0], v2[0]))
+      );
+      const minY = Math.max(0, Math.floor(Math.min(v0[1], v1[1], v2[1])));
+      const maxY = Math.min(
+        this.height - 1,
+        Math.ceil(Math.max(v0[1], v1[1], v2[1]))
+      );
       const invW = [
         vInvW[i0],
         vInvW[i1],
@@ -557,6 +689,7 @@ var SoftwareRenderer = class {
           const l2 = w2 * invArea;
           const zndc = l0 * ndcZ[0] + l1 * ndcZ[1] + l2 * ndcZ[2];
           const z01 = zndc * 0.5 + 0.5;
+          if (z01 < 0 || z01 > 1) continue;
           const di = y * this.width + x;
           const depth = this.depth;
           if (z01 >= depth[di]) continue;
@@ -973,6 +1106,21 @@ function drawInfiniteGrid(software_renderer, params) {
 }
 
 // lib/render/resolveRenderOptions.ts
+var CAMERA_UP_VALUES = /* @__PURE__ */ new Set(["y+", "y-", "x+", "x-", "z+", "z-"]);
+function resolveCameraUp(up) {
+  return up != null && CAMERA_UP_VALUES.has(up) ? up : DEFAULT_RENDER_OPTIONS.up;
+}
+function resolveCameraRotation(cameraRotation) {
+  if (cameraRotation == null) {
+    return DEFAULT_RENDER_OPTIONS.cameraRotation;
+  }
+  const resolveAxis = (value) => typeof value === "number" && Number.isFinite(value) ? value : 0;
+  return {
+    x: resolveAxis(cameraRotation.x),
+    y: resolveAxis(cameraRotation.y),
+    z: resolveAxis(cameraRotation.z)
+  };
+}
 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 {
@@ -981,7 +1129,9 @@ function resolveRenderOptions(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
+    lookAt: options.lookAt !== void 0 ? options.lookAt : DEFAULT_RENDER_OPTIONS.lookAt,
+    up: resolveCameraUp(options.up),
+    cameraRotation: resolveCameraRotation(options.cameraRotation)
   };
 }
 
@@ -996,7 +1146,9 @@ function renderDrawCalls(drawCalls, optionsInput = {}, imageFactory = createUint
     renderHeight,
     options.fov,
     options.camPos ?? null,
-    options.lookAt ?? null
+    options.lookAt ?? null,
+    options.up,
+    options.cameraRotation ?? null
   );
   const renderer = new SoftwareRenderer(renderWidth, renderHeight, imageFactory);
   let rgb = null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poppygl",
   "main": "dist/index.js",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "repository": {
     "type": "git",
     "url": "https://github.com/tscircuit/poppygl.git"
@@ -15,12 +15,14 @@
     "build": "tsup-node ./lib/index.ts --format esm --dts",
     "format": "biome format --write .",
     "format:check": "biome format .",
-    "test": "bun test"
+    "test": "bun test",
+    "test:playwright": "playwright test"
   },
   "type": "module",
   "devDependencies": {
     "@biomejs/biome": "^2.2.4",
-    "@tscircuit/alphabet": "^0.0.22",
+    "@playwright/test": "^1.60.0",
+    "@tscircuit/alphabet": "0.0.23",
     "@types/bun": "^1.2.23",
     "@types/readable-stream": "^4.0.21",
     "looks-same": "^10.0.1",