@flighthq/geometry 0.1.0

package/src/matrix4Pool.test.ts

@@ -0,0 +1,71 @@
+import { getMatrix4Element } from '@flighthq/geometry';
+import type { Matrix4 } from '@flighthq/types';
+
+import { acquireIdentityMatrix4, acquireMatrix4, clearMatrix4Pool, releaseMatrix4 } from './matrix4Pool';
+
+beforeEach(() => {
+  clearMatrix4Pool();
+});
+
+describe('acquireIdentityMatrix4', () => {
+  it('returns a matrix set to identity', () => {
+    const m = acquireIdentityMatrix4();
+    expect(getMatrix4Element(m, 0, 0)).toBe(1);
+    expect(getMatrix4Element(m, 0, 1)).toBe(0);
+    expect(getMatrix4Element(m, 1, 1)).toBe(1);
+    expect(getMatrix4Element(m, 2, 2)).toBe(1);
+    expect(getMatrix4Element(m, 3, 3)).toBe(1);
+    expect(getMatrix4Element(m, 0, 3)).toBe(0);
+    expect(getMatrix4Element(m, 3, 0)).toBe(0);
+  });
+
+  it('resets a released matrix to identity', () => {
+    const m1 = acquireMatrix4();
+    m1.m[0] = 5;
+    m1.m[12] = 10;
+    releaseMatrix4(m1);
+    const m2 = acquireIdentityMatrix4();
+    expect(m2).toBe(m1);
+    expect(getMatrix4Element(m2, 0, 0)).toBe(1);
+    expect(getMatrix4Element(m2, 3, 0)).toBe(0);
+  });
+});
+
+describe('acquireMatrix4', () => {
+  it('returns a new Matrix4 when pool is empty', () => {
+    const m: Matrix4 = acquireMatrix4();
+    expect(m).not.toBeNull();
+  });
+
+  it('reuses released matrices', () => {
+    const m1 = acquireMatrix4();
+    releaseMatrix4(m1);
+    const m2 = acquireMatrix4();
+    expect(m2).toBe(m1);
+  });
+
+  it('reuses released matrices in last-in-first-out order', () => {
+    const m1 = acquireMatrix4();
+    const m2 = acquireMatrix4();
+    releaseMatrix4(m1);
+    releaseMatrix4(m2);
+    expect(acquireMatrix4()).toBe(m2);
+    expect(acquireMatrix4()).toBe(m1);
+  });
+});
+
+describe('clearMatrix4Pool', () => {
+  it('empties the pool so the next get allocates fresh', () => {
+    const m = acquireMatrix4();
+    releaseMatrix4(m);
+    clearMatrix4Pool();
+    const m2 = acquireMatrix4();
+    expect(m2).not.toBe(m);
+  });
+});
+
+describe('releaseMatrix4', () => {
+  it('handles null safely', () => {
+    expect(() => releaseMatrix4(null as unknown as Matrix4)).not.toThrow();
+  });
+});

package/src/matrixPool.test.ts

@@ -0,0 +1,69 @@
+import type { Matrix } from '@flighthq/types';
+
+import { acquireIdentityMatrix, acquireMatrix, clearMatrixPool, releaseMatrix } from './matrixPool';
+
+beforeEach(() => {
+  clearMatrixPool();
+});
+
+describe('acquireIdentityMatrix', () => {
+  it('returns a new Matrix when pool is empty', () => {
+    const m: Matrix = acquireMatrix();
+    expect(m).not.toBeNull();
+  });
+
+  it('reuses released matrices', () => {
+    const m1 = acquireMatrix();
+    releaseMatrix(m1);
+    const m2 = acquireMatrix();
+    expect(m2).toBe(m1);
+  });
+
+  it('reuses released matrices in last-in-first-out order', () => {
+    const m1 = acquireMatrix();
+    const m2 = acquireMatrix();
+    releaseMatrix(m1);
+    releaseMatrix(m2);
+    expect(acquireMatrix()).toBe(m2);
+    expect(acquireMatrix()).toBe(m1);
+  });
+});
+
+describe('acquireMatrix', () => {
+  it('returns a matrix set to identity', () => {
+    const m = acquireIdentityMatrix();
+    expect(m.a).toBe(1);
+    expect(m.b).toBe(0);
+    expect(m.c).toBe(0);
+    expect(m.d).toBe(1);
+    expect(m.tx).toBe(0);
+    expect(m.ty).toBe(0);
+  });
+
+  it('resets a released matrix to identity', () => {
+    const m1 = acquireMatrix();
+    m1.a = 5;
+    m1.tx = 10;
+    releaseMatrix(m1);
+    const m2 = acquireIdentityMatrix();
+    expect(m2).toBe(m1);
+    expect(m2.a).toBe(1);
+    expect(m2.tx).toBe(0);
+  });
+});
+
+describe('clearMatrixPool', () => {
+  it('empties the pool so the next get allocates fresh', () => {
+    const m = acquireMatrix();
+    releaseMatrix(m);
+    clearMatrixPool();
+    const m2 = acquireMatrix();
+    expect(m2).not.toBe(m);
+  });
+});
+
+describe('releaseMatrix', () => {
+  it('handles null safely', () => {
+    expect(() => releaseMatrix(null as unknown as Matrix)).not.toThrow();
+  });
+});

