@guinetik/gcanvas 1.0.0

package/src/math/gr.js

@@ -0,0 +1,201 @@
+/**
+ * General Relativity utilities for spacetime visualization.
+ * Complements the Tensor class with higher-level embedding and coordinate functions.
+ *
+ * @example
+ * import { flammEmbedding, flammEmbeddingHeight } from './gr.js';
+ *
+ * // Raw Flamm's paraboloid height
+ * const z = flammEmbedding(10, 2, 1); // r=10, rs=2, M=1
+ *
+ * // Inverted for visualization (well goes "down")
+ * const height = flammEmbeddingHeight(10, 2, 1, 20, 25);
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EMBEDDING FUNCTIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Flamm's paraboloid embedding for Schwarzschild/Kerr spacetime.
+ *
+ * The formula z = sqrt(8M(r - r_horizon)) gives the proper embedding
+ * of the spatial geometry into 3D Euclidean space.
+ *
+ * @param {number} r - Radial coordinate
+ * @param {number} rHorizon - Event horizon radius (rs for Schwarzschild, r+ for Kerr)
+ * @param {number} M - Mass parameter (in geometrized units G=c=1)
+ * @returns {number} Embedding height z (positive)
+ */
+export function flammEmbedding(r, rHorizon, M) {
+  if (r <= rHorizon) return 0;
+  return Math.sqrt(8 * M * (r - rHorizon));
+}
+
+/**
+ * Inverted embedding height for visualization.
+ *
+ * Returns a height value where:
+ * - Far from the black hole: height approaches 0 (flat)
+ * - Near the horizon: height increases (deep well)
+ *
+ * This is what you typically want for rendering the "gravity well" visualization.
+ *
+ * @param {number} r - Radial coordinate
+ * @param {number} rHorizon - Event horizon radius
+ * @param {number} M - Mass parameter
+ * @param {number} rMax - Maximum radius for normalization (typically grid size)
+ * @param {number} scale - Visual scale factor for the well depth
+ * @returns {number} Height value for rendering (larger = deeper in well)
+ */
+export function flammEmbeddingHeight(r, rHorizon, M, rMax, scale) {
+  // Clamp to just outside horizon
+  const rClamped = Math.max(r, rHorizon + 0.01);
+
+  // Flamm's paraboloid: z = sqrt(8M(r - r_horizon))
+  const z = flammEmbedding(rClamped, rHorizon, M);
+  const zMax = flammEmbedding(rMax, rHorizon, M);
+
+  // Invert so well goes "down", normalize by zMax
+  // This gives proper curvature behavior: steep near horizon, flat far away
+  return ((zMax - z) * scale) / zMax;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// COORDINATE TRANSFORMATIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Convert Cartesian coordinates to spherical coordinates.
+ *
+ * @param {number} x - Cartesian x
+ * @param {number} y - Cartesian y
+ * @param {number} z - Cartesian z
+ * @returns {{ r: number, theta: number, phi: number }} Spherical coordinates
+ */
+export function cartesianToSpherical(x, y, z) {
+  const r = Math.sqrt(x * x + y * y + z * z);
+  const theta = r > 0 ? Math.acos(z / r) : 0;
+  const phi = Math.atan2(y, x);
+  return { r, theta, phi };
+}
+
+/**
+ * Convert spherical coordinates to Cartesian coordinates.
+ *
+ * @param {number} r - Radial distance
+ * @param {number} theta - Polar angle (0 to π)
+ * @param {number} phi - Azimuthal angle (0 to 2π)
+ * @returns {{ x: number, y: number, z: number }} Cartesian coordinates
+ */
+export function sphericalToCartesian(r, theta, phi) {
+  const sinTheta = Math.sin(theta);
+  return {
+    x: r * sinTheta * Math.cos(phi),
+    y: r * sinTheta * Math.sin(phi),
+    z: r * Math.cos(theta),
+  };
+}
+
+/**
+ * Convert polar coordinates (r, phi) to Cartesian (x, z) in the equatorial plane.
+ * Commonly used for orbital visualization where y is the "height" axis.
+ *
+ * @param {number} r - Radial distance
+ * @param {number} phi - Azimuthal angle
+ * @returns {{ x: number, z: number }} Cartesian coordinates in equatorial plane
+ */
+export function polarToCartesian(r, phi) {
+  return {
+    x: r * Math.cos(phi),
+    z: r * Math.sin(phi),
+  };
+}
+
+/**
+ * Convert Cartesian (x, z) to polar (r, phi) in the equatorial plane.
+ *
+ * @param {number} x - Cartesian x
+ * @param {number} z - Cartesian z
+ * @returns {{ r: number, phi: number }} Polar coordinates
+ */
+export function cartesianToPolar(x, z) {
+  return {
+    r: Math.sqrt(x * x + z * z),
+    phi: Math.atan2(z, x),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GRAVITATIONAL LENSING
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Calculate gravitational lensing displacement for a point near a massive object.
+ *
+ * Light passing near a massive object is deflected, causing background objects
+ * to appear displaced radially outward from the lens center. This creates the
+ * "Einstein ring" effect where objects directly behind the lens form a ring.
+ *
+ * This is a simplified screen-space approximation suitable for real-time rendering.
+ * True lensing would require ray-tracing through curved spacetime.
+ *
+ * @param {number} screenDist - Distance from lens center in screen pixels
+ * @param {number} effectRadius - Maximum radius of lensing effect in pixels
+ * @param {number} strength - Displacement strength (higher = more dramatic)
+ * @param {number} falloff - Exponential falloff rate (higher = tighter effect)
+ * @param {number} minDist - Minimum distance to apply lensing (avoids singularity)
+ * @returns {number} Radial displacement in pixels (0 if outside effect radius)
+ *
+ * @example
+ * // Calculate displacement for a star 100px from black hole center
+ * const displacement = gravitationalLensing(100, 500, 200, 0.008, 5);
+ * // Apply: newRadius = screenDist + displacement
+ */
+export function gravitationalLensing(screenDist, effectRadius, strength, falloff, minDist = 5) {
+  if (screenDist <= minDist || screenDist >= effectRadius) {
+    return 0;
+  }
+
+  // Exponential falloff: stronger closer to lens center
+  const lensFactor = Math.exp(-screenDist * falloff);
+
+  return lensFactor * strength;
+}
+
+/**
+ * Apply gravitational lensing to screen coordinates.
+ *
+ * Takes a point's screen position (relative to lens center) and returns
+ * the displaced position after lensing.
+ *
+ * @param {number} x - X coordinate relative to lens center
+ * @param {number} y - Y coordinate relative to lens center
+ * @param {number} effectRadius - Maximum radius of lensing effect
+ * @param {number} strength - Displacement strength
+ * @param {number} falloff - Exponential falloff rate
+ * @param {number} minDist - Minimum distance for lensing
+ * @returns {{ x: number, y: number, displacement: number }} Displaced coordinates and displacement amount
+ *
+ * @example
+ * const result = applyGravitationalLensing(50, 30, 500, 200, 0.008);
+ * ctx.drawImage(star, centerX + result.x, centerY + result.y, ...);
+ */
+export function applyGravitationalLensing(x, y, effectRadius, strength, falloff, minDist = 5) {
+  const dist = Math.sqrt(x * x + y * y);
+
+  if (dist <= minDist || dist >= effectRadius) {
+    return { x, y, displacement: 0 };
+  }
+
+  const displacement = gravitationalLensing(dist, effectRadius, strength, falloff, minDist);
+
+  // Radial displacement: push point outward from center
+  const ratio = (dist + displacement) / dist;
+
+  return {
+    x: x * ratio,
+    y: y * ratio,
+    displacement
+  };
+}

package/src/math/heat.js

@@ -0,0 +1,202 @@
+/**
+ * Heat Dynamics Module
+ *
+ * Particle-based heat physics functions for simulating thermal behavior:
+ * - Zone-based temperature changes (heating/cooling regions)
+ * - Buoyancy forces from temperature differentials
+ * - Heat transfer between particles
+ *
+ * Designed for lava lamp, fluid simulations, and particle systems.
+ *
+ * @see Easing.smoothstep, Easing.lerp in src/motion/easing.js for interpolation utilities
+ */
+
+import { Easing } from "../motion/easing.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TEMPERATURE FUNCTIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Attempt ot use this as smoothstep with edge parameters (wrapper for Easing.smoothstep).
+ * @private
+ */
+function smoothstep(edge0, edge1, x) {
+  const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
+  return Easing.smoothstep(t);
+}
+
+/**
+ * Calculate temperature change based on position in thermal zones.
+ * Uses smooth transitions between zones instead of hard boundaries.
+ *
+ * Zone layout (normalized y: 0 = top, 1 = bottom):
+ * - Cool zone: y < coolZone (temperature approaches 0)
+ * - Middle zone: between coolZone and heatZone (temperature approaches y position)
+ * - Heat zone: y > heatZone (temperature approaches 1)
+ *
+ * @param {number} position - Normalized position [0, 1] (typically y coordinate)
+ * @param {number} currentTemp - Current temperature [0, 1]
+ * @param {Object} config - Zone configuration
+ * @param {number} config.heatZone - Y position where heating begins (e.g., 0.92)
+ * @param {number} config.coolZone - Y position where cooling begins (e.g., 0.2)
+ * @param {number} config.rate - Base temperature change rate
+ * @param {number} [config.heatMultiplier=1.5] - Heating rate multiplier
+ * @param {number} [config.coolMultiplier=1.5] - Cooling rate multiplier
+ * @param {number} [config.middleMultiplier=0.05] - Middle zone rate multiplier
+ * @param {number} [config.transitionWidth=0.1] - Width of smooth transition zones
+ * @returns {number} New temperature value [0, 1]
+ *
+ * @example
+ * const temp = zoneTemperature(0.95, 0.5, {
+ *   heatZone: 0.92, coolZone: 0.2, rate: 0.0055
+ * });
+ */
+export function zoneTemperature(position, currentTemp, config) {
+  const {
+    heatZone,
+    coolZone,
+    rate,
+    heatMultiplier = 1.5,
+    coolMultiplier = 1.5,
+    middleMultiplier = 0.05,
+    transitionWidth = 0.1,
+  } = config;
+
+  // Calculate zone influence using smoothstep for soft transitions
+  // Heat zone influence: ramps up as position exceeds heatZone
+  const heatInfluence = smoothstep(heatZone - transitionWidth, heatZone + transitionWidth * 0.5, position);
+
+  // Cool zone influence: ramps up as position goes below coolZone
+  const coolInfluence = 1 - smoothstep(coolZone - transitionWidth * 0.5, coolZone + transitionWidth, position);
+
+  // Middle zone is whatever's left
+  const middleInfluence = 1 - heatInfluence - coolInfluence;
+
+  // Calculate target temperatures and rates for each zone
+  let deltaTemp = 0;
+
+  // Heat zone: temperature approaches 1.0
+  if (heatInfluence > 0) {
+    deltaTemp += (1.0 - currentTemp) * rate * heatMultiplier * heatInfluence;
+  }
+
+  // Cool zone: temperature approaches 0.0
+  if (coolInfluence > 0) {
+    deltaTemp += (0.0 - currentTemp) * rate * coolMultiplier * coolInfluence;
+  }
+
+  // Middle zone: temperature approaches position (linear gradient)
+  if (middleInfluence > 0) {
+    deltaTemp += (position - currentTemp) * rate * middleMultiplier * middleInfluence;
+  }
+
+  // Apply and clamp
+  return Math.max(0, Math.min(1, currentTemp + deltaTemp));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BUOYANCY FUNCTIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Calculate buoyancy force from temperature differential.
+ * Hot particles rise (negative velocity), cold particles sink (positive velocity).
+ *
+ * Based on simplified Archimedes principle where temperature acts as
+ * inverse density: hotter = less dense = more buoyant.
+ *
+ * @param {number} temperature - Particle temperature [0, 1]
+ * @param {number} neutralTemp - Temperature at which buoyancy is zero (typically 0.5)
+ * @param {number} strength - Buoyancy force strength coefficient
+ * @returns {number} Velocity adjustment (negative = rise, positive = sink)
+ *
+ * @example
+ * // Hot particle rises
+ * const lift = thermalBuoyancy(0.9, 0.5, 0.00018); // negative value
+ * particle.vy -= lift; // subtracting negative = rising
+ *
+ * // Cold particle sinks
+ * const sink = thermalBuoyancy(0.2, 0.5, 0.00018); // positive value
+ */
+export function thermalBuoyancy(temperature, neutralTemp, strength) {
+  return (temperature - neutralTemp) * strength;
+}
+
+/**
+ * Calculate weight-adjusted gravity force.
+ * Larger particles experience more gravitational pull.
+ *
+ * @param {number} radius - Particle radius
+ * @param {number} baseRadius - Reference radius for weight = 1
+ * @param {number} gravity - Base gravity coefficient
+ * @returns {number} Gravity force to add to vertical velocity
+ *
+ * @example
+ * const weight = thermalGravity(0.06, 0.04, 0.000052);
+ * particle.vy += weight;
+ */
+export function thermalGravity(radius, baseRadius, gravity) {
+  const weight = radius / baseRadius;
+  return gravity * weight;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HEAT TRANSFER FUNCTIONS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Calculate heat transfer between two particles.
+ * Uses Newton's law of cooling: heat flows from hot to cold proportionally
+ * to the temperature difference.
+ *
+ * @param {number} temp1 - Temperature of first particle [0, 1]
+ * @param {number} temp2 - Temperature of second particle [0, 1]
+ * @param {number} distance - Distance between particle centers
+ * @param {number} maxDistance - Maximum distance for heat transfer
+ * @param {number} rate - Heat transfer rate coefficient
+ * @returns {number} Temperature change for particle 1 (add to temp1)
+ *
+ * @example
+ * const dist = Math.sqrt(dx*dx + dy*dy);
+ * const maxDist = (blob1.r + blob2.r) * 1.5;
+ * const delta = heatTransfer(blob1.temp, blob2.temp, dist, maxDist, 0.0022);
+ * blob1.temp += delta;
+ */
+export function heatTransfer(temp1, temp2, distance, maxDistance, rate) {
+  if (distance >= maxDistance) return 0;
+
+  // Heat flows from hot to cold
+  const heatDiff = temp2 - temp1;
+
+  // Optional: scale transfer by proximity (closer = faster transfer)
+  // const proximity = 1 - (distance / maxDistance);
+  // return heatDiff * rate * proximity;
+
+  return heatDiff * rate;
+}
+
+/**
+ * Calculate heat transfer with distance falloff.
+ * Transfer rate decreases with distance for more realistic behavior.
+ *
+ * @param {number} temp1 - Temperature of first particle [0, 1]
+ * @param {number} temp2 - Temperature of second particle [0, 1]
+ * @param {number} distance - Distance between particle centers
+ * @param {number} maxDistance - Maximum distance for heat transfer
+ * @param {number} rate - Base heat transfer rate coefficient
+ * @param {number} [falloff=1] - Distance falloff exponent (1 = linear, 2 = quadratic)
+ * @returns {number} Temperature change for particle 1
+ *
+ * @example
+ * // Quadratic falloff for more localized heat transfer
+ * const delta = heatTransferFalloff(t1, t2, dist, maxDist, 0.003, 2);
+ */
+export function heatTransferFalloff(temp1, temp2, distance, maxDistance, rate, falloff = 1) {
+  if (distance >= maxDistance) return 0;
+
+  const heatDiff = temp2 - temp1;
+  const proximity = Math.pow(1 - distance / maxDistance, falloff);
+
+  return heatDiff * rate * proximity;
+}

package/src/math/index.js

@@ -0,0 +1,12 @@
+export {Random} from "./random.js";
+export {Complex} from "./complex.js";
+export {Fractals} from "./fractal.js";
+export {Patterns} from "./patterns.js";
+export {Noise} from "./noise.js";
+export {Tensor} from "./tensor.js";
+
+// Physics modules
+export * from "./gr.js";
+export * from "./orbital.js";
+export * from "./quantum.js";
+export * from "./heat.js";