@flighthq/geometry 0.1.0

package/src/aabb.test.ts

@@ -0,0 +1,341 @@
+import {
+  cloneAabb,
+  copyAabb,
+  createAabb,
+  createBoundingSphere,
+  createMatrix4,
+  createVector3,
+  expandAabbByPoint,
+  expandAabbBySphere,
+  getAabbCenter,
+  getAabbContainsPoint,
+  getAabbExtents,
+  getAabbSize,
+  getClosestPointOnAabb,
+  intersectAabb,
+  isAabbIntersectingAabb,
+  setAabb,
+  setAabbFromPoints,
+  setMatrix4Position,
+  transformAabbByMatrix4,
+  unionAabb,
+} from '@flighthq/geometry';
+
+describe('cloneAabb', () => {
+  it('creates an independent copy with independent corner vectors', () => {
+    const a = createAabb(-1, -2, -3, 4, 5, 6);
+    const c = cloneAabb(a);
+    expect(c).not.toBe(a);
+    expect(c.min).not.toBe(a.min);
+    expect(c.min.x).toBe(-1);
+    expect(c.max.z).toBe(6);
+    c.min.x = 99;
+    expect(a.min.x).toBe(-1);
+  });
+});
+
+describe('copyAabb', () => {
+  it('copies both corners', () => {
+    const src = createAabb(-1, -2, -3, 4, 5, 6);
+    const out = createAabb();
+    copyAabb(out, src);
+    expect(out.min.x).toBe(-1);
+    expect(out.max.y).toBe(5);
+  });
+
+  it('supports out === source', () => {
+    const a = createAabb(-1, -2, -3, 4, 5, 6);
+    copyAabb(a, a);
+    expect(a.min.x).toBe(-1);
+    expect(a.max.z).toBe(6);
+  });
+});
+
+describe('createAabb', () => {
+  it('defaults to an empty box (min > max)', () => {
+    const a = createAabb();
+    expect(a.min.x).toBe(Number.POSITIVE_INFINITY);
+    expect(a.max.x).toBe(Number.NEGATIVE_INFINITY);
+  });
+
+  it('uses provided corners', () => {
+    const a = createAabb(1, 2, 3, 4, 5, 6);
+    expect(a.min.x).toBe(1);
+    expect(a.max.z).toBe(6);
+  });
+});
+
+describe('expandAabbByPoint', () => {
+  it('an empty box snaps exactly to the first point', () => {
+    const a = createAabb();
+    const out = createAabb();
+    expandAabbByPoint(out, a, createVector3(2, 3, 4));
+    expect(out.min.x).toBe(2);
+    expect(out.max.x).toBe(2);
+    expect(out.min.z).toBe(4);
+    expect(out.max.z).toBe(4);
+  });
+
+  it('grows to include a point outside the box', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const out = createAabb();
+    expandAabbByPoint(out, a, createVector3(-5, 2, 0.5));
+    expect(out.min.x).toBe(-5);
+    expect(out.max.y).toBe(2);
+    expect(out.max.z).toBe(1);
+  });
+
+  it('supports out === aabb', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    expandAabbByPoint(a, a, createVector3(3, -3, 3));
+    expect(a.min.y).toBe(-3);
+    expect(a.max.x).toBe(3);
+  });
+});
+
+describe('expandAabbBySphere', () => {
+  it('grows the box to contain the sphere', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const s = createBoundingSphere(0, 0, 0, 3);
+    const out = createAabb();
+    expandAabbBySphere(out, a, s);
+    expect(out.min.x).toBe(-3);
+    expect(out.max.x).toBe(3);
+    expect(out.min.y).toBe(-3);
+    expect(out.max.y).toBe(3);
+  });
+
+  it('an empty sphere leaves the box unchanged', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const s = createBoundingSphere(0, 0, 0, -1);
+    const out = createAabb();
+    expandAabbBySphere(out, a, s);
+    expect(out.min.x).toBe(0);
+    expect(out.max.x).toBe(1);
+  });
+
+  it('supports out === aabb', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const s = createBoundingSphere(5, 0, 0, 1);
+    expandAabbBySphere(a, a, s);
+    expect(a.max.x).toBe(6);
+  });
+});
+
+describe('getAabbCenter', () => {
+  it('writes the midpoint of the corners', () => {
+    const a = createAabb(-2, -4, -6, 2, 4, 6);
+    const out = createVector3();
+    getAabbCenter(out, a);
+    expect(out.x).toBe(0);
+    expect(out.y).toBe(0);
+    expect(out.z).toBe(0);
+  });
+});
+
+describe('getAabbContainsPoint', () => {
+  it('returns true for an interior point and on the boundary', () => {
+    const a = createAabb(0, 0, 0, 2, 2, 2);
+    expect(getAabbContainsPoint(a, createVector3(1, 1, 1))).toBe(true);
+    expect(getAabbContainsPoint(a, createVector3(0, 2, 0))).toBe(true);
+  });
+
+  it('returns false for a point outside', () => {
+    const a = createAabb(0, 0, 0, 2, 2, 2);
+    expect(getAabbContainsPoint(a, createVector3(3, 1, 1))).toBe(false);
+  });
+});
+
+describe('getAabbExtents', () => {
+  it('writes half-widths of the box', () => {
+    const a = createAabb(-2, -4, -6, 2, 4, 6);
+    const out = createVector3();
+    getAabbExtents(out, a);
+    expect(out.x).toBe(2);
+    expect(out.y).toBe(4);
+    expect(out.z).toBe(6);
+  });
+});
+
+describe('getAabbSize', () => {
+  it('writes the full width/height/depth', () => {
+    const a = createAabb(-1, -2, -3, 3, 6, 9);
+    const out = createVector3();
+    getAabbSize(out, a);
+    expect(out.x).toBe(4);
+    expect(out.y).toBe(8);
+    expect(out.z).toBe(12);
+  });
+});
+
+describe('getClosestPointOnAabb', () => {
+  it('clamps an outside point to the nearest face', () => {
+    const a = createAabb(0, 0, 0, 2, 2, 2);
+    const out = createVector3();
+    getClosestPointOnAabb(out, a, createVector3(5, -1, 1));
+    expect(out.x).toBe(2);
+    expect(out.y).toBe(0);
+    expect(out.z).toBe(1);
+  });
+
+  it('returns the point unchanged when it is inside the box', () => {
+    const a = createAabb(0, 0, 0, 4, 4, 4);
+    const out = createVector3();
+    getClosestPointOnAabb(out, a, createVector3(1, 2, 3));
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(2);
+    expect(out.z).toBe(3);
+  });
+
+  it('supports out === point', () => {
+    const a = createAabb(0, 0, 0, 2, 2, 2);
+    const p = createVector3(-3, 5, 1);
+    getClosestPointOnAabb(p, a, p);
+    expect(p.x).toBe(0);
+    expect(p.y).toBe(2);
+    expect(p.z).toBe(1);
+  });
+});
+
+describe('intersectAabb', () => {
+  it('produces the overlapping sub-box for two overlapping boxes', () => {
+    const a = createAabb(0, 0, 0, 4, 4, 4);
+    const b = createAabb(2, 2, 2, 6, 6, 6);
+    const out = createAabb();
+    intersectAabb(out, a, b);
+    expect(out.min.x).toBe(2);
+    expect(out.max.x).toBe(4);
+    expect(out.min.y).toBe(2);
+    expect(out.max.y).toBe(4);
+  });
+
+  it('produces an empty box (min > max) for non-overlapping boxes', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const b = createAabb(5, 5, 5, 6, 6, 6);
+    const out = createAabb();
+    intersectAabb(out, a, b);
+    // min > max in at least one axis
+    expect(out.min.x).toBeGreaterThan(out.max.x);
+  });
+
+  it('supports out === a', () => {
+    const a = createAabb(0, 0, 0, 4, 4, 4);
+    const b = createAabb(2, 2, 2, 6, 6, 6);
+    intersectAabb(a, a, b);
+    expect(a.min.x).toBe(2);
+    expect(a.max.x).toBe(4);
+  });
+});
+
+describe('isAabbIntersectingAabb', () => {
+  it('returns true for overlapping boxes', () => {
+    const a = createAabb(0, 0, 0, 2, 2, 2);
+    const b = createAabb(1, 1, 1, 3, 3, 3);
+    expect(isAabbIntersectingAabb(a, b)).toBe(true);
+  });
+
+  it('returns true for touching boxes (shared face)', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const b = createAabb(1, 0, 0, 2, 1, 1);
+    expect(isAabbIntersectingAabb(a, b)).toBe(true);
+  });
+
+  it('returns false for separated boxes', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const b = createAabb(5, 5, 5, 6, 6, 6);
+    expect(isAabbIntersectingAabb(a, b)).toBe(false);
+  });
+});
+
+describe('setAabb', () => {
+  it('sets both corners', () => {
+    const a = createAabb();
+    setAabb(a, -1, -1, -1, 1, 1, 1);
+    expect(a.min.x).toBe(-1);
+    expect(a.max.z).toBe(1);
+  });
+});
+
+describe('setAabbFromPoints', () => {
+  it('computes the tight box over a set of points', () => {
+    const a = createAabb();
+    setAabbFromPoints(a, [createVector3(1, 5, -2), createVector3(-3, 0, 4), createVector3(2, 2, 2)]);
+    expect(a.min.x).toBe(-3);
+    expect(a.min.y).toBe(0);
+    expect(a.min.z).toBe(-2);
+    expect(a.max.x).toBe(2);
+    expect(a.max.y).toBe(5);
+    expect(a.max.z).toBe(4);
+  });
+
+  it('empty list yields an empty box', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    setAabbFromPoints(a, []);
+    expect(a.min.x).toBe(Number.POSITIVE_INFINITY);
+    expect(a.max.x).toBe(Number.NEGATIVE_INFINITY);
+  });
+});
+
+describe('transformAabbByMatrix4', () => {
+  it('translates the box', () => {
+    const a = createAabb(-1, -1, -1, 1, 1, 1);
+    const m = createMatrix4();
+    setMatrix4Position(m, createVector3(10, 0, 0));
+    const out = createAabb();
+    transformAabbByMatrix4(out, a, m);
+    expect(out.min.x).toBeCloseTo(9, 6);
+    expect(out.max.x).toBeCloseTo(11, 6);
+    expect(out.min.y).toBeCloseTo(-1, 6);
+  });
+
+  it('grows the box under a 45-degree rotation about z', () => {
+    const a = createAabb(-1, -1, -1, 1, 1, 1);
+    // Column-major 45-degree z rotation.
+    const c = Math.SQRT1_2;
+    const m = createMatrix4(c, c, 0, 0, -c, c, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
+    const out = createAabb();
+    transformAabbByMatrix4(out, a, m);
+    // Rotated unit box spans +/- sqrt(2) in x and y.
+    expect(out.max.x).toBeCloseTo(Math.SQRT2, 5);
+    expect(out.min.x).toBeCloseTo(-Math.SQRT2, 5);
+    expect(out.max.z).toBeCloseTo(1, 6);
+  });
+
+  it('supports out === aabb', () => {
+    const a = createAabb(-1, -1, -1, 1, 1, 1);
+    const m = createMatrix4();
+    setMatrix4Position(m, createVector3(5, 5, 5));
+    transformAabbByMatrix4(a, a, m);
+    expect(a.min.x).toBeCloseTo(4, 6);
+    expect(a.max.z).toBeCloseTo(6, 6);
+  });
+});
+
+describe('unionAabb', () => {
+  it('encloses both boxes', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const b = createAabb(-2, 3, -1, -1, 5, 0);
+    const out = createAabb();
+    unionAabb(out, a, b);
+    expect(out.min.x).toBe(-2);
+    expect(out.min.z).toBe(-1);
+    expect(out.max.y).toBe(5);
+    expect(out.max.x).toBe(1);
+  });
+
+  it('supports out === a', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const b = createAabb(-2, 0, 0, 0, 4, 0);
+    unionAabb(a, a, b);
+    expect(a.min.x).toBe(-2);
+    expect(a.max.y).toBe(4);
+  });
+
+  it('supports out === b', () => {
+    const a = createAabb(0, 0, 0, 1, 1, 1);
+    const b = createAabb(-2, 0, 0, 0, 4, 0);
+    unionAabb(b, a, b);
+    expect(b.min.x).toBe(-2);
+    expect(b.max.y).toBe(4);
+  });
+});

