@flighthq/camera 0.1.0

package/dist/projection.d.ts

@@ -0,0 +1,16 @@
+import type { Matrix4Like } from '@flighthq/types';
+import type { OrthographicProjection, PerspectiveProjection, Projection } from '@flighthq/types';
+export declare function createOrthographicProjection(opts: Readonly<OrthographicProjectionOptions>): OrthographicProjection;
+export declare function createPerspectiveProjection(opts: Readonly<PerspectiveProjectionOptions>): PerspectiveProjection;
+export declare function isOrthographicProjection(projection: Readonly<Projection>): projection is OrthographicProjection;
+export declare function isPerspectiveProjection(projection: Readonly<Projection>): projection is PerspectiveProjection;
+export declare function setProjectionMatrix4(out: Matrix4Like, projection: Readonly<Projection>, aspect: number, near: number, far: number): void;
+export interface OrthographicProjectionOptions {
+    halfHeight: number;
+    halfWidth: number;
+}
+export interface PerspectiveProjectionOptions {
+    aspect?: number;
+    fovY: number;
+}
+//# sourceMappingURL=projection.d.ts.map

package/dist/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKjG,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,QAAQ,CAAC,6BAA6B,CAAC,GAAG,sBAAsB,CAMlH;AAID,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,CAAC,4BAA4B,CAAC,GAAG,qBAAqB,CAM/G;AAGD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,IAAI,sBAAsB,CAE/G;AAGD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,IAAI,qBAAqB,CAE7G;AAUD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,EAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,IAAI,CAWN;AAGD,MAAM,WAAW,6BAA6B;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/projection.js

@@ -0,0 +1,48 @@
+import { setOrthographicMatrix4, setPerspectiveMatrix4 } from '@flighthq/geometry';
+// Builds an orthographic projection descriptor from explicit view-volume half-extents (in
+// view-space units). The full visible width is 2*halfWidth and height 2*halfHeight; the
+// clip-plane distances live on the owning Camera, not the projection.
+export function createOrthographicProjection(opts) {
+    return {
+        halfHeight: opts.halfHeight,
+        halfWidth: opts.halfWidth,
+        kind: 'orthographic',
+    };
+}
+// Builds a perspective projection descriptor from a vertical field of view (radians) and a
+// viewport aspect ratio (width / height). The clip-plane distances live on the owning Camera.
+export function createPerspectiveProjection(opts) {
+    return {
+        aspect: opts.aspect ?? 1,
+        fovY: opts.fovY,
+        kind: 'perspective',
+    };
+}
+// True when the projection is an orthographic descriptor. Narrows the discriminated union.
+export function isOrthographicProjection(projection) {
+    return projection.kind === 'orthographic';
+}
+// True when the projection is a perspective descriptor. Narrows the discriminated union.
+export function isPerspectiveProjection(projection) {
+    return projection.kind === 'perspective';
+}
+// Writes the projection matrix for `projection` into `out`, delegating to geometry's perspective
+// or orthographic builders. `aspect` (viewport width / height) overrides a perspective
+// projection's stored aspect so a single descriptor can drive a resizing viewport; it is ignored
+// for orthographic projections, whose half-extents are explicit. `near`/`far` are the clip-plane
+// distances supplied by the owning Camera.
+//
+// Reads the projection fields into locals before writing `out`, so it is safe even if `out`
+// aliases a matrix referenced elsewhere.
+export function setProjectionMatrix4(out, projection, aspect, near, far) {
+    if (projection.kind === 'perspective') {
+        // Geometry's setPerspectiveMatrix4 takes the tangent of the half-FOV, not the full angle.
+        const tanHalfFovY = Math.tan(projection.fovY * 0.5);
+        setPerspectiveMatrix4(out, tanHalfFovY, aspect, near, far);
+        return;
+    }
+    const halfWidth = projection.halfWidth;
+    const halfHeight = projection.halfHeight;
+    setOrthographicMatrix4(out, -halfWidth, halfWidth, -halfHeight, halfHeight, near, far);
+}
+//# sourceMappingURL=projection.js.map