package/src/obb.test.ts

@@ -0,0 +1,183 @@
+import {
+  createAabb,
+  createMatrix4,
+  createObb,
+  createRay3D,
+  createVector3,
+  getClosestPointOnObb,
+  intersectRay3DObb,
+  isObbIntersectingAabb,
+  isObbIntersectingObb,
+  setMatrix4Position,
+  setObb,
+  transformObbByMatrix4,
+} from '@flighthq/geometry';
+
+describe('createObb', () => {
+  it('stores center, half-extents, and orientation', () => {
+    const o = createObb(1, 2, 3, 4, 5, 6, 0, 0, 0, 1);
+    expect(o.centerX).toBe(1);
+    expect(o.centerY).toBe(2);
+    expect(o.centerZ).toBe(3);
+    expect(o.halfExtentX).toBe(4);
+    expect(o.halfExtentY).toBe(5);
+    expect(o.halfExtentZ).toBe(6);
+    expect(o.orientationX).toBe(0);
+    expect(o.orientationY).toBe(0);
+    expect(o.orientationZ).toBe(0);
+    expect(o.orientationW).toBe(1);
+  });
+});
+
+describe('getClosestPointOnObb', () => {
+  it('clamps an outside point to the nearest face of an axis-aligned OBB', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const out = createVector3();
+    getClosestPointOnObb(out, o, createVector3(5, 0, 0));
+    expect(out.x).toBeCloseTo(1, 6);
+    expect(out.y).toBeCloseTo(0, 6);
+    expect(out.z).toBeCloseTo(0, 6);
+  });
+
+  it('returns a point inside the OBB unchanged', () => {
+    const o = createObb(0, 0, 0, 2, 2, 2, 0, 0, 0, 1);
+    const out = createVector3();
+    getClosestPointOnObb(out, o, createVector3(1, 0.5, -0.5));
+    expect(out.x).toBeCloseTo(1, 6);
+    expect(out.y).toBeCloseTo(0.5, 6);
+    expect(out.z).toBeCloseTo(-0.5, 6);
+  });
+
+  it('handles off-center OBB with identity orientation', () => {
+    const o = createObb(10, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const out = createVector3();
+    getClosestPointOnObb(out, o, createVector3(0, 0, 0));
+    expect(out.x).toBeCloseTo(9, 6);
+    expect(out.y).toBeCloseTo(0, 6);
+    expect(out.z).toBeCloseTo(0, 6);
+  });
+
+  it('supports out === point', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const p = createVector3(5, 0, 0);
+    getClosestPointOnObb(p, o, p);
+    expect(p.x).toBeCloseTo(1, 6);
+  });
+});
+
+describe('intersectRay3DObb', () => {
+  it('hits a unit OBB at the expected t from outside', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    // Ray from (5,0,0) pointing in -X: should enter at x=1, t=4.
+    const ray = createRay3D(5, 0, 0, -1, 0, 0);
+    const t = intersectRay3DObb(ray, o);
+    expect(t).toBeCloseTo(4, 6);
+  });
+
+  it('returns -1 for a ray pointing away from the OBB', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const ray = createRay3D(5, 0, 0, 1, 0, 0);
+    expect(intersectRay3DObb(ray, o)).toBe(-1);
+  });
+
+  it('returns 0 for a ray starting inside the OBB', () => {
+    const o = createObb(0, 0, 0, 2, 2, 2, 0, 0, 0, 1);
+    const ray = createRay3D(0, 0, 0, 0, 0, 1);
+    expect(intersectRay3DObb(ray, o)).toBe(0);
+  });
+
+  it('returns -1 for a ray that misses an off-center OBB', () => {
+    const o = createObb(10, 10, 10, 1, 1, 1, 0, 0, 0, 1);
+    const ray = createRay3D(0, 0, 0, 1, 0, 0);
+    expect(intersectRay3DObb(ray, o)).toBe(-1);
+  });
+});
+
+describe('isObbIntersectingAabb', () => {
+  it('returns true for coincident OBB and AABB', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const a = createAabb(-1, -1, -1, 1, 1, 1);
+    expect(isObbIntersectingAabb(o, a)).toBe(true);
+  });
+
+  it('returns true for overlapping OBB and AABB', () => {
+    const o = createObb(0.5, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const a = createAabb(-1, -1, -1, 1, 1, 1);
+    expect(isObbIntersectingAabb(o, a)).toBe(true);
+  });
+
+  it('returns false for separated OBB and AABB', () => {
+    const o = createObb(10, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const a = createAabb(-1, -1, -1, 1, 1, 1);
+    expect(isObbIntersectingAabb(o, a)).toBe(false);
+  });
+});
+
+describe('isObbIntersectingObb', () => {
+  it('returns true for two coincident OBBs', () => {
+    const a = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const b = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    expect(isObbIntersectingObb(a, b)).toBe(true);
+  });
+
+  it('returns true for two overlapping OBBs', () => {
+    const a = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const b = createObb(1.5, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    expect(isObbIntersectingObb(a, b)).toBe(true);
+  });
+
+  it('returns false for two separated OBBs', () => {
+    const a = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const b = createObb(10, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    expect(isObbIntersectingObb(a, b)).toBe(false);
+  });
+});
+
+describe('setObb', () => {
+  it('updates all fields in place', () => {
+    const o = createObb(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+    setObb(o, 1, 2, 3, 4, 5, 6, 0.1, 0.2, 0.3, 0.9);
+    expect(o.centerX).toBe(1);
+    expect(o.centerY).toBe(2);
+    expect(o.centerZ).toBe(3);
+    expect(o.halfExtentX).toBe(4);
+    expect(o.halfExtentY).toBe(5);
+    expect(o.halfExtentZ).toBe(6);
+    expect(o.orientationX).toBe(0.1);
+    expect(o.orientationW).toBe(0.9);
+  });
+});
+
+describe('transformObbByMatrix4', () => {
+  it('translates the center by a translation matrix', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const m = createMatrix4();
+    setMatrix4Position(m, createVector3(5, 0, 0));
+    const out = createObb(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+    transformObbByMatrix4(out, o, m);
+    expect(out.centerX).toBeCloseTo(5, 6);
+    expect(out.centerY).toBeCloseTo(0, 6);
+    expect(out.halfExtentX).toBeCloseTo(1, 6);
+    expect(out.orientationW).toBeCloseTo(1, 5);
+  });
+
+  it('scales half-extents by a uniform scale matrix', () => {
+    const o = createObb(0, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const m = createMatrix4(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1);
+    const out = createObb(0, 0, 0, 0, 0, 0, 0, 0, 0, 1);
+    transformObbByMatrix4(out, o, m);
+    expect(out.halfExtentX).toBeCloseTo(2, 6);
+    expect(out.halfExtentY).toBeCloseTo(2, 6);
+    expect(out.halfExtentZ).toBeCloseTo(2, 6);
+  });
+
+  it('supports out === obb', () => {
+    const o = createObb(1, 0, 0, 1, 1, 1, 0, 0, 0, 1);
+    const m = createMatrix4();
+    setMatrix4Position(m, createVector3(0, 3, 0));
+    transformObbByMatrix4(o, o, m);
+    expect(o.centerX).toBeCloseTo(1, 6);
+    expect(o.centerY).toBeCloseTo(3, 6);
+    expect(o.halfExtentX).toBeCloseTo(1, 6);
+  });
+});

package/src/plane.test.ts

@@ -0,0 +1,225 @@
+import {
+  clonePlane,
+  copyPlane,
+  createPlane,
+  createVector3,
+  getClosestPointOnPlane,
+  getPlaneCoplanarPoint,
+  getPlaneSignedDistanceToPoint,
+  normalizePlane,
+  projectVector3OntoPlane,
+  setPlane,
+  setPlaneFromNormalAndPoint,
+  setPlaneFromPoints,
+} from '@flighthq/geometry';
+
+describe('clonePlane', () => {
+  it('creates an independent copy', () => {
+    const p = createPlane(1, 0, 0, -5);
+    const c = clonePlane(p);
+    expect(c).not.toBe(p);
+    expect(c.a).toBe(1);
+    expect(c.d).toBe(-5);
+  });
+});
+
+describe('copyPlane', () => {
+  it('copies all coefficients', () => {
+    const src = createPlane(0, 1, 0, 3);
+    const out = createPlane();
+    copyPlane(out, src);
+    expect(out.a).toBe(0);
+    expect(out.b).toBe(1);
+    expect(out.c).toBe(0);
+    expect(out.d).toBe(3);
+  });
+
+  it('supports out === source', () => {
+    const p = createPlane(2, 3, 4, 5);
+    copyPlane(p, p);
+    expect(p.a).toBe(2);
+    expect(p.d).toBe(5);
+  });
+});
+
+describe('createPlane', () => {
+  it('defaults to zeros', () => {
+    const p = createPlane();
+    expect(p.a).toBe(0);
+    expect(p.b).toBe(0);
+    expect(p.c).toBe(0);
+    expect(p.d).toBe(0);
+  });
+
+  it('uses provided coefficients', () => {
+    const p = createPlane(1, 2, 3, 4);
+    expect(p.a).toBe(1);
+    expect(p.b).toBe(2);
+    expect(p.c).toBe(3);
+    expect(p.d).toBe(4);
+  });
+});
+
+describe('getClosestPointOnPlane', () => {
+  it('projects a point onto the plane along the normal', () => {
+    // Plane z = 0 => normal (0,0,1), d = 0.
+    const p = createPlane(0, 0, 1, 0);
+    const out = createVector3();
+    getClosestPointOnPlane(out, p, createVector3(2, 3, 5));
+    expect(out.x).toBeCloseTo(2, 6);
+    expect(out.y).toBeCloseTo(3, 6);
+    expect(out.z).toBeCloseTo(0, 6);
+  });
+
+  it('leaves a point already on the plane in place', () => {
+    const p = createPlane(1, 0, 0, -5);
+    const out = createVector3();
+    getClosestPointOnPlane(out, p, createVector3(5, 1, 2));
+    expect(out.x).toBeCloseTo(5, 6);
+    expect(out.y).toBeCloseTo(1, 6);
+    expect(out.z).toBeCloseTo(2, 6);
+  });
+
+  it('agrees with projectVector3OntoPlane', () => {
+    const p = createPlane(0, 1, 0, -3);
+    const closest = createVector3();
+    const projected = createVector3();
+    getClosestPointOnPlane(closest, p, createVector3(4, 7, -2));
+    projectVector3OntoPlane(projected, createVector3(4, 7, -2), p);
+    expect(closest.x).toBeCloseTo(projected.x, 6);
+    expect(closest.y).toBeCloseTo(projected.y, 6);
+    expect(closest.z).toBeCloseTo(projected.z, 6);
+  });
+
+  it('supports out === point', () => {
+    const p = createPlane(0, 0, 1, 0);
+    const v = createVector3(1, 2, 9);
+    getClosestPointOnPlane(v, p, v);
+    expect(v.z).toBeCloseTo(0, 6);
+  });
+});
+
+describe('getPlaneCoplanarPoint', () => {
+  it('point on the plane has signed distance zero', () => {
+    // Plane x = 5 => normal (+1,0,0), d = -5.
+    const p = createPlane(1, 0, 0, -5);
+    const out = createVector3();
+    getPlaneCoplanarPoint(out, p);
+    expect(getPlaneSignedDistanceToPoint(p, out)).toBeCloseTo(0, 6);
+  });
+});
+
+describe('getPlaneSignedDistanceToPoint', () => {
+  it('is positive on the normal side and negative behind', () => {
+    // Plane x = 0 with normal +x.
+    const p = createPlane(1, 0, 0, 0);
+    expect(getPlaneSignedDistanceToPoint(p, createVector3(3, 0, 0))).toBeCloseTo(3, 6);
+    expect(getPlaneSignedDistanceToPoint(p, createVector3(-2, 5, 9))).toBeCloseTo(-2, 6);
+  });
+
+  it('accounts for the plane offset', () => {
+    // Plane x = 4 with normal +x => a*x + d = x - 4.
+    const p = createPlane(1, 0, 0, -4);
+    expect(getPlaneSignedDistanceToPoint(p, createVector3(4, 0, 0))).toBeCloseTo(0, 6);
+  });
+});
+
+describe('normalizePlane', () => {
+  it('normalizes a plane with non-unit normal', () => {
+    // Normal (0,2,0), d=4 → normalized (0,1,0), d=2.
+    const p = createPlane(0, 2, 0, 4);
+    const out = createPlane();
+    normalizePlane(out, p);
+    expect(out.b).toBeCloseTo(1, 6);
+    expect(out.d).toBeCloseTo(2, 6);
+  });
+
+  it('supports out === source', () => {
+    const p = createPlane(0, 3, 0, 6);
+    normalizePlane(p, p);
+    expect(p.b).toBeCloseTo(1, 6);
+    expect(p.d).toBeCloseTo(2, 6);
+  });
+
+  it('leaves a degenerate plane unchanged', () => {
+    const p = createPlane(0, 0, 0, 5);
+    const out = createPlane();
+    normalizePlane(out, p);
+    expect(out.d).toBe(5);
+  });
+});
+
+describe('projectVector3OntoPlane', () => {
+  it('projects a point above the XZ plane down to y=0', () => {
+    // Plane y=0: normal (0,1,0), d=0.
+    const plane = createPlane(0, 1, 0, 0);
+    const out = createVector3();
+    projectVector3OntoPlane(out, createVector3(3, 5, 2), plane);
+    expect(out.x).toBeCloseTo(3, 6);
+    expect(out.y).toBeCloseTo(0, 6);
+    expect(out.z).toBeCloseTo(2, 6);
+  });
+
+  it('supports out === point', () => {
+    const plane = createPlane(1, 0, 0, 0);
+    const pt = createVector3(4, 2, 1);
+    projectVector3OntoPlane(pt, pt, plane);
+    expect(pt.x).toBeCloseTo(0, 6);
+    expect(pt.y).toBeCloseTo(2, 6);
+    expect(pt.z).toBeCloseTo(1, 6);
+  });
+});
+
+describe('setPlane', () => {
+  it('sets all coefficients', () => {
+    const p = createPlane();
+    setPlane(p, 9, 8, 7, 6);
+    expect(p.a).toBe(9);
+    expect(p.b).toBe(8);
+    expect(p.c).toBe(7);
+    expect(p.d).toBe(6);
+  });
+});
+
+describe('setPlaneFromNormalAndPoint', () => {
+  it('builds a plane that contains the given point', () => {
+    const normal = createVector3(0, 1, 0);
+    const point = createVector3(0, 5, 0);
+    const p = createPlane();
+    setPlaneFromNormalAndPoint(p, normal, point);
+    expect(getPlaneSignedDistanceToPoint(p, point)).toBeCloseTo(0, 6);
+  });
+
+  it('stores the normal in (a, b, c)', () => {
+    const normal = createVector3(1, 0, 0);
+    const point = createVector3(3, 0, 0);
+    const p = createPlane();
+    setPlaneFromNormalAndPoint(p, normal, point);
+    expect(p.a).toBeCloseTo(1, 6);
+    expect(p.b).toBeCloseTo(0, 6);
+    expect(p.c).toBeCloseTo(0, 6);
+    expect(p.d).toBeCloseTo(-3, 6);
+  });
+});
+
+describe('setPlaneFromPoints', () => {
+  it('builds the XZ plane from three points in XZ', () => {
+    const p = createPlane();
+    setPlaneFromPoints(p, createVector3(0, 0, 0), createVector3(1, 0, 0), createVector3(0, 0, 1));
+    // Normal should be +y (right-hand rule CCW from top)
+    expect(Math.abs(p.b)).toBeCloseTo(1, 5);
+    expect(p.a).toBeCloseTo(0, 5);
+    expect(p.c).toBeCloseTo(0, 5);
+  });
+
+  it('all three points lie on the resulting plane', () => {
+    const a = createVector3(1, 2, 3);
+    const b = createVector3(4, 0, 1);
+    const c = createVector3(-1, 3, 5);
+    const p = createPlane();
+    setPlaneFromPoints(p, a, b, c);
+    expect(getPlaneSignedDistanceToPoint(p, a)).toBeCloseTo(0, 5);
+    expect(getPlaneSignedDistanceToPoint(p, b)).toBeCloseTo(0, 5);
+    expect(getPlaneSignedDistanceToPoint(p, c)).toBeCloseTo(0, 5);
+  });
+});