@flighthq/camera 0.1.0

package/src/frustumCorners.test.ts

@@ -0,0 +1,75 @@
+import { createVector3 } from '@flighthq/geometry';
+import type { Vector3Like } from '@flighthq/types';
+
+import { createCamera, setCameraViewMatrix4FromLookAt } from './camera';
+import { getCameraFrustumCorners } from './frustumCorners';
+import { createPerspectiveProjection } from './projection';
+
+type FrustumCorners = [
+  Vector3Like,
+  Vector3Like,
+  Vector3Like,
+  Vector3Like,
+  Vector3Like,
+  Vector3Like,
+  Vector3Like,
+  Vector3Like,
+];
+
+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;
+}
+
+function makeCorners(): FrustumCorners {
+  return [
+    createVector3(),
+    createVector3(),
+    createVector3(),
+    createVector3(),
+    createVector3(),
+    createVector3(),
+    createVector3(),
+    createVector3(),
+  ];
+}
+
+describe('getCameraFrustumCorners', () => {
+  it('writes 8 world-space corners and returns true', () => {
+    const camera = makeCamera();
+    const corners = makeCorners();
+    const result = getCameraFrustumCorners(corners, camera, 1);
+    expect(result).toBe(true);
+    // Near corners (index 0-3) should be closer to camera than far corners (4-7).
+    // Camera is at z=10 looking toward z=0, so smaller z values are farther away.
+    for (let i = 0; i < 4; i++) {
+      expect(corners[i].z).toBeGreaterThan(corners[i + 4].z);
+    }
+  });
+
+  it('returns false when the view-projection is non-invertible', () => {
+    const camera = makeCamera();
+    camera.near = 1;
+    camera.far = 1; // Degenerate: near == far.
+    const corners = makeCorners();
+    const result = getCameraFrustumCorners(corners, camera, 1);
+    expect(result).toBe(false);
+  });
+
+  it('near corners and far corners have opposite symmetry in xy', () => {
+    const camera = makeCamera();
+    const corners = makeCorners();
+    getCameraFrustumCorners(corners, camera, 1);
+    // Near corners: 0 (-1,-1,-1), 1 (1,-1,-1), 2 (-1,1,-1), 3 (1,1,-1)
+    // With aspect=1 and fovY=PI/2, the near plane half-extent = near * tan(PI/4) = near.
+    // Near = 1 → half-extent = 1. Near corner 0 should be (-1,-1, near_z) and corner 3 (1,1, near_z).
+    expect(corners[0].x).toBeCloseTo(-corners[1].x, 3);
+    expect(corners[0].y).toBeCloseTo(-corners[2].y, 3);
+    expect(corners[3].x).toBeCloseTo(-corners[2].x, 3);
+  });
+});

package/src/intersection.test.ts

