@johnhenry/math 0.0.0

package/src/FFT.ts

@@ -0,0 +1,146 @@
+import { ComplexNumber } from "./ComplexNumber.ts";
+
+/**
+ * FFT — the discrete Fourier transform and its fast (Cooley-Tukey) radix-2
+ * implementation, plus the inverse transform and FFT-based convolution. Builds
+ * on {@link ComplexNumber}. Inputs may be complex numbers or plain reals.
+ */
+
+type Signal = ReadonlyArray<ComplexNumber | number>;
+
+const toParts = (input: Signal): { re: number[]; im: number[] } => {
+  const re: number[] = [];
+  const im: number[] = [];
+  for (const x of input) {
+    if (x instanceof ComplexNumber) {
+      re.push(x.value);
+      im.push(x.iValue);
+    } else {
+      re.push(x);
+      im.push(0);
+    }
+  }
+  return { re, im };
+};
+
+const toComplex = (re: number[], im: number[]): ComplexNumber[] => re.map((r, i) => new ComplexNumber(r, im[i]));
+
+const isPowerOfTwo = (n: number): boolean => n > 0 && (n & (n - 1)) === 0;
+
+/** In-place iterative radix-2 Cooley-Tukey. `invert` runs the inverse transform. */
+function transform(re: number[], im: number[], invert: boolean): void {
+  const n = re.length;
+  // bit-reversal permutation
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = ((2 * Math.PI) / len) * (invert ? 1 : -1);
+    const wlenR = Math.cos(ang);
+    const wlenI = Math.sin(ang);
+    for (let i = 0; i < n; i += len) {
+      let wr = 1;
+      let wi = 0;
+      for (let j = 0; j < len / 2; j++) {
+        const uR = re[i + j];
+        const uI = im[i + j];
+        const vR = re[i + j + len / 2] * wr - im[i + j + len / 2] * wi;
+        const vI = re[i + j + len / 2] * wi + im[i + j + len / 2] * wr;
+        re[i + j] = uR + vR;
+        im[i + j] = uI + vI;
+        re[i + j + len / 2] = uR - vR;
+        im[i + j + len / 2] = uI - vI;
+        const nwr = wr * wlenR - wi * wlenI;
+        wi = wr * wlenI + wi * wlenR;
+        wr = nwr;
+      }
+    }
+  }
+  if (invert)
+    for (let i = 0; i < n; i++) {
+      re[i] /= n;
+      im[i] /= n;
+    }
+}
+
+export class FFT {
+  /** Fast Fourier transform (input length must be a power of two). */
+  static fft(input: Signal): ComplexNumber[] {
+    const { re, im } = toParts(input);
+    if (!isPowerOfTwo(re.length)) throw new Error("FFT input length must be a power of two (see fftPadded).");
+    transform(re, im, false);
+    return toComplex(re, im);
+  }
+
+  /** Inverse fast Fourier transform. */
+  static ifft(input: Signal): ComplexNumber[] {
+    const { re, im } = toParts(input);
+    if (!isPowerOfTwo(re.length)) throw new Error("IFFT input length must be a power of two.");
+    transform(re, im, true);
+    return toComplex(re, im);
+  }
+
+  /** FFT with the input zero-padded up to the next power of two. */
+  static fftPadded(input: Signal): ComplexNumber[] {
+    const { re, im } = toParts(input);
+    let n = 1;
+    while (n < re.length) n <<= 1;
+    while (re.length < n) {
+      re.push(0);
+      im.push(0);
+    }
+    transform(re, im, false);
+    return toComplex(re, im);
+  }
+
+  /** Direct O(n²) discrete Fourier transform for any length (reference implementation). */
+  static dft(input: Signal): ComplexNumber[] {
+    const { re, im } = toParts(input);
+    const n = re.length;
+    const out: ComplexNumber[] = [];
+    for (let k = 0; k < n; k++) {
+      let sumR = 0;
+      let sumI = 0;
+      for (let t = 0; t < n; t++) {
+        const ang = (-2 * Math.PI * k * t) / n;
+        sumR += re[t] * Math.cos(ang) - im[t] * Math.sin(ang);
+        sumI += re[t] * Math.sin(ang) + im[t] * Math.cos(ang);
+      }
+      out.push(new ComplexNumber(sumR, sumI));
+    }
+    return out;
+  }
+
+  /** Linear convolution of two real (or complex) signals, via the FFT. */
+  static convolve(a: Signal, b: Signal): ComplexNumber[] {
+    const resultLen = a.length + b.length - 1;
+    let n = 1;
+    while (n < resultLen) n <<= 1;
+    const pad = (s: Signal) => {
+      const { re, im } = toParts(s);
+      while (re.length < n) {
+        re.push(0);
+        im.push(0);
+      }
+      return { re, im };
+    };
+    const A = pad(a);
+    const B = pad(b);
+    transform(A.re, A.im, false);
+    transform(B.re, B.im, false);
+    const re = new Array(n);
+    const im = new Array(n);
+    for (let i = 0; i < n; i++) {
+      re[i] = A.re[i] * B.re[i] - A.im[i] * B.im[i];
+      im[i] = A.re[i] * B.im[i] + A.im[i] * B.re[i];
+    }
+    transform(re, im, true);
+    return toComplex(re.slice(0, resultLen), im.slice(0, resultLen));
+  }
+}