package/src/boundingSphere.test.ts

@@ -0,0 +1,247 @@
+import {
+  cloneBoundingSphere,
+  copyBoundingSphere,
+  createAabb,
+  createBoundingSphere,
+  createMatrix4,
+  createVector3,
+  getBoundingSphereContainsPoint,
+  getClosestPointOnBoundingSphere,
+  isBoundingSphereIntersectingBoundingSphere,
+  mergeBoundingSphere,
+  setBoundingSphere,
+  setBoundingSphereFromAabb,
+  setMatrix4Position,
+  transformBoundingSphereByMatrix4,
+} from '@flighthq/geometry';
+
+describe('cloneBoundingSphere', () => {
+  it('creates an independent copy with an independent center', () => {
+    const s = createBoundingSphere(1, 2, 3, 4);
+    const c = cloneBoundingSphere(s);
+    expect(c).not.toBe(s);
+    expect(c.center).not.toBe(s.center);
+    expect(c.center.x).toBe(1);
+    expect(c.radius).toBe(4);
+    c.center.x = 99;
+    expect(s.center.x).toBe(1);
+  });
+});
+
+describe('copyBoundingSphere', () => {
+  it('copies center and radius', () => {
+    const src = createBoundingSphere(1, 2, 3, 4);
+    const out = createBoundingSphere();
+    copyBoundingSphere(out, src);
+    expect(out.center.x).toBe(1);
+    expect(out.radius).toBe(4);
+  });
+
+  it('supports out === source', () => {
+    const s = createBoundingSphere(1, 2, 3, 4);
+    copyBoundingSphere(s, s);
+    expect(s.center.y).toBe(2);
+    expect(s.radius).toBe(4);
+  });
+});
+
+describe('createBoundingSphere', () => {
+  it('defaults to an empty sphere (negative radius)', () => {
+    const s = createBoundingSphere();
+    expect(s.center.x).toBe(0);
+    expect(s.radius).toBe(-1);
+  });
+
+  it('uses provided center and radius', () => {
+    const s = createBoundingSphere(1, 2, 3, 5);
+    expect(s.center.z).toBe(3);
+    expect(s.radius).toBe(5);
+  });
+});
+
+describe('getBoundingSphereContainsPoint', () => {
+  it('returns true inside and on the surface', () => {
+    const s = createBoundingSphere(0, 0, 0, 2);
+    expect(getBoundingSphereContainsPoint(s, createVector3(1, 0, 0))).toBe(true);
+    expect(getBoundingSphereContainsPoint(s, createVector3(2, 0, 0))).toBe(true);
+  });
+
+  it('returns false outside', () => {
+    const s = createBoundingSphere(0, 0, 0, 2);
+    expect(getBoundingSphereContainsPoint(s, createVector3(3, 0, 0))).toBe(false);
+  });
+
+  it('an empty sphere contains no points', () => {
+    const s = createBoundingSphere(0, 0, 0, -1);
+    expect(getBoundingSphereContainsPoint(s, createVector3(0, 0, 0))).toBe(false);
+  });
+});
+
+describe('getClosestPointOnBoundingSphere', () => {
+  it('projects an outside point onto the surface', () => {
+    const s = createBoundingSphere(0, 0, 0, 2);
+    const out = createVector3();
+    getClosestPointOnBoundingSphere(out, s, createVector3(10, 0, 0));
+    expect(out.x).toBeCloseTo(2, 6);
+    expect(out.y).toBeCloseTo(0, 6);
+    expect(out.z).toBeCloseTo(0, 6);
+  });
+
+  it('pulls an inside point out to the surface', () => {
+    const s = createBoundingSphere(0, 0, 0, 5);
+    const out = createVector3();
+    getClosestPointOnBoundingSphere(out, s, createVector3(0, 1, 0));
+    expect(out.x).toBeCloseTo(0, 6);
+    expect(out.y).toBeCloseTo(5, 6);
+    expect(out.z).toBeCloseTo(0, 6);
+  });
+
+  it('uses the +X fallback when the point is at the center', () => {
+    const s = createBoundingSphere(1, 2, 3, 4);
+    const out = createVector3();
+    getClosestPointOnBoundingSphere(out, s, createVector3(1, 2, 3));
+    expect(out.x).toBeCloseTo(5, 6);
+    expect(out.y).toBeCloseTo(2, 6);
+    expect(out.z).toBeCloseTo(3, 6);
+  });
+
+  it('writes the center for an empty sphere', () => {
+    const s = createBoundingSphere(1, 2, 3, -1);
+    const out = createVector3();
+    getClosestPointOnBoundingSphere(out, s, createVector3(9, 9, 9));
+    expect(out.x).toBe(1);
+    expect(out.y).toBe(2);
+    expect(out.z).toBe(3);
+  });
+
+  it('supports out === point', () => {
+    const s = createBoundingSphere(0, 0, 0, 3);
+    const p = createVector3(6, 0, 0);
+    getClosestPointOnBoundingSphere(p, s, p);
+    expect(p.x).toBeCloseTo(3, 6);
+  });
+});
+
+describe('isBoundingSphereIntersectingBoundingSphere', () => {
+  it('returns true for overlapping spheres', () => {
+    const a = createBoundingSphere(0, 0, 0, 2);
+    const b = createBoundingSphere(3, 0, 0, 2);
+    expect(isBoundingSphereIntersectingBoundingSphere(a, b)).toBe(true);
+  });
+
+  it('returns true for touching spheres', () => {
+    const a = createBoundingSphere(0, 0, 0, 1);
+    const b = createBoundingSphere(2, 0, 0, 1);
+    expect(isBoundingSphereIntersectingBoundingSphere(a, b)).toBe(true);
+  });
+
+  it('returns false for separated spheres', () => {
+    const a = createBoundingSphere(0, 0, 0, 1);
+    const b = createBoundingSphere(5, 0, 0, 1);
+    expect(isBoundingSphereIntersectingBoundingSphere(a, b)).toBe(false);
+  });
+
+  it('returns false if either sphere is empty', () => {
+    const a = createBoundingSphere(0, 0, 0, 1);
+    const empty = createBoundingSphere(0, 0, 0, -1);
+    expect(isBoundingSphereIntersectingBoundingSphere(a, empty)).toBe(false);
+    expect(isBoundingSphereIntersectingBoundingSphere(empty, a)).toBe(false);
+  });
+});
+
+describe('mergeBoundingSphere', () => {
+  it('merges two overlapping spheres into a containing sphere', () => {
+    const a = createBoundingSphere(-1, 0, 0, 1);
+    const b = createBoundingSphere(1, 0, 0, 1);
+    const out = createBoundingSphere();
+    mergeBoundingSphere(out, a, b);
+    // Both original spheres must be contained.
+    expect(getBoundingSphereContainsPoint(out, createVector3(-2, 0, 0))).toBe(true);
+    expect(getBoundingSphereContainsPoint(out, createVector3(2, 0, 0))).toBe(true);
+  });
+
+  it('if a contains b, result equals a', () => {
+    const a = createBoundingSphere(0, 0, 0, 10);
+    const b = createBoundingSphere(1, 0, 0, 1);
+    const out = createBoundingSphere();
+    mergeBoundingSphere(out, a, b);
+    expect(out.center.x).toBeCloseTo(0, 5);
+    expect(out.radius).toBeCloseTo(10, 5);
+  });
+
+  it('empty source returns the other sphere', () => {
+    const a = createBoundingSphere();
+    const b = createBoundingSphere(3, 0, 0, 2);
+    const out = createBoundingSphere();
+    mergeBoundingSphere(out, a, b);
+    expect(out.center.x).toBeCloseTo(3, 5);
+    expect(out.radius).toBeCloseTo(2, 5);
+  });
+
+  it('supports out === a', () => {
+    const a = createBoundingSphere(-1, 0, 0, 1);
+    const b = createBoundingSphere(1, 0, 0, 1);
+    mergeBoundingSphere(a, a, b);
+    expect(getBoundingSphereContainsPoint(a, createVector3(-2, 0, 0))).toBe(true);
+    expect(getBoundingSphereContainsPoint(a, createVector3(2, 0, 0))).toBe(true);
+  });
+});
+
+describe('setBoundingSphere', () => {
+  it('sets center and radius', () => {
+    const s = createBoundingSphere();
+    setBoundingSphere(s, 5, 6, 7, 8);
+    expect(s.center.x).toBe(5);
+    expect(s.radius).toBe(8);
+  });
+});
+
+describe('setBoundingSphereFromAabb', () => {
+  it('centers on the box and reaches its corners', () => {
+    const aabb = createAabb(-1, -1, -1, 1, 1, 1);
+    const s = createBoundingSphere();
+    setBoundingSphereFromAabb(s, aabb);
+    expect(s.center.x).toBe(0);
+    expect(s.center.y).toBe(0);
+    expect(s.center.z).toBe(0);
+    expect(s.radius).toBeCloseTo(Math.sqrt(3), 6);
+  });
+
+  it('an empty box yields an empty sphere', () => {
+    const aabb = createAabb();
+    const s = createBoundingSphere(0, 0, 0, 5);
+    setBoundingSphereFromAabb(s, aabb);
+    expect(s.radius).toBe(-1);
+  });
+});
+
+describe('transformBoundingSphereByMatrix4', () => {
+  it('translates the center and preserves the radius', () => {
+    const s = createBoundingSphere(0, 0, 0, 2);
+    const m = createMatrix4();
+    setMatrix4Position(m, createVector3(10, 0, 0));
+    const out = createBoundingSphere();
+    transformBoundingSphereByMatrix4(out, s, m);
+    expect(out.center.x).toBeCloseTo(10, 6);
+    expect(out.radius).toBeCloseTo(2, 6);
+  });
+
+  it('scales the radius by the largest axis scale', () => {
+    const s = createBoundingSphere(0, 0, 0, 1);
+    // Column-major non-uniform scale diag(2,3,4).
+    const m = createMatrix4(2, 0, 0, 0, 0, 3, 0, 0, 0, 0, 4, 0, 0, 0, 0, 1);
+    const out = createBoundingSphere();
+    transformBoundingSphereByMatrix4(out, s, m);
+    expect(out.radius).toBeCloseTo(4, 6);
+  });
+
+  it('supports out === sphere', () => {
+    const s = createBoundingSphere(1, 0, 0, 2);
+    const m = createMatrix4();
+    setMatrix4Position(m, createVector3(0, 5, 0));
+    transformBoundingSphereByMatrix4(s, s, m);
+    expect(s.center.x).toBeCloseTo(1, 6);
+    expect(s.center.y).toBeCloseTo(5, 6);
+    expect(s.radius).toBeCloseTo(2, 6);
+  });
+});