@@ -0,0 +1,118 @@
+import { createBoundingSphere, createPlane, createRay3D, createVector3 } from '@flighthq/geometry';
+
+import { createCamera, setCameraViewMatrix4FromLookAt } from './camera';
+import { getCameraRayThroughBoundingSphere, intersectCameraRayWithPlane } from './intersection';
+import { createPerspectiveProjection } from './projection';
+
+function makeCamera() {
+  const camera = createCamera({
+    far: 100,
+    near: 0.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('getCameraRayThroughBoundingSphere', () => {
+  it('returns true for a sphere in front of the camera', () => {
+    const camera = makeCamera();
+    const sphere = createBoundingSphere(0, 0, 5, 1);
+    const ray = createRay3D();
+    const result = getCameraRayThroughBoundingSphere(ray, camera, sphere, 1);
+    expect(result).toBe(true);
+  });
+
+  it('returns a ray pointing from the camera toward the sphere center', () => {
+    const camera = makeCamera();
+    // Sphere centered at origin, camera at (0,0,10) looking toward (0,0,0).
+    const sphere = createBoundingSphere(0, 0, 0, 1);
+    const ray = createRay3D();
+    getCameraRayThroughBoundingSphere(ray, camera, sphere, 1);
+    // The direction should point toward -Z (from eye at 0,0,10 toward sphere center 0,0,0).
+    expect(ray.direction.x).toBeCloseTo(0, 3);
+    expect(ray.direction.y).toBeCloseTo(0, 3);
+    expect(ray.direction.z).toBeCloseTo(-1, 3);
+  });
+
+  it('returns false for an empty sphere (negative radius)', () => {
+    const camera = makeCamera();
+    const sphere = createBoundingSphere(0, 0, 5, -1);
+    const ray = createRay3D();
+    expect(getCameraRayThroughBoundingSphere(ray, camera, sphere, 1)).toBe(false);
+  });
+
+  it('returns false when the sphere center is behind the camera', () => {
+    const camera = makeCamera();
+    // Camera is at z=10 looking toward -Z. A sphere at z=15 is behind the camera.
+    const sphere = createBoundingSphere(0, 0, 15, 1);
+    const ray = createRay3D();
+    expect(getCameraRayThroughBoundingSphere(ray, camera, sphere, 1)).toBe(false);
+  });
+
+  it('is alias-safe when out shares fields with sphere center', () => {
+    const camera = makeCamera();
+    const sphere = createBoundingSphere(0, 0, 5, 1);
+    // Create a ray whose origin is the same object as sphere.center (aliasing).
+    const ray = createRay3D(sphere.center.x, sphere.center.y, sphere.center.z);
+    const result = getCameraRayThroughBoundingSphere(ray, camera, sphere, 1);
+    // Should succeed regardless of aliasing.
+    expect(result).toBe(true);
+  });
+});
+
+describe('intersectCameraRayWithPlane', () => {
+  it('returns the hit point for a ray pointing straight down into a horizontal plane', () => {
+    // Ray pointing straight down (-Y) from (0, 5, 0).
+    const ray = createRay3D(0, 5, 0, 0, -1, 0);
+    // Horizontal ground plane: y = 0 → 0x + 1y + 0z + 0 = 0.
+    const plane = createPlane(0, 1, 0, 0);
+    const hit = createVector3();
+    const result = intersectCameraRayWithPlane(hit, ray, plane);
+    expect(result).toBe(true);
+    expect(hit.x).toBeCloseTo(0, 5);
+    expect(hit.y).toBeCloseTo(0, 5);
+    expect(hit.z).toBeCloseTo(0, 5);
+  });
+
+  it('returns false when the ray is parallel to the plane', () => {
+    // Ray pointing horizontally (along X) and a vertical plane (normal = Y).
+    const ray = createRay3D(0, 1, 0, 1, 0, 0);
+    const plane = createPlane(0, 1, 0, -1); // y = 1
+    const hit = createVector3();
+    expect(intersectCameraRayWithPlane(hit, ray, plane)).toBe(false);
+  });
+
+  it('returns false when the intersection is behind the ray origin (t < 0)', () => {
+    // Ray pointing UP (+Y) from below a plane at y=0: the intersection t would be negative.
+    const ray = createRay3D(0, -5, 0, 0, 1, 0);
+    // Plane at y = -10: 0x + 1y + 0z + 10 = 0.
+    const plane = createPlane(0, 1, 0, 10);
+    const hit = createVector3();
+    // t = -(0*0 + 1*(-5) + 0*0 + 10) / (0*0 + 1*1 + 0*0) = -(5) / 1 = -5 < 0 → false.
+    expect(intersectCameraRayWithPlane(hit, ray, plane)).toBe(false);
+  });
+
+  it('computes the correct hit point for a diagonal ray against a diagonal plane', () => {
+    // Ray from (0,0,0) pointing diagonally (+1, +1, 0).
+    const ray = createRay3D(0, 0, 0, 1, 1, 0);
+    // Plane at x + y = 4: 1x + 1y + 0z - 4 = 0.
+    const plane = createPlane(1, 1, 0, -4);
+    const hit = createVector3();
+    const result = intersectCameraRayWithPlane(hit, ray, plane);
+    expect(result).toBe(true);
+    // t = -(0 + 0 - 4) / (1 + 1) = 4/2 = 2 → hit = (2, 2, 0).
+    expect(hit.x).toBeCloseTo(2, 5);
+    expect(hit.y).toBeCloseTo(2, 5);
+    expect(hit.z).toBeCloseTo(0, 5);
+  });
+
+  it('is alias-safe when out is the same object as the ray origin', () => {
+    const ray = createRay3D(0, 5, 0, 0, -1, 0);
+    const plane = createPlane(0, 1, 0, 0);
+    // Alias out = ray.origin.
+    const result = intersectCameraRayWithPlane(ray.origin, ray, plane);
+    expect(result).toBe(true);
+    expect(ray.origin.y).toBeCloseTo(0, 5);
+  });
+});

package/src/picking.test.ts

@@ -0,0 +1,94 @@
+import { createRay3D, createVector3 } from '@flighthq/geometry';
+
+import { createCamera, setCameraViewMatrix4FromLookAt } from './camera';
+import { getCameraScreenToWorldRay, getCameraWorldToScreen } from './picking';
+import { createPerspectiveProjection } from './projection';
+
+function makeCamera() {
+  return createCamera({
+    far: 100,
+    near: 0.1,
+    projection: createPerspectiveProjection({ aspect: 1, fovY: Math.PI / 2 }),
+  });
+}
+
+describe('getCameraScreenToWorldRay', () => {
+  it('returns a ray pointing from near toward far for center NDC (0,0)', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const ray = createRay3D();
+    const result = getCameraScreenToWorldRay(ray, camera, 0, 0, 1);
+    expect(result).toBe(true);
+    // Center ray should point along -Z (camera looks toward -Z).
+    expect(ray.direction.x).toBeCloseTo(0, 3);
+    expect(ray.direction.y).toBeCloseTo(0, 3);
+    expect(ray.direction.z).toBeCloseTo(-1, 3);
+  });
+
+  it('returns false when the view-projection is non-invertible', () => {
+    const camera = makeCamera();
+    // near == far collapses the depth range, making the matrix singular.
+    camera.near = 1;
+    camera.far = 1;
+    const ray = createRay3D();
+    const result = getCameraScreenToWorldRay(ray, camera, 0, 0, 1);
+    expect(result).toBe(false);
+  });
+
+  it('round-trips with getCameraWorldToScreen at the center point', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    // A world point directly ahead of the camera.
+    const worldPoint = createVector3(0, 0, 2);
+    const ndc = createVector3();
+    getCameraWorldToScreen(ndc, camera, worldPoint, 1);
+    // Unproject those NDC coordinates back.
+    const ray = createRay3D();
+    getCameraScreenToWorldRay(ray, camera, ndc.x, ndc.y, 1);
+    // The direction of the ray should point from the origin toward (0,0,2).
+    // Since the camera is at (0,0,5) looking at origin, forward is -Z.
+    expect(ray.direction.x).toBeCloseTo(0, 2);
+    expect(ray.direction.y).toBeCloseTo(0, 2);
+    expect(ray.direction.z).toBeCloseTo(-1, 2);
+  });
+});
+
+describe('getCameraWorldToScreen', () => {
+  it('maps a point in front of the camera to NDC with |x|, |y| <= 1', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const ndc = createVector3();
+    const result = getCameraWorldToScreen(ndc, camera, createVector3(0, 0, 2), 1);
+    expect(result).toBe(true);
+    expect(Math.abs(ndc.x)).toBeLessThanOrEqual(1);
+    expect(Math.abs(ndc.y)).toBeLessThanOrEqual(1);
+  });
+
+  it('maps the origin to (0,0) NDC for a camera looking along -Z', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const ndc = createVector3();
+    getCameraWorldToScreen(ndc, camera, createVector3(0, 0, 0), 1);
+    expect(ndc.x).toBeCloseTo(0, 3);
+    expect(ndc.y).toBeCloseTo(0, 3);
+  });
+
+  it('returns false for a point behind the camera', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const ndc = createVector3();
+    // A point behind the eye (z=10, camera eye is at z=5, looking toward z=0).
+    const result = getCameraWorldToScreen(ndc, camera, createVector3(0, 0, 10), 1);
+    expect(result).toBe(false);
+  });
+
+  it('is safe when out aliases worldPoint', () => {
+    const camera = makeCamera();
+    setCameraViewMatrix4FromLookAt(camera, createVector3(0, 0, 5), createVector3(0, 0, 0), createVector3(0, 1, 0));
+    const point = createVector3(0, 0, 2);
+    const result = getCameraWorldToScreen(point, camera, point, 1);
+    // Should succeed and write valid NDC into point (which was also worldPoint).
+    expect(result).toBe(true);
+    expect(Math.abs(point.x)).toBeLessThanOrEqual(1);
+  });
+});