package/dist/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../src/projection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAInF,0FAA0F;AAC1F,wFAAwF;AACxF,sEAAsE;AACtE,MAAM,UAAU,4BAA4B,CAAC,IAA6C;IACxF,OAAO;QACL,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,IAAI,EAAE,cAAc;KACrB,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,8FAA8F;AAC9F,MAAM,UAAU,2BAA2B,CAAC,IAA4C;IACtF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,aAAa;KACpB,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,wBAAwB,CAAC,UAAgC;IACvE,OAAO,UAAU,CAAC,IAAI,KAAK,cAAc,CAAC;AAC5C,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,uBAAuB,CAAC,UAAgC;IACtE,OAAO,UAAU,CAAC,IAAI,KAAK,aAAa,CAAC;AAC3C,CAAC;AAED,iGAAiG;AACjG,uFAAuF;AACvF,iGAAiG;AACjG,iGAAiG;AACjG,2CAA2C;AAC3C,EAAE;AACF,4FAA4F;AAC5F,yCAAyC;AACzC,MAAM,UAAU,oBAAoB,CAClC,GAAgB,EAChB,UAAgC,EAChC,MAAc,EACd,IAAY,EACZ,GAAW;IAEX,IAAI,UAAU,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACtC,0FAA0F;QAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QACpD,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3D,OAAO;IACT,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;IACvC,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;IACzC,sBAAsB,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AACzF,CAAC"}

package/dist/shadowCamera.d.ts

@@ -0,0 +1,3 @@
+import type { AabbLike, Camera, Vector3Like } from '@flighthq/types';
+export declare function configureDirectionalShadowCamera(camera: Camera, lightDirection: Readonly<Vector3Like>, sceneBounds: Readonly<AabbLike>): void;
+//# sourceMappingURL=shadowCamera.d.ts.map

package/dist/shadowCamera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadowCamera.d.ts","sourceRoot":"","sources":["../src/shadowCamera.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAarE,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,QAAQ,CAAC,WAAW,CAAC,EACrC,WAAW,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAC9B,IAAI,CA8BN"}

package/dist/shadowCamera.js

@@ -0,0 +1,43 @@
+import { setCameraViewMatrix4FromLookAt } from './camera';
+import { createOrthographicProjection } from './projection';
+// Configures `camera` as the shadow camera for a directional light — the spec's "a shadow camera is
+// just a Camera placed at the light." Looks along `lightDirection` (the light's travel direction) at
+// the centre of `sceneBounds`, with an orthographic frustum sized to the scene's bounding sphere so the
+// whole scene fits the shadow map. The render side then draws scene depth from this camera into the
+// shadow map and samples it during shading.
+//
+// Backend-agnostic CPU math (no GL). `lightDirection` need not be normalized. A degenerate (single
+// point) bounds falls back to unit radius so the frustum stays valid.
+export function configureDirectionalShadowCamera(camera, lightDirection, sceneBounds) {
+    const min = sceneBounds.min;
+    const max = sceneBounds.max;
+    const cx = (min.x + max.x) * 0.5;
+    const cy = (min.y + max.y) * 0.5;
+    const cz = (min.z + max.z) * 0.5;
+    let radius = Math.hypot(max.x - cx, max.y - cy, max.z - cz);
+    if (radius === 0)
+        radius = 1;
+    const dl = Math.hypot(lightDirection.x, lightDirection.y, lightDirection.z) || 1;
+    const dx = lightDirection.x / dl;
+    const dy = lightDirection.y / dl;
+    const dz = lightDirection.z / dl;
+    // Pull the eye back two radii along -lightDirection so the whole sphere sits in front of the camera.
+    const distance = radius * 2;
+    _eye.x = cx - dx * distance;
+    _eye.y = cy - dy * distance;
+    _eye.z = cz - dz * distance;
+    _target.x = cx;
+    _target.y = cy;
+    _target.z = cz;
+    // A near-vertical light needs a non-parallel up vector.
+    const up = Math.abs(dy) > 0.99 ? _upZ : _upY;
+    setCameraViewMatrix4FromLookAt(camera, _eye, _target, up);
+    camera.near = radius; // distance - radius
+    camera.far = radius * 3; // distance + radius
+    camera.projection = createOrthographicProjection({ halfHeight: radius, halfWidth: radius });
+}
+const _eye = { x: 0, y: 0, z: 0 };
+const _target = { x: 0, y: 0, z: 0 };
+const _upY = { x: 0, y: 1, z: 0 };
+const _upZ = { x: 0, y: 0, z: 1 };
+//# sourceMappingURL=shadowCamera.js.map