package/src/GeometricAlgebra4.ts

@@ -0,0 +1,157 @@
+/**
+ * GeometricAlgebra4 — the products that combine {@link Vec4} and
+ * {@link Bivector4} objects, mirroring how {@link ComplexMath} and
+ * {@link RealMath} hold the free-function operations for their respective
+ * types. {@link Rotor4} is built on top of these.
+ *
+ * Scope note: this module only implements the specific products the physics
+ * and rendering layers of a 4D engine actually need (vector·vector,
+ * vector∧vector, bivector*bivector, and the Hodge dual of a bivector) rather
+ * than a fully generic arbitrary-grade multivector type — Cl(4,0) has 16
+ * basis blades across grades 0–4, but rotors only ever touch grades 0, 2, 4,
+ * and nothing in this package needs grade-1 (vector) or grade-3 (trivector)
+ * results from a product.
+ */
+import { Bivector4 } from "./Bivector4.ts";
+import {
+  E1,
+  E2,
+  E3,
+  E4,
+  E12,
+  E13,
+  E14,
+  E23,
+  E24,
+  E34,
+  geometricProductMV,
+  type Multivector4,
+  mvZero,
+  PSEUDOSCALAR4,
+  wedgeProductMV,
+} from "./Clifford4Internal.ts";
+import { Vec4 } from "./Vec4.ts";
+
+function vecToMV(v: Vec4): Multivector4 {
+  const mv = mvZero();
+  mv[E1] = v.x;
+  mv[E2] = v.y;
+  mv[E3] = v.z;
+  mv[E4] = v.w;
+  return mv;
+}
+
+export function bivectorToMV(b: Bivector4): Multivector4 {
+  const mv = mvZero();
+  mv[E12] = b.xy;
+  mv[E13] = b.xz;
+  mv[E14] = b.xw;
+  mv[E23] = b.yz;
+  mv[E24] = b.yw;
+  mv[E34] = b.zw;
+  return mv;
+}
+
+export function bivectorFromMV(mv: Multivector4): Bivector4 {
+  return new Bivector4(
+    mv[E12] as number,
+    mv[E13] as number,
+    mv[E14] as number,
+    mv[E23] as number,
+    mv[E24] as number,
+    mv[E34] as number,
+  );
+}
+
+/** The Euclidean inner product `a · b` (a scalar). Equivalent to `a.dot(b)`. */
+export function dotProduct(a: Vec4, b: Vec4): number {
+  return a.dot(b);
+}
+
+/** The outer (wedge) product `a ∧ b` — the oriented 2-plane spanned by `a` and `b`. */
+export function wedgeProduct(a: Vec4, b: Vec4): Bivector4 {
+  return bivectorFromMV(wedgeProductMV(vecToMV(a), vecToMV(b)));
+}
+
+export interface VectorGeometricProduct {
+  readonly scalar: number;
+  readonly bivector: Bivector4;
+}
+
+/** The full geometric product `a * b = a·b + a∧b` of two vectors. */
+export function geometricProductVectors(a: Vec4, b: Vec4): VectorGeometricProduct {
+  const mv = geometricProductMV(vecToMV(a), vecToMV(b));
+  return { scalar: mv[0] as number, bivector: bivectorFromMV(mv) };
+}
+
+export interface BivectorGeometricProduct {
+  readonly scalar: number;
+  readonly bivector: Bivector4;
+  readonly pseudoscalar: number;
+}
+
+/**
+ * The full geometric product `A * B` of two bivectors: `⟨AB⟩₀ + ⟨AB⟩₂ + ⟨AB⟩₄`.
+ * This is the operation that makes 4D rotors an 8-component (1 + 6 + 1)
+ * object — the grade-4 (pseudoscalar) term has no 3D analogue, since in 3D
+ * the product of two bivectors never produces a grade-4 term (3D has no
+ * grade above 3). It's exactly this term that lets a 4D rotor encode a
+ * *double rotation*: simultaneous rotation in two independent orthogonal
+ * planes at once.
+ */
+export function geometricProductBivectors(a: Bivector4, b: Bivector4): BivectorGeometricProduct {
+  const mv = geometricProductMV(bivectorToMV(a), bivectorToMV(b));
+  return {
+    scalar: mv[0] as number,
+    bivector: bivectorFromMV(mv),
+    pseudoscalar: mv[PSEUDOSCALAR4] as number,
+  };
+}
+
+/**
+ * Hodge dual of a bivector in 4D: maps each basis 2-plane to its orthogonal
+ * complement 2-plane (e.g. `dual(e12) = ±e34`), scaled by the pseudoscalar.
+ * Unlike 3D (where the dual of a bivector is a vector), the 4D dual of a
+ * bivector is again a bivector — this is a 4D-specific fact worth remembering
+ * when porting 3D geometric intuition.
+ */
+export function dual(b: Bivector4): Bivector4 {
+  // Multiplying by the inverse pseudoscalar (I⁻¹ = -I in Cl(4,0), since
+  // I*I = +1... actually for Cl(4,0), I^2 = (e1e2e3e4)^2 = +1, so I⁻¹ = I)
+  // implements the Hodge dual via the geometric product with I.
+  const I = mvZero();
+  I[PSEUDOSCALAR4] = 1;
+  const mv = geometricProductMV(bivectorToMV(b), I);
+  return bivectorFromMV(mv);
+}
+
+/**
+ * The commutator product `A × B = ½(AB − BA)` of two bivectors -- distinct
+ * from {@link geometricProductBivectors}'s full `AB`. This is the operation
+ * n-dimensional rigid body dynamics needs for the generalized Euler's
+ * equation `L_t(ω) = I(ω_t) − ω × I(ω) = τ` (angular momentum, inertia
+ * tensor, and torque are all bivectors in 4D; this `×` is the commutator,
+ * not the 3D cross product it specializes to in 3D).
+ */
+export function commutatorProduct(a: Bivector4, b: Bivector4): Bivector4 {
+  const ab = geometricProductMV(bivectorToMV(a), bivectorToMV(b));
+  const ba = geometricProductMV(bivectorToMV(b), bivectorToMV(a));
+  const commutator = mvZero();
+  for (let i = 0; i < commutator.length; i++) commutator[i] = ((ab[i] as number) - (ba[i] as number)) / 2;
+  return bivectorFromMV(commutator);
+}
+
+/**
+ * The left contraction `v⌋B` of a vector into a bivector, producing a
+ * vector -- the grade-1 part of the geometric product `vB` (the geometric
+ * product of a grade-1 and a grade-2 element splits into grade 1 [this] and
+ * grade 3, and this package doesn't otherwise need grade-3/trivector
+ * results, so only the grade-1 part is extracted here). Needed for a rigid
+ * body's point velocity: `v_point = v + r⌋ω`, where `v` is linear velocity
+ * (Vec4), `ω` is angular velocity (Bivector4), and `r` is the point's offset
+ * from the body's center of mass.
+ */
+export function leftContraction(v: Vec4, b: Bivector4): Vec4 {
+  const mv = geometricProductMV(vecToMV(v), bivectorToMV(b));
+  return new Vec4(mv[E1] as number, mv[E2] as number, mv[E3] as number, mv[E4] as number);
+}