package/src/projection.test.ts

@@ -0,0 +1,97 @@
+import { createMatrix4, createPerspectiveMatrix4, setOrthographicMatrix4 } from '@flighthq/geometry';
+import type { OrthographicProjection, PerspectiveProjection } from '@flighthq/types';
+
+import {
+  createOrthographicProjection,
+  createPerspectiveProjection,
+  isOrthographicProjection,
+  isPerspectiveProjection,
+  setProjectionMatrix4,
+} from './projection';
+
+describe('createOrthographicProjection', () => {
+  it('builds an orthographic descriptor from half-extents', () => {
+    const projection = createOrthographicProjection({ halfHeight: 3, halfWidth: 4 });
+    expect(projection.kind).toBe('orthographic');
+    expect(projection.halfWidth).toBe(4);
+    expect(projection.halfHeight).toBe(3);
+  });
+});
+
+describe('createPerspectiveProjection', () => {
+  it('builds a perspective descriptor from fovY and aspect', () => {
+    const projection = createPerspectiveProjection({ aspect: 1.5, fovY: Math.PI / 3 });
+    expect(projection.kind).toBe('perspective');
+    expect(projection.fovY).toBeCloseTo(Math.PI / 3);
+    expect(projection.aspect).toBe(1.5);
+  });
+
+  it('defaults aspect to 1 when omitted', () => {
+    const projection = createPerspectiveProjection({ fovY: 1 });
+    expect(projection.aspect).toBe(1);
+  });
+});
+
+describe('isOrthographicProjection', () => {
+  it('is true for orthographic and false for perspective', () => {
+    const ortho = createOrthographicProjection({ halfHeight: 1, halfWidth: 1 });
+    const persp = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    expect(isOrthographicProjection(ortho)).toBe(true);
+    expect(isOrthographicProjection(persp)).toBe(false);
+  });
+});
+
+describe('isPerspectiveProjection', () => {
+  it('is true for perspective and false for orthographic', () => {
+    const persp = createPerspectiveProjection({ aspect: 1, fovY: 1 });
+    const ortho = createOrthographicProjection({ halfHeight: 1, halfWidth: 1 });
+    expect(isPerspectiveProjection(persp)).toBe(true);
+    expect(isPerspectiveProjection(ortho)).toBe(false);
+  });
+});
+
+describe('setProjectionMatrix4', () => {
+  it('matches geometry perspective builder using tan(fovY/2)', () => {
+    const fovY = Math.PI / 2;
+    const aspect = 1.6;
+    const near = 0.1;
+    const far = 100;
+    const projection: PerspectiveProjection = createPerspectiveProjection({ aspect, fovY });
+
+    const out = createMatrix4();
+    setProjectionMatrix4(out, projection, aspect, near, far);
+
+    const expected = createPerspectiveMatrix4(Math.tan(fovY * 0.5), aspect, near, far);
+    for (let i = 0; i < 16; i++) {
+      expect(out.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+
+  it('uses the passed aspect over the projection stored aspect for perspective', () => {
+    const fovY = 1;
+    const projection = createPerspectiveProjection({ aspect: 1, fovY });
+
+    const out = createMatrix4();
+    setProjectionMatrix4(out, projection, 2, 0.5, 50);
+
+    const expected = createPerspectiveMatrix4(Math.tan(fovY * 0.5), 2, 0.5, 50);
+    for (let i = 0; i < 16; i++) {
+      expect(out.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+
+  it('matches geometry orthographic builder using symmetric half-extents', () => {
+    const projection: OrthographicProjection = createOrthographicProjection({ halfHeight: 3, halfWidth: 5 });
+    const near = 1;
+    const far = 20;
+
+    const out = createMatrix4();
+    setProjectionMatrix4(out, projection, 99, near, far);
+
+    const expected = createMatrix4();
+    setOrthographicMatrix4(expected, -5, 5, -3, 3, near, far);
+    for (let i = 0; i < 16; i++) {
+      expect(out.m[i]).toBeCloseTo(expected.m[i]);
+    }
+  });
+});

package/src/shadowCamera.test.ts

@@ -0,0 +1,45 @@
+import { createAabb } from '@flighthq/geometry';
+import type { OrthographicProjection } from '@flighthq/types';
+
+import { createCamera } from './camera';
+import { createPerspectiveProjection } from './projection';
+import { configureDirectionalShadowCamera } from './shadowCamera';
+
+function bounds() {
+  return createAabb(-1, -1, -1, 1, 1, 1);
+}
+
+describe('configureDirectionalShadowCamera', () => {
+  it('switches the camera to an orthographic frustum sized to the scene sphere', () => {
+    const camera = createCamera({
+      far: 100,
+      near: 0.1,
+      projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+    });
+
+    configureDirectionalShadowCamera(camera, { x: 0, y: -1, z: 0 }, bounds());
+
+    expect(camera.projection.kind).toBe('orthographic');
+    const radius = Math.hypot(1, 1, 1);
+    expect((camera.projection as OrthographicProjection).halfWidth).toBeCloseTo(radius);
+    expect(camera.near).toBeCloseTo(radius);
+    expect(camera.far).toBeCloseTo(radius * 3);
+  });
+
+  it('places the scene centre two radii in front along the light direction', () => {
+    const camera = createCamera({
+      far: 100,
+      near: 0.1,
+      projection: createPerspectiveProjection({ aspect: 1, fovY: 1 }),
+    });
+
+    configureDirectionalShadowCamera(camera, { x: 0, y: -1, z: 0 }, bounds());
+
+    // The world origin (= scene centre) maps to (0, 0, -distance) in the shadow camera's view space;
+    // the view matrix's translation column carries that view-space position of the world origin.
+    const distance = Math.hypot(1, 1, 1) * 2;
+    expect(camera.view.m[12]).toBeCloseTo(0);
+    expect(camera.view.m[13]).toBeCloseTo(0);
+    expect(camera.view.m[14]).toBeCloseTo(-distance);
+  });
+});