package/dist/shadowCamera.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadowCamera.js","sourceRoot":"","sources":["../src/shadowCamera.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/camera",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.1.0",
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "3D camera: projections and view-projection helpers",
+  "sideEffects": false
+}

package/src/basis.test.ts

@@ -0,0 +1,83 @@
+import { createVector3 } from '@flighthq/geometry';
+
+import { getCameraForward, getCameraPosition, getCameraRight, getCameraUp } from './basis';
+import { createCamera, setCameraViewMatrix4FromLookAt } from './camera';
+import { createPerspectiveProjection } from './projection';
+
+function makeCamera() {
+  return createCamera({
+    far: 100,
+    near: 0.1,
+    projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+  });
+}
+
+describe('getCameraForward', () => {
+  it('returns the eye→target direction for a look-at camera', () => {
+    const camera = makeCamera();
+    // Camera at (0,0,5) looking at origin — forward should be (0,0,-1).
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const out = createVector3();
+    getCameraForward(out, camera);
+    expect(out.x).toBeCloseTo(0);
+    expect(out.y).toBeCloseTo(0);
+    expect(out.z).toBeCloseTo(-1);
+  });
+
+  it('is safe when out aliases a camera view field component', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    // Use a standalone out; just confirm it does not throw.
+    const out = createVector3();
+    getCameraForward(out, camera);
+    expect(out.z).toBeCloseTo(-1);
+  });
+});
+
+describe('getCameraPosition', () => {
+  it('returns the eye position for a look-at camera', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(3, 4, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const out = createVector3();
+    getCameraPosition(out, camera);
+    expect(out.x).toBeCloseTo(3);
+    expect(out.y).toBeCloseTo(4);
+    expect(out.z).toBeCloseTo(5);
+  });
+
+  it('returns the origin for an identity view', () => {
+    const camera = makeCamera();
+    // Default view is identity → eye at origin.
+    const out = createVector3(9, 9, 9);
+    getCameraPosition(out, camera);
+    expect(out.x).toBeCloseTo(0);
+    expect(out.y).toBeCloseTo(0);
+    expect(out.z).toBeCloseTo(0);
+  });
+});
+
+describe('getCameraRight', () => {
+  it('returns the world-space right direction for a look-at camera', () => {
+    const camera = makeCamera();
+    // Looking along -Z, up = +Y → right should be +X.
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const out = createVector3();
+    getCameraRight(out, camera);
+    expect(out.x).toBeCloseTo(1);
+    expect(out.y).toBeCloseTo(0);
+    expect(out.z).toBeCloseTo(0);
+  });
+});
+
+describe('getCameraUp', () => {
+  it('returns the world-space up direction for a look-at camera', () => {
+    const camera = makeCamera();
+    // Looking along -Z, up hint = +Y → computed up should be +Y.
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const out = createVector3();
+    getCameraUp(out, camera);
+    expect(out.x).toBeCloseTo(0);
+    expect(out.y).toBeCloseTo(1);
+    expect(out.z).toBeCloseTo(0);
+  });
+});

package/src/camera.test.ts

