@guinetik/gcanvas 1.0.0

package/src/math/noise.js

@@ -0,0 +1,433 @@
+/*
+ * A speed-improved perlin and simplex noise algorithms for 2D.
+ *
+ * Based on example code by Stefan Gustavson (stegu@itn.liu.se).
+ * Optimisations by Peter Eastman (peastman@drizzle.stanford.edu).
+ * Better rank ordering method by Stefan Gustavson in 2012.
+ * Converted to Javascript by Joseph Gentle.
+ *
+ * Version 2012-03-09
+ *
+ * This code was placed in the public domain by its original author,
+ * Stefan Gustavson. You may use it as you see fit, but
+ * attribution is appreciated.
+ *
+ * Updated to ES modules by [Guinetik] in 2025
+ */
+
+export class Noise {
+  // Internal helper class for gradient calculations
+  static #Grad = class {
+    constructor(x, y, z) {
+      this.x = x;
+      this.y = y;
+      this.z = z;
+    }
+
+    dot2(x, y) {
+      return this.x * x + this.y * y;
+    }
+
+    dot3(x, y, z) {
+      return this.x * x + this.y * y + this.z * z;
+    }
+  };
+
+  // Pre-computed gradients
+  static #grad3 = [
+    new this.#Grad(1, 1, 0),
+    new this.#Grad(-1, 1, 0),
+    new this.#Grad(1, -1, 0),
+    new this.#Grad(-1, -1, 0),
+    new this.#Grad(1, 0, 1),
+    new this.#Grad(-1, 0, 1),
+    new this.#Grad(1, 0, -1),
+    new this.#Grad(-1, 0, -1),
+    new this.#Grad(0, 1, 1),
+    new this.#Grad(0, -1, 1),
+    new this.#Grad(0, 1, -1),
+    new this.#Grad(0, -1, -1),
+  ];
+
+  // Permutation table
+  static #p = [
+    151, 160, 137, 91, 90, 15, 131, 13, 201, 95, 96, 53, 194, 233, 7, 225, 140,
+    36, 103, 30, 69, 142, 8, 99, 37, 240, 21, 10, 23, 190, 6, 148, 247, 120,
+    234, 75, 0, 26, 197, 62, 94, 252, 219, 203, 117, 35, 11, 32, 57, 177, 33,
+    88, 237, 149, 56, 87, 174, 20, 125, 136, 171, 168, 68, 175, 74, 165, 71,
+    134, 139, 48, 27, 166, 77, 146, 158, 231, 83, 111, 229, 122, 60, 211, 133,
+    230, 220, 105, 92, 41, 55, 46, 245, 40, 244, 102, 143, 54, 65, 25, 63, 161,
+    1, 216, 80, 73, 209, 76, 132, 187, 208, 89, 18, 169, 200, 196, 135, 130,
+    116, 188, 159, 86, 164, 100, 109, 198, 173, 186, 3, 64, 52, 217, 226, 250,
+    124, 123, 5, 202, 38, 147, 118, 126, 255, 82, 85, 212, 207, 206, 59, 227,
+    47, 16, 58, 17, 182, 189, 28, 42, 223, 183, 170, 213, 119, 248, 152, 2, 44,
+    154, 163, 70, 221, 153, 101, 155, 167, 43, 172, 9, 129, 22, 39, 253, 19, 98,
+    108, 110, 79, 113, 224, 232, 178, 185, 112, 104, 218, 246, 97, 228, 251, 34,
+    242, 193, 238, 210, 144, 12, 191, 179, 162, 241, 81, 51, 145, 235, 249, 14,
+    239, 107, 49, 192, 214, 31, 181, 199, 106, 157, 184, 84, 204, 176, 115, 121,
+    50, 45, 127, 4, 150, 254, 138, 236, 205, 93, 222, 114, 67, 29, 24, 72, 243,
+    141, 128, 195, 78, 66, 215, 61, 156, 180,
+  ];
+
+  // To remove the need for index wrapping, double the permutation table length
+  static #perm = new Array(512);
+  static #gradP = new Array(512);
+
+  // Skewing and unskewing factors
+  static #F2 = 0.5 * (Math.sqrt(3) - 1);
+  static #G2 = (3 - Math.sqrt(3)) / 6;
+
+  static #F3 = 1 / 3;
+  static #G3 = 1 / 6;
+
+  // Helper functions
+  static #fade(t) {
+    return t * t * t * (t * (t * 6 - 15) + 10);
+  }
+
+  static #lerp(a, b, t) {
+    return (1 - t) * a + t * b;
+  }
+
+  // Initialize with default seed
+  static {
+    this.seed(0);
+  }
+
+  /**
+   * Seed the noise function
+   * @param {number} seed - A seed value between 0 and 65535
+   */
+  static seed(seed) {
+    if (seed > 0 && seed < 1) {
+      // Scale the seed out
+      seed *= 65536;
+    }
+
+    seed = Math.floor(seed);
+    if (seed < 256) {
+      seed |= seed << 8;
+    }
+
+    for (let i = 0; i < 256; i++) {
+      let v;
+      if (i & 1) {
+        v = this.#p[i] ^ (seed & 255);
+      } else {
+        v = this.#p[i] ^ ((seed >> 8) & 255);
+      }
+
+      this.#perm[i] = this.#perm[i + 256] = v;
+      this.#gradP[i] = this.#gradP[i + 256] = this.#grad3[v % 12];
+    }
+  }
+
+  /**
+   * 2D simplex noise
+   * @param {number} xin - X coordinate
+   * @param {number} yin - Y coordinate
+   * @returns {number} Noise value in range [-1, 1]
+   */
+  static simplex2(xin, yin) {
+    let n0, n1, n2; // Noise contributions from the three corners
+    // Skew the input space to determine which simplex cell we're in
+    const s = (xin + yin) * this.#F2; // Hairy factor for 2D
+    const i = Math.floor(xin + s);
+    const j = Math.floor(yin + s);
+    const t = (i + j) * this.#G2;
+    const x0 = xin - i + t; // The x,y distances from the cell origin, unskewed.
+    const y0 = yin - j + t;
+    // For the 2D case, the simplex shape is an equilateral triangle.
+    // Determine which simplex we are in.
+    let i1, j1; // Offsets for second (middle) corner of simplex in (i,j) coords
+    if (x0 > y0) {
+      // lower triangle, XY order: (0,0)->(1,0)->(1,1)
+      i1 = 1;
+      j1 = 0;
+    } else {
+      // upper triangle, YX order: (0,0)->(0,1)->(1,1)
+      i1 = 0;
+      j1 = 1;
+    }
+    // A step of (1,0) in (i,j) means a step of (1-c,-c) in (x,y), and
+    // a step of (0,1) in (i,j) means a step of (-c,1-c) in (x,y), where
+    // c = (3-sqrt(3))/6
+    const x1 = x0 - i1 + this.#G2; // Offsets for middle corner in (x,y) unskewed coords
+    const y1 = y0 - j1 + this.#G2;
+    const x2 = x0 - 1 + 2 * this.#G2; // Offsets for last corner in (x,y) unskewed coords
+    const y2 = y0 - 1 + 2 * this.#G2;
+    // Work out the hashed gradient indices of the three simplex corners
+    const ii = i & 255;
+    const jj = j & 255;
+    const gi0 = this.#gradP[ii + this.#perm[jj]];
+    const gi1 = this.#gradP[ii + i1 + this.#perm[jj + j1]];
+    const gi2 = this.#gradP[ii + 1 + this.#perm[jj + 1]];
+    // Calculate the contribution from the three corners
+    let t0 = 0.5 - x0 * x0 - y0 * y0;
+    if (t0 < 0) {
+      n0 = 0;
+    } else {
+      t0 *= t0;
+      n0 = t0 * t0 * gi0.dot2(x0, y0); // (x,y) of grad3 used for 2D gradient
+    }
+    let t1 = 0.5 - x1 * x1 - y1 * y1;
+    if (t1 < 0) {
+      n1 = 0;
+    } else {
+      t1 *= t1;
+      n1 = t1 * t1 * gi1.dot2(x1, y1);
+    }
+    let t2 = 0.5 - x2 * x2 - y2 * y2;
+    if (t2 < 0) {
+      n2 = 0;
+    } else {
+      t2 *= t2;
+      n2 = t2 * t2 * gi2.dot2(x2, y2);
+    }
+    // Add contributions from each corner to get the final noise value.
+    // The result is scaled to return values in the interval [-1,1].
+    return 70 * (n0 + n1 + n2);
+  }
+
+  /**
+   * 3D simplex noise
+   * @param {number} xin - X coordinate
+   * @param {number} yin - Y coordinate
+   * @param {number} zin - Z coordinate
+   * @returns {number} Noise value in range [-1, 1]
+   */
+  static simplex3(xin, yin, zin) {
+    let n0, n1, n2, n3; // Noise contributions from the four corners
+
+    // Skew the input space to determine which simplex cell we're in
+    const s = (xin + yin + zin) * this.#F3; // Hairy factor for 2D
+    const i = Math.floor(xin + s);
+    const j = Math.floor(yin + s);
+    const k = Math.floor(zin + s);
+
+    const t = (i + j + k) * this.#G3;
+    const x0 = xin - i + t; // The x,y distances from the cell origin, unskewed.
+    const y0 = yin - j + t;
+    const z0 = zin - k + t;
+
+    // For the 3D case, the simplex shape is a slightly irregular tetrahedron.
+    // Determine which simplex we are in.
+    let i1, j1, k1; // Offsets for second corner of simplex in (i,j,k) coords
+    let i2, j2, k2; // Offsets for third corner of simplex in (i,j,k) coords
+    if (x0 >= y0) {
+      if (y0 >= z0) {
+        i1 = 1;
+        j1 = 0;
+        k1 = 0;
+        i2 = 1;
+        j2 = 1;
+        k2 = 0;
+      } else if (x0 >= z0) {
+        i1 = 1;
+        j1 = 0;
+        k1 = 0;
+        i2 = 1;
+        j2 = 0;
+        k2 = 1;
+      } else {
+        i1 = 0;
+        j1 = 0;
+        k1 = 1;
+        i2 = 1;
+        j2 = 0;
+        k2 = 1;
+      }
+    } else {
+      if (y0 < z0) {
+        i1 = 0;
+        j1 = 0;
+        k1 = 1;
+        i2 = 0;
+        j2 = 1;
+        k2 = 1;
+      } else if (x0 < z0) {
+        i1 = 0;
+        j1 = 1;
+        k1 = 0;
+        i2 = 0;
+        j2 = 1;
+        k2 = 1;
+      } else {
+        i1 = 0;
+        j1 = 1;
+        k1 = 0;
+        i2 = 1;
+        j2 = 1;
+        k2 = 0;
+      }
+    }
+
+    // A step of (1,0,0) in (i,j,k) means a step of (1-c,-c,-c) in (x,y,z),
+    // a step of (0,1,0) in (i,j,k) means a step of (-c,1-c,-c) in (x,y,z), and
+    // a step of (0,0,1) in (i,j,k) means a step of (-c,-c,1-c) in (x,y,z), where
+    // c = 1/6.
+    const x1 = x0 - i1 + this.#G3; // Offsets for second corner
+    const y1 = y0 - j1 + this.#G3;
+    const z1 = z0 - k1 + this.#G3;
+
+    const x2 = x0 - i2 + 2 * this.#G3; // Offsets for third corner
+    const y2 = y0 - j2 + 2 * this.#G3;
+    const z2 = z0 - k2 + 2 * this.#G3;
+
+    const x3 = x0 - 1 + 3 * this.#G3; // Offsets for fourth corner
+    const y3 = y0 - 1 + 3 * this.#G3;
+    const z3 = z0 - 1 + 3 * this.#G3;
+
+    // Work out the hashed gradient indices of the four simplex corners
+    const ii = i & 255;
+    const jj = j & 255;
+    const kk = k & 255;
+    const gi0 = this.#gradP[ii + this.#perm[jj + this.#perm[kk]]];
+    const gi1 =
+      this.#gradP[ii + i1 + this.#perm[jj + j1 + this.#perm[kk + k1]]];
+    const gi2 =
+      this.#gradP[ii + i2 + this.#perm[jj + j2 + this.#perm[kk + k2]]];
+    const gi3 = this.#gradP[ii + 1 + this.#perm[jj + 1 + this.#perm[kk + 1]]];
+
+    // Calculate the contribution from the four corners
+    let t0 = 0.6 - x0 * x0 - y0 * y0 - z0 * z0;
+    if (t0 < 0) {
+      n0 = 0;
+    } else {
+      t0 *= t0;
+      n0 = t0 * t0 * gi0.dot3(x0, y0, z0); // (x,y) of grad3 used for 2D gradient
+    }
+    let t1 = 0.6 - x1 * x1 - y1 * y1 - z1 * z1;
+    if (t1 < 0) {
+      n1 = 0;
+    } else {
+      t1 *= t1;
+      n1 = t1 * t1 * gi1.dot3(x1, y1, z1);
+    }
+    let t2 = 0.6 - x2 * x2 - y2 * y2 - z2 * z2;
+    if (t2 < 0) {
+      n2 = 0;
+    } else {
+      t2 *= t2;
+      n2 = t2 * t2 * gi2.dot3(x2, y2, z2);
+    }
+    let t3 = 0.6 - x3 * x3 - y3 * y3 - z3 * z3;
+    if (t3 < 0) {
+      n3 = 0;
+    } else {
+      t3 *= t3;
+      n3 = t3 * t3 * gi3.dot3(x3, y3, z3);
+    }
+    // Add contributions from each corner to get the final noise value.
+    // The result is scaled to return values in the interval [-1,1].
+    return 32 * (n0 + n1 + n2 + n3);
+  }
+
+  /**
+   * 2D Perlin Noise
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @returns {number} Noise value in range [-1, 1]
+   */
+  static perlin2(x, y) {
+    // Find unit grid cell containing point
+    const X = Math.floor(x),
+      Y = Math.floor(y);
+    // Get relative xy coordinates of point within that cell
+    x = x - X;
+    y = y - Y;
+    // Wrap the integer cells at 255 (smaller integer period can be introduced here)
+    const XX = X & 255,
+      YY = Y & 255;
+
+    // Calculate noise contributions from each of the four corners
+    const n00 = this.#gradP[XX + this.#perm[YY]].dot2(x, y);
+    const n01 = this.#gradP[XX + this.#perm[YY + 1]].dot2(x, y - 1);
+    const n10 = this.#gradP[XX + 1 + this.#perm[YY]].dot2(x - 1, y);
+    const n11 = this.#gradP[XX + 1 + this.#perm[YY + 1]].dot2(x - 1, y - 1);
+
+    // Compute the fade curve value for x
+    const u = this.#fade(x);
+
+    // Interpolate the four results
+    return this.#lerp(
+      this.#lerp(n00, n10, u),
+      this.#lerp(n01, n11, u),
+      this.#fade(y)
+    );
+  }
+
+  /**
+   * 3D Perlin Noise
+   * @param {number} x - X coordinate
+   * @param {number} y - Y coordinate
+   * @param {number} z - Z coordinate
+   * @returns {number} Noise value in range [-1, 1]
+   */
+  static perlin3(x, y, z) {
+    // Find unit grid cell containing point
+    const X = Math.floor(x),
+      Y = Math.floor(y),
+      Z = Math.floor(z);
+    // Get relative xyz coordinates of point within that cell
+    x = x - X;
+    y = y - Y;
+    z = z - Z;
+    // Wrap the integer cells at 255 (smaller integer period can be introduced here)
+    const XX = X & 255,
+      YY = Y & 255,
+      ZZ = Z & 255;
+
+    // Calculate noise contributions from each of the eight corners
+    const n000 = this.#gradP[XX + this.#perm[YY + this.#perm[ZZ]]].dot3(
+      x,
+      y,
+      z
+    );
+    const n001 = this.#gradP[XX + this.#perm[YY + this.#perm[ZZ + 1]]].dot3(
+      x,
+      y,
+      z - 1
+    );
+    const n010 = this.#gradP[XX + this.#perm[YY + 1 + this.#perm[ZZ]]].dot3(
+      x,
+      y - 1,
+      z
+    );
+    const n011 = this.#gradP[XX + this.#perm[YY + 1 + this.#perm[ZZ + 1]]].dot3(
+      x,
+      y - 1,
+      z - 1
+    );
+    const n100 = this.#gradP[XX + 1 + this.#perm[YY + this.#perm[ZZ]]].dot3(
+      x - 1,
+      y,
+      z
+    );
+    const n101 = this.#gradP[XX + 1 + this.#perm[YY + this.#perm[ZZ + 1]]].dot3(
+      x - 1,
+      y,
+      z - 1
+    );
+    const n110 = this.#gradP[XX + 1 + this.#perm[YY + 1 + this.#perm[ZZ]]].dot3(
+      x - 1,
+      y - 1,
+      z
+    );
+    const n111 = this.#gradP[
+      XX + 1 + this.#perm[YY + 1 + this.#perm[ZZ + 1]]
+    ].dot3(x - 1, y - 1, z - 1);
+
+    // Compute the fade curve value for x, y, z
+    const u = this.#fade(x);
+    const v = this.#fade(y);
+    const w = this.#fade(z);
+
+    // Interpolate
+    return this.#lerp(
+      this.#lerp(this.#lerp(n000, n100, u), this.#lerp(n001, n101, u), w),
+      this.#lerp(this.#lerp(n010, n110, u), this.#lerp(n011, n111, u), w),
+      v
+    );
+  }
+}