package/src/Geometry.ts

@@ -0,0 +1,173 @@
+/**
+ * Geometry — computational geometry on 2D points (`[x, y]` tuples): convex hull,
+ * orientation and intersection predicates, point-in-polygon, distances, polygon
+ * area/centroid, and 2D affine transforms via homogeneous matrices. Complements
+ * the {@link Polygon} class with lower-level, allocation-free primitives.
+ */
+
+export type Point = [number, number];
+
+export class Geometry {
+  /** The signed area of the triangle `(a, b, c)` (>0 CCW, <0 CW, 0 collinear). */
+  static orientation(a: Point, b: Point, c: Point): number {
+    return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+  }
+
+  static distance(a: Point, b: Point): number {
+    return Math.hypot(a[0] - b[0], a[1] - b[1]);
+  }
+
+  /** Distance from point `p` to the segment `a–b`. */
+  static distancePointToSegment(p: Point, a: Point, b: Point): number {
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    const len2 = dx * dx + dy * dy;
+    if (len2 === 0) return Geometry.distance(p, a);
+    let t = ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / len2;
+    t = Math.max(0, Math.min(1, t));
+    return Geometry.distance(p, [a[0] + t * dx, a[1] + t * dy]);
+  }
+
+  /** The convex hull (counter-clockwise) via Andrew's monotone chain. */
+  static convexHull(points: readonly Point[]): Point[] {
+    const pts = [...points].sort((p, q) => p[0] - q[0] || p[1] - q[1]);
+    if (pts.length <= 2) return pts;
+    const cross = (o: Point, a: Point, b: Point) => Geometry.orientation(o, a, b);
+
+    const lower: Point[] = [];
+    for (const p of pts) {
+      while (lower.length >= 2 && cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0) lower.pop();
+      lower.push(p);
+    }
+    const upper: Point[] = [];
+    for (let i = pts.length - 1; i >= 0; i--) {
+      const p = pts[i];
+      while (upper.length >= 2 && cross(upper[upper.length - 2], upper[upper.length - 1], p) <= 0) upper.pop();
+      upper.push(p);
+    }
+    lower.pop();
+    upper.pop();
+    return lower.concat(upper);
+  }
+
+  /** Whether segments `p1–p2` and `p3–p4` intersect (endpoints/collinear included). */
+  static segmentsIntersect(p1: Point, p2: Point, p3: Point, p4: Point): boolean {
+    const d1 = Geometry.orientation(p3, p4, p1);
+    const d2 = Geometry.orientation(p3, p4, p2);
+    const d3 = Geometry.orientation(p1, p2, p3);
+    const d4 = Geometry.orientation(p1, p2, p4);
+    const onSeg = (a: Point, b: Point, p: Point) =>
+      Math.min(a[0], b[0]) <= p[0] &&
+      p[0] <= Math.max(a[0], b[0]) &&
+      Math.min(a[1], b[1]) <= p[1] &&
+      p[1] <= Math.max(a[1], b[1]);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0))) return true;
+    if (d1 === 0 && onSeg(p3, p4, p1)) return true;
+    if (d2 === 0 && onSeg(p3, p4, p2)) return true;
+    if (d3 === 0 && onSeg(p1, p2, p3)) return true;
+    if (d4 === 0 && onSeg(p1, p2, p4)) return true;
+    return false;
+  }
+
+  /** The shoelace area of a polygon given by its vertices. */
+  static polygonArea(polygon: readonly Point[]): number {
+    let sum = 0;
+    for (let i = 0; i < polygon.length; i++) {
+      const a = polygon[i];
+      const b = polygon[(i + 1) % polygon.length];
+      sum += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(sum) / 2;
+  }
+
+  /** The centroid of a set of points (the simple average). */
+  static centroid(points: readonly Point[]): Point {
+    const n = points.length || 1;
+    let sx = 0;
+    let sy = 0;
+    for (const [x, y] of points) {
+      sx += x;
+      sy += y;
+    }
+    return [sx / n, sy / n];
+  }
+
+  /** Point-in-polygon by the even-odd ray-casting rule. */
+  static pointInPolygon(point: Point, polygon: readonly Point[]): boolean {
+    const [px, py] = point;
+    let inside = false;
+    const n = polygon.length;
+    for (let i = 0, j = n - 1; i < n; j = i++) {
+      const [xi, yi] = polygon[i];
+      const [xj, yj] = polygon[j];
+      if (yi > py !== yj > py && px < ((xj - xi) * (py - yi)) / (yj - yi) + xi) inside = !inside;
+    }
+    return inside;
+  }
+}
+
+/**
+ * Transform2D — 2D affine transforms as 3×3 homogeneous matrices. Compose them
+ * with {@link Transform2D.multiply} and apply them with {@link Transform2D.apply}.
+ */
+export class Transform2D {
+  readonly m: number[][];
+
+  constructor(m: number[][]) {
+    this.m = m;
+  }
+
+  static identity(): Transform2D {
+    return new Transform2D([
+      [1, 0, 0],
+      [0, 1, 0],
+      [0, 0, 1],
+    ]);
+  }
+
+  static translation(tx: number, ty: number): Transform2D {
+    return new Transform2D([
+      [1, 0, tx],
+      [0, 1, ty],
+      [0, 0, 1],
+    ]);
+  }
+
+  static scaling(sx: number, sy: number = sx): Transform2D {
+    return new Transform2D([
+      [sx, 0, 0],
+      [0, sy, 0],
+      [0, 0, 1],
+    ]);
+  }
+
+  static rotation(theta: number): Transform2D {
+    const c = Math.cos(theta);
+    const s = Math.sin(theta);
+    return new Transform2D([
+      [c, -s, 0],
+      [s, c, 0],
+      [0, 0, 1],
+    ]);
+  }
+
+  /** Matrix product `this · other` (apply `other` first, then `this`). */
+  multiply(other: Transform2D): Transform2D {
+    const a = this.m;
+    const b = other.m;
+    const out = [
+      [0, 0, 0],
+      [0, 0, 0],
+      [0, 0, 0],
+    ];
+    for (let i = 0; i < 3; i++) for (let j = 0; j < 3; j++) for (let k = 0; k < 3; k++) out[i][j] += a[i][k] * b[k][j];
+    return new Transform2D(out);
+  }
+
+  /** Apply the transform to a point. */
+  apply(p: Point): Point {
+    const [x, y] = p;
+    const m = this.m;
+    return [m[0][0] * x + m[0][1] * y + m[0][2], m[1][0] * x + m[1][1] * y + m[1][2]];
+  }
+}