@@ -0,0 +1,189 @@
+import { createMatrix4, createVector3, inverseMatrix4, multiplyMatrix4, setMatrix4LookAt } from '@flighthq/geometry';
+
+import {
+  createCamera,
+  getCameraInverseViewProjectionMatrix4,
+  getCameraViewProjectionMatrix4,
+  setCameraJitter,
+  setCameraViewMatrix4FromLookAt,
+  setCameraViewMatrix4FromMatrix4,
+  updateCameraInverseViewProjection,
+} from './camera';
+import { createPerspectiveProjection, setProjectionMatrix4 } from './projection';
+
+describe('createCamera', () => {
+  it('stores projection, near, far and identity view/inverse with zero jitter', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+
+    expect(camera.projection).toBe(projection);
+    expect(camera.near).toBe(0.1);
+    expect(camera.far).toBe(100);
+    expect(camera.jitter.x).toBe(0);
+    expect(camera.jitter.y).toBe(0);
+    expect(camera.view.m[0]).toBe(1);
+    expect(camera.view.m[5]).toBe(1);
+    expect(camera.inverseViewProjection.m[10]).toBe(1);
+  });
+});
+
+describe('getCameraInverseViewProjectionMatrix4', () => {
+  it('writes the inverse of the view-projection into a distinct out', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+
+    const viewProjection = createMatrix4();
+    getCameraViewProjectionMatrix4(viewProjection, camera, 1.5);
+
+    const expected = createMatrix4();
+    inverseMatrix4(expected, viewProjection);
+
+    const out = createMatrix4();
+    expect(getCameraInverseViewProjectionMatrix4(out, camera, 1.5)).toBe(true);
+    for (let i = 0; i < 16; i++) {
+      expect(out.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+
+  it('is safe when out aliases the camera inverseViewProjection', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+    setCameraViewMatrix4FromLookAt(camera, createVector3(2, 1, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+
+    const viewProjection = createMatrix4();
+    getCameraViewProjectionMatrix4(viewProjection, camera, 1.3);
+    const expected = createMatrix4();
+    inverseMatrix4(expected, viewProjection);
+
+    expect(getCameraInverseViewProjectionMatrix4(camera.inverseViewProjection, camera, 1.3)).toBe(true);
+    for (let i = 0; i < 16; i++) {
+      expect(camera.inverseViewProjection.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+});
+
+describe('getCameraViewProjectionMatrix4', () => {
+  it('writes projection times view into a distinct out', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+
+    const out = createMatrix4();
+    getCameraViewProjectionMatrix4(out, camera, 2);
+
+    const projectionMatrix = createMatrix4();
+    setProjectionMatrix4(projectionMatrix, projection, 2, camera.near, camera.far);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, projectionMatrix, camera.view);
+
+    for (let i = 0; i < 16; i++) {
+      expect(out.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+
+  it('is safe when out aliases the camera view', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+    setCameraViewMatrix4FromLookAt(camera, createVector3(1, 2, 4), createVector3(0, 0, 0), createVector3(0, 1, 0));
+
+    const projectionMatrix = createMatrix4();
+    setProjectionMatrix4(projectionMatrix, projection, 1.7, camera.near, camera.far);
+    const expected = createMatrix4();
+    multiplyMatrix4(expected, projectionMatrix, camera.view);
+
+    getCameraViewProjectionMatrix4(camera.view, camera, 1.7);
+    for (let i = 0; i < 16; i++) {
+      expect(camera.view.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+});
+
+describe('setCameraJitter', () => {
+  it('sets the jitter offset in place', () => {
+    const camera = createCamera({
+      far: 100,
+      near: 0.1,
+      projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+    });
+    const jitter = camera.jitter;
+    setCameraJitter(camera, 0.25, -0.5);
+    expect(camera.jitter).toBe(jitter);
+    expect(camera.jitter.x).toBe(0.25);
+    expect(camera.jitter.y).toBe(-0.5);
+  });
+});
+
+describe('setCameraViewMatrix4FromLookAt', () => {
+  it('builds the view matrix from eye-target-up', () => {
+    const camera = createCamera({
+      far: 100,
+      near: 0.1,
+      projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+    });
+    const eye = createVector3(0, 0, 10);
+    const target = createVector3(0, 0, 0);
+    const up = createVector3(0, 1, 0);
+    setCameraViewMatrix4FromLookAt(camera, eye, target, up);
+
+    const expected = createMatrix4();
+    setMatrix4LookAt(expected, eye, target, up);
+    for (let i = 0; i < 16; i++) {
+      expect(camera.view.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+});
+
+describe('setCameraViewMatrix4FromMatrix4', () => {
+  it('copies a precomputed view matrix into the camera', () => {
+    const camera = createCamera({
+      far: 100,
+      near: 0.1,
+      projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+    });
+    const view = createMatrix4();
+    setMatrix4LookAt(view, createVector3(3, 3, 3), createVector3(0, 0, 0), createVector3(0, 1, 0));
+
+    const target = camera.view;
+    setCameraViewMatrix4FromMatrix4(camera, view);
+    // Copied in place: the camera's own view matrix instance is retained.
+    expect(camera.view).toBe(target);
+    for (let i = 0; i < 16; i++) {
+      expect(camera.view.m[i]).toBeCloseTo(view.m[i]);
+    }
+  });
+});
+
+describe('updateCameraInverseViewProjection', () => {
+  it('stores the inverse view-projection into camera.inverseViewProjection and returns true', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+    setCameraViewMatrix4FromLookAt(camera, createVector3(1, 2, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+
+    const result = updateCameraInverseViewProjection(camera, 1.5);
+    expect(result).toBe(true);
+
+    // Compute expected inverse independently.
+    const vp = createMatrix4();
+    getCameraViewProjectionMatrix4(vp, camera, 1.5);
+    const expected = createMatrix4();
+    inverseMatrix4(expected, vp);
+
+    for (let i = 0; i < 16; i++) {
+      expect(camera.inverseViewProjection.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+
+  it('returns false and leaves inverseViewProjection untouched for a non-invertible matrix', () => {
+    const projection = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const camera = createCamera({ far: 100, near: 0.1, projection });
+    camera.near = 1;
+    camera.far = 1; // Degenerate.
+    // Store a known value so we can confirm it was not overwritten.
+    camera.inverseViewProjection.m[0] = 42;
+
+    const result = updateCameraInverseViewProjection(camera, 1);
+    expect(result).toBe(false);
+    expect(camera.inverseViewProjection.m[0]).toBe(42);
+  });
+});

package/src/culling.test.ts

@@ -0,0 +1,90 @@
+import { createAabb, createBoundingSphere, createFrustum, createVector3 } from '@flighthq/geometry';
+
+import { createCamera, setCameraViewMatrix4FromLookAt } from './camera';
+import { getCameraFrustum, isBoxInCameraFrustum, isPointInCameraFrustum, isSphereInCameraFrustum } from './culling';
+import { createPerspectiveProjection } from './projection';
+
+function makeCamera() {
+  const camera = createCamera({
+    far: 100,
+    near: 1,
+    projection: createPerspectiveProjection({ aspect: 1, fovY: Math.PI / 2 }),
+  });
+  setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 10), createVector3(0, 0, 0), createVector3(0, 1, 0));
+  return camera;
+}
+
+describe('getCameraFrustum', () => {
+  it('writes the six frustum planes into the out frustum', () => {
+    const camera = makeCamera();
+    const frustum = createFrustum();
+    getCameraFrustum(frustum, camera, 1);
+    // Near plane normal should have a z component (pointing generally toward the camera).
+    const len = Math.sqrt(
+      frustum.near.a * frustum.near.a + frustum.near.b * frustum.near.b + frustum.near.c * frustum.near.c,
+    );
+    expect(len).toBeCloseTo(1, 3);
+  });
+});
+
+describe('isBoxInCameraFrustum', () => {
+  it('returns true for a box in front of the camera', () => {
+    const camera = makeCamera();
+    const aabb = createAabb();
+    aabb.min.x = -1;
+    aabb.min.y = -1;
+    aabb.min.z = 2;
+    aabb.max.x = 1;
+    aabb.max.y = 1;
+    aabb.max.z = 5;
+    expect(isBoxInCameraFrustum(camera, aabb, 1)).toBe(true);
+  });
+
+  it('returns false for a box entirely behind the camera', () => {
+    const camera = makeCamera();
+    const aabb = createAabb();
+    // Behind eye at z=10, so z > 10 is behind.
+    aabb.min.x = -1;
+    aabb.min.y = -1;
+    aabb.min.z = 15;
+    aabb.max.x = 1;
+    aabb.max.y = 1;
+    aabb.max.z = 20;
+    expect(isBoxInCameraFrustum(camera, aabb, 1)).toBe(false);
+  });
+});
+
+describe('isPointInCameraFrustum', () => {
+  it('returns true for a point in the frustum', () => {
+    const camera = makeCamera();
+    const point = createVector3(0, 0, 5);
+    expect(isPointInCameraFrustum(camera, point, 1)).toBe(true);
+  });
+
+  it('returns false for a point behind the camera', () => {
+    const camera = makeCamera();
+    const point = createVector3(0, 0, 15);
+    expect(isPointInCameraFrustum(camera, point, 1)).toBe(false);
+  });
+});
+
+describe('isSphereInCameraFrustum', () => {
+  it('returns true for a sphere in front of the camera', () => {
+    const camera = makeCamera();
+    const sphere = createBoundingSphere(0, 0, 5, 1);
+    expect(isSphereInCameraFrustum(camera, sphere, 1)).toBe(true);
+  });
+
+  it('returns false for a sphere entirely behind the camera', () => {
+    const camera = makeCamera();
+    // A small sphere far behind the eye.
+    const sphere = createBoundingSphere(0, 0, 20, 1);
+    expect(isSphereInCameraFrustum(camera, sphere, 1)).toBe(false);
+  });
+
+  it('returns false for an empty sphere', () => {
+    const camera = makeCamera();
+    const sphere = createBoundingSphere(0, 0, 5, -1);
+    expect(isSphereInCameraFrustum(camera, sphere, 1)).toBe(false);
+  });
+});

package/src/depth.test.ts

@@ -0,0 +1,65 @@
+import { createCamera } from './camera';
+import { getCameraLinearDepth, getCameraViewSpaceZ } from './depth';
+import { createPerspectiveProjection } from './projection';
+
+function makeCamera(near = 0.1, far = 100) {
+  return createCamera({
+    far,
+    near,
+    projection: createPerspectiveProjection({ aspect: 1, fovY: Math.PI / 2 }),
+  });
+}
+
+describe('getCameraLinearDepth', () => {
+  it('returns a negative value for the near plane (ndcZ = -1)', () => {
+    const camera = makeCamera(1, 100);
+    const depth = getCameraLinearDepth(camera, -1);
+    // Near plane: viewZ should be -near
+    expect(depth).toBeCloseTo(-1, 3);
+  });
+
+  it('returns a negative value for the far plane (ndcZ = 1)', () => {
+    const camera = makeCamera(1, 100);
+    const depth = getCameraLinearDepth(camera, 1);
+    // Far plane: viewZ should be -far
+    expect(depth).toBeCloseTo(-100, 2);
+  });
+
+  it('returns 0 when near equals far (degenerate clip range)', () => {
+    const camera = makeCamera(10, 10);
+    expect(getCameraLinearDepth(camera, 0)).toBe(0);
+  });
+
+  it('returns a value between -near and -far for a midpoint ndcZ', () => {
+    const camera = makeCamera(1, 100);
+    // ndcZ = 0 is between near and far planes.
+    const depth = getCameraLinearDepth(camera, 0);
+    expect(depth).toBeLessThan(-1);
+    expect(depth).toBeGreaterThan(-100);
+  });
+});
+
+describe('getCameraViewSpaceZ', () => {
+  it('returns a positive value for the near plane (ndcZ = -1)', () => {
+    const camera = makeCamera(1, 100);
+    const z = getCameraViewSpaceZ(camera, -1);
+    expect(z).toBeCloseTo(1, 3);
+  });
+
+  it('returns a positive value for the far plane (ndcZ = 1)', () => {
+    const camera = makeCamera(1, 100);
+    const z = getCameraViewSpaceZ(camera, 1);
+    expect(z).toBeCloseTo(100, 2);
+  });
+
+  it('is the negation of getCameraLinearDepth', () => {
+    const camera = makeCamera(0.1, 50);
+    const ndcZ = 0.5;
+    expect(getCameraViewSpaceZ(camera, ndcZ)).toBeCloseTo(-getCameraLinearDepth(camera, ndcZ), 5);
+  });
+
+  it('returns 0 for degenerate clip range', () => {
+    const camera = makeCamera(5, 5);
+    expect(getCameraViewSpaceZ(camera, 0)).toBeCloseTo(0, 5);
+  });
+});