package/src/math/orbital.js

@@ -0,0 +1,191 @@
+/**
+ * Orbital mechanics utilities for geodesic motion visualization.
+ * Provides functions for Keplerian motion and GR corrections.
+ *
+ * All functions are pure - can be refactored to a class later if needed.
+ *
+ * @example
+ * import { keplerianOmega, schwarzschildPrecessionRate } from './orbital.js';
+ *
+ * // Base angular velocity
+ * const omega = keplerianOmega(10, 1, 0.5);
+ *
+ * // GR precession correction
+ * const precession = schwarzschildPrecessionRate(10, 2, 0.15);
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ANGULAR VELOCITY
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Keplerian angular velocity based on Kepler's 3rd law.
+ *
+ * omega ∝ sqrt(M) / r^(3/2)
+ *
+ * The referenceR parameter allows scaling for visualization - objects at
+ * r = referenceR will have angular velocity = speedFactor * sqrt(M).
+ *
+ * @param {number} r - Orbital radius
+ * @param {number} M - Central mass (geometrized units)
+ * @param {number} [speedFactor=1] - Speed multiplier for visualization
+ * @param {number} [referenceR=5] - Reference radius for scaling
+ * @returns {number} Angular velocity omega
+ */
+export function keplerianOmega(r, M, speedFactor = 1, referenceR = 5) {
+  if (r <= 0) return 0;
+  return (speedFactor * Math.sqrt(M)) / Math.pow(r / referenceR, 1.5);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GR PRECESSION RATES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * GR orbital precession rate for Schwarzschild spacetime.
+ *
+ * In GR, orbits don't close - they precess. The rate scales as rs/r,
+ * meaning closer orbits precess faster.
+ *
+ * The exact formula is Δφ ≈ 6πM/a(1-e²) per orbit, but for visualization
+ * we use a simpler form that captures the essential 1/r dependence.
+ *
+ * @param {number} r - Orbital radius
+ * @param {number} rs - Schwarzschild radius (2M)
+ * @param {number} [factor=1] - Precession rate multiplier
+ * @returns {number} Precession rate (multiply by dt for angle change)
+ */
+export function schwarzschildPrecessionRate(r, rs, factor = 1) {
+  if (r <= rs) return 0;
+  return factor * (rs / r);
+}
+
+/**
+ * GR orbital precession rate for Kerr spacetime.
+ *
+ * Includes additional contribution from frame dragging.
+ * Prograde orbits precess faster than in Schwarzschild.
+ *
+ * @param {number} r - Orbital radius
+ * @param {number} M - Mass parameter
+ * @param {number} a - Spin parameter (0 to M)
+ * @param {number} [factor=1] - Precession rate multiplier
+ * @returns {number} Precession rate
+ */
+export function kerrPrecessionRate(r, M, a, factor = 1) {
+  const rs = 2 * M;
+  if (r <= rs) return 0;
+  // Base Schwarzschild precession + frame dragging enhancement
+  return factor * (rs / r) * (1 + a / M);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ORBITAL GEOMETRY
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Compute orbital radius with eccentricity (Keplerian ellipse).
+ *
+ * r(φ) = a(1 - e²) / (1 + e*cos(φ))
+ *
+ * For small eccentricity, this simplifies to approximately:
+ * r ≈ a + a*e*sin(φ) (used in demos for smooth oscillation)
+ *
+ * @param {number} semiMajor - Semi-major axis a
+ * @param {number} eccentricity - Orbital eccentricity e (0 to 1)
+ * @param {number} phi - True anomaly (orbital angle)
+ * @returns {number} Orbital radius at angle phi
+ */
+export function orbitalRadius(semiMajor, eccentricity, phi) {
+  if (eccentricity >= 1) return semiMajor;
+  const p = semiMajor * (1 - eccentricity * eccentricity);
+  return p / (1 + eccentricity * Math.cos(phi));
+}
+
+/**
+ * Simplified radial oscillation for small eccentricity.
+ * More visually smooth than true Keplerian ellipse.
+ *
+ * @param {number} semiMajor - Base orbital radius
+ * @param {number} eccentricity - Eccentricity (small values)
+ * @param {number} phi - Orbital angle
+ * @param {number} [amplitudeFactor=2] - Oscillation amplitude multiplier
+ * @returns {number} Orbital radius
+ */
+export function orbitalRadiusSimple(semiMajor, eccentricity, phi, amplitudeFactor = 2) {
+  const oscillation = eccentricity * Math.sin(phi * 2);
+  return semiMajor + oscillation * amplitudeFactor;
+}
+
+/**
+ * Decaying orbital radius.
+ * Applies a decay factor to the orbital radius over time/angle.
+ *
+ * @param {number} r0 - Initial orbital radius
+ * @param {number} decayFactor - How fast the orbit decays (0 to 1)
+ * @param {number} t - Time or progress factor
+ * @returns {number} Decayed radius
+ */
+export function decayingOrbitalRadius(r0, decayFactor, t) {
+  return r0 * Math.exp(-decayFactor * t);
+}
+
+/**
+ * Computes a terminal trajectory (direct fall).
+ * Interpolates between a starting point and the center (0,0,0).
+ *
+ * @param {number} startX - Start X
+ * @param {number} startY - Start Y
+ * @param {number} startZ - Start Z
+ * @param {number} progress - Progress (0 to 1)
+ * @param {Function} easingFn - Optional easing function
+ * @returns {Object} Position { x, y, z }
+ */
+export function getTerminalTrajectory(startX, startY, startZ, progress, easingFn = null) {
+  const t = easingFn ? easingFn(progress) : progress;
+  return {
+    x: startX * (1 - t),
+    y: startY * (1 - t),
+    z: startZ * (1 - t),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TRAIL MANAGEMENT
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Add a point to an orbital trail array, maintaining max length.
+ *
+ * Points are added at the front (newest first) for efficient rendering
+ * of fading trails.
+ *
+ * @param {Array} trail - Trail array (modified in place)
+ * @param {Object} point - Point to add { x, z, r, ... }
+ * @param {number} [maxLength=80] - Maximum trail length
+ * @returns {Array} The modified trail array
+ */
+export function updateTrail(trail, point, maxLength = 80) {
+  trail.unshift(point);
+  if (trail.length > maxLength) {
+    trail.pop();
+  }
+  return trail;
+}
+
+/**
+ * Create a trail point from orbital state.
+ *
+ * @param {number} r - Orbital radius
+ * @param {number} phi - Orbital angle (including precession)
+ * @param {Object} [extra={}] - Additional data to include
+ * @returns {Object} Trail point { x, z, r, ...extra }
+ */
+export function createTrailPoint(r, phi, extra = {}) {
+  return {
+    x: Math.cos(phi) * r,
+    z: Math.sin(phi) * r,
+    r,
+    ...extra,
+  };
+}