jsgui3-server 0.0.134 → 0.0.136

package/examples/controls/14d) window, canvas globe/math.test.js

@@ -0,0 +1,281 @@
+'use strict';
+
+const assert = require('assert');
+const {
+  qIdentity,
+  qNormalize,
+  qMul,
+  qFromAxisAngle,
+  qFromVectors,
+  mat3FromQuat,
+  mat3Transpose
+} = require('./math');
+
+describe('Quaternion Math Functions', function() {
+  
+  // Helper to check if two numbers are approximately equal
+  function approx_equal(a, b, epsilon = 1e-10) {
+    return Math.abs(a - b) < epsilon;
+  }
+  
+  // Helper to check if two arrays are approximately equal
+  function approx_equal_array(a, b, epsilon = 1e-10) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!approx_equal(a[i], b[i], epsilon)) return false;
+    }
+    return true;
+  }
+  
+  // Helper to compute quaternion magnitude
+  function q_magnitude(q) {
+    return Math.sqrt(q[0]*q[0] + q[1]*q[1] + q[2]*q[2] + q[3]*q[3]);
+  }
+  
+  describe('qIdentity', function() {
+    it('should return identity quaternion [0, 0, 0, 1]', function() {
+      const q = qIdentity();
+      assert.deepStrictEqual(q, [0, 0, 0, 1]);
+    });
+  });
+  
+  describe('qNormalize', function() {
+    it('should normalize a quaternion to unit length', function() {
+      const q = [1, 2, 3, 4];
+      const normalized = qNormalize(q);
+      const mag = q_magnitude(normalized);
+      assert(approx_equal(mag, 1.0), `Magnitude should be 1.0, got ${mag}`);
+    });
+    
+    it('should handle zero quaternion gracefully', function() {
+      const q = [0, 0, 0, 0];
+      const normalized = qNormalize(q);
+      // Should normalize to [0,0,0,0] since magnitude is 0
+      assert.deepStrictEqual(normalized, [0, 0, 0, 0]);
+    });
+    
+    it('should preserve already normalized quaternions', function() {
+      const q = qIdentity();
+      const normalized = qNormalize(q);
+      assert(approx_equal_array(normalized, [0, 0, 0, 1]));
+    });
+  });
+  
+  describe('qMul', function() {
+    it('should multiply two quaternions correctly', function() {
+      // Identity * anything = anything
+      const q1 = qIdentity();
+      const q2 = [1, 2, 3, 4];
+      const result = qMul(q1, q2);
+      assert(approx_equal_array(result, q2, 1e-9));
+    });
+    
+    it('should be non-commutative (q1*q2 != q2*q1 in general)', function() {
+      const q1 = qFromAxisAngle(1, 0, 0, Math.PI / 4);
+      const q2 = qFromAxisAngle(0, 1, 0, Math.PI / 4);
+      const r1 = qMul(q1, q2);
+      const r2 = qMul(q2, q1);
+      
+      // These should not be equal
+      const are_equal = approx_equal_array(r1, r2, 1e-6);
+      assert(!are_equal, 'Quaternion multiplication should be non-commutative');
+    });
+    
+    it('should compose rotations correctly', function() {
+      // 90° rotation around Z-axis
+      const q1 = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      // Another 90° rotation around Z-axis
+      const q2 = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      // Combined should be 180° around Z-axis
+      const result = qNormalize(qMul(q1, q2));
+      const expected = qFromAxisAngle(0, 0, 1, Math.PI);
+      
+      // Allow for both q and -q (they represent same rotation)
+      const match = approx_equal_array(result, expected, 1e-9) ||
+                    approx_equal_array(result, [-expected[0], -expected[1], -expected[2], -expected[3]], 1e-9);
+      assert(match, `Expected ${expected}, got ${result}`);
+    });
+  });
+  
+  describe('qFromAxisAngle', function() {
+    it('should create quaternion from axis-angle', function() {
+      // 180° rotation around X-axis
+      const q = qFromAxisAngle(1, 0, 0, Math.PI);
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Quaternion should be unit length');
+      assert(approx_equal(q[0], 1.0, 1e-9), 'X component should be ~1');
+      assert(approx_equal(q[3], 0.0, 1e-9), 'W component should be ~0');
+    });
+    
+    it('should handle zero angle (identity)', function() {
+      const q = qFromAxisAngle(1, 0, 0, 0);
+      assert(approx_equal_array(q, [0, 0, 0, 1], 1e-9));
+    });
+    
+    it('should normalize axis internally', function() {
+      // Non-unit axis
+      const q = qFromAxisAngle(3, 4, 0, Math.PI / 2);
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Result should be unit quaternion');
+    });
+  });
+  
+  describe('qFromVectors', function() {
+    it('should create quaternion rotating u to v', function() {
+      const u = [1, 0, 0];
+      const v = [0, 1, 0];
+      const q = qFromVectors(u, v);
+      
+      // Verify it's a unit quaternion
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Should be unit quaternion');
+    });
+    
+    it('should handle identical vectors (no rotation)', function() {
+      const u = [1, 0, 0];
+      const v = [1, 0, 0];
+      const q = qFromVectors(u, v);
+      
+      // Should be identity or very close
+      assert(approx_equal_array(q, [0, 0, 0, 1], 1e-9));
+    });
+    
+    it('should handle opposite vectors (180° rotation)', function() {
+      const u = [1, 0, 0];
+      const v = [-1, 0, 0];
+      const q = qFromVectors(u, v);
+      
+      // Should be a 180° rotation
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Should be unit quaternion');
+      // W component should be ~0 for 180° rotation
+      assert(approx_equal(Math.abs(q[3]), 0.0, 1e-9));
+    });
+    
+    it('should handle small angle rotations robustly', function() {
+      const u = [1, 0, 0];
+      const v = [0.99999, 0.00001, 0];
+      // Normalize v
+      const vn = Math.sqrt(v[0]*v[0] + v[1]*v[1] + v[2]*v[2]);
+      v[0] /= vn; v[1] /= vn; v[2] /= vn;
+      
+      const q = qFromVectors(u, v);
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Should be unit quaternion');
+    });
+  });
+  
+  describe('mat3FromQuat', function() {
+    it('should create rotation matrix from quaternion', function() {
+      const q = qIdentity();
+      const m = mat3FromQuat(q);
+      
+      // Identity quaternion should give identity matrix
+      const identity = [
+        1, 0, 0,
+        0, 1, 0,
+        0, 0, 1
+      ];
+      assert(approx_equal_array(m, identity, 1e-9));
+    });
+    
+    it('should create correct matrix for 90° Z rotation', function() {
+      const q = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      const m = mat3FromQuat(q);
+      
+      // 90° Z rotation matrix (column-major)
+      const expected = [
+        0, 1, 0,
+        -1, 0, 0,
+        0, 0, 1
+      ];
+      assert(approx_equal_array(m, expected, 1e-9));
+    });
+    
+    it('should produce orthogonal matrix', function() {
+      const q = qNormalize([1, 2, 3, 4]);
+      const m = mat3FromQuat(q);
+      
+      // Check if M * M^T = I (orthogonality test)
+      const mt = mat3Transpose(m);
+      
+      // Multiply M * M^T (both are column-major)
+      const result = [];
+      for (let row = 0; row < 3; row++) {
+        for (let col = 0; col < 3; col++) {
+          let sum = 0;
+          for (let k = 0; k < 3; k++) {
+            // m is column-major: element at (row, k) is m[k*3 + row]
+            // mt is column-major: element at (k, col) is mt[col*3 + k]
+            sum += m[k * 3 + row] * mt[col * 3 + k];
+          }
+          result.push(sum);
+        }
+      }
+      
+      const identity = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+      assert(approx_equal_array(result, identity, 1e-9));
+    });
+  });
+  
+  describe('mat3Transpose', function() {
+    it('should transpose a 3x3 matrix', function() {
+      const m = [
+        1, 2, 3,
+        4, 5, 6,
+        7, 8, 9
+      ];
+      const mt = mat3Transpose(m);
+      const expected = [
+        1, 4, 7,
+        2, 5, 8,
+        3, 6, 9
+      ];
+      assert.deepStrictEqual(mt, expected);
+    });
+    
+    it('should be self-inverse (transpose twice = original)', function() {
+      const m = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+      const mt = mat3Transpose(m);
+      const mtt = mat3Transpose(mt);
+      assert.deepStrictEqual(mtt, m);
+    });
+  });
+  
+  describe('Integration Tests', function() {
+    it('should rotate a vector correctly using quaternion', function() {
+      // Rotate point [1,0,0] by 90° around Z-axis
+      // Should get [0,1,0]
+      const q = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      const m = mat3FromQuat(q);
+      
+      const v = [1, 0, 0];
+      const result = [
+        m[0] * v[0] + m[3] * v[1] + m[6] * v[2],
+        m[1] * v[0] + m[4] * v[1] + m[7] * v[2],
+        m[2] * v[0] + m[5] * v[1] + m[8] * v[2]
+      ];
+      
+      assert(approx_equal_array(result, [0, 1, 0], 1e-9));
+    });
+    
+    it('should compose multiple rotations correctly', function() {
+      // Rotate 90° around X, then 90° around Y
+      const qx = qFromAxisAngle(1, 0, 0, Math.PI / 2);
+      const qy = qFromAxisAngle(0, 1, 0, Math.PI / 2);
+      const qCombined = qNormalize(qMul(qy, qx));
+      
+      // Apply to point [1, 0, 0]
+      const m = mat3FromQuat(qCombined);
+      const v = [1, 0, 0];
+      const result = [
+        m[0] * v[0] + m[3] * v[1] + m[6] * v[2],
+        m[1] * v[0] + m[4] * v[1] + m[7] * v[2],
+        m[2] * v[0] + m[5] * v[1] + m[8] * v[2]
+      ];
+      
+      // Should get [0, 0, -1] (or close to it)
+      assert(approx_equal_array(result, [0, 0, -1], 1e-9));
+    });
+  });
+});

package/examples/controls/14d) window, canvas globe/pipeline/BaseStage.js

@@ -0,0 +1,46 @@
+
+/**
+ * @typedef {Object} RenderState
+ * @property {CanvasRenderingContext2D} ctx - Destination 2D context.
+ * @property {number} width - Canvas width in CSS pixels.
+ * @property {number} height - Canvas height in CSS pixels.
+ * @property {number} radius - Globe screen-space radius (px).
+ * @property {number} cx - Globe center X in canvas coordinates.
+ * @property {number} cy - Globe center Y in canvas coordinates.
+ * @property {boolean} interactive - True if frame triggered by interaction (may raise quality scale).
+ */
+
+/**
+ * @typedef {Object} Continent
+ * @property {string} name
+ * @property {Float32Array} polyXYZ - Original great-circle densified polygon vertices (triplets).
+ * @property {Uint16Array|null} tri - Triangulated index list (ear clipping) referencing polygon vertex order.
+ * @property {Float32Array} [_rotated] - Per-frame rotated vertices (camera space).
+ * @property {Uint16Array} [_visTris] - Front-facing triangle indices (subset of tri).
+ * @property {number} [_visTrisLen] - Number of used indices in _visTris.
+ * @property {{idx:number[]}[]} [_strokeRuns] - Contiguous front-facing edge runs for outline stroking.
+ * @property {string|null} [fill]
+ * @property {string|null} [stroke]
+ * @property {number|null} [lineWidth]
+ */
+
+/**
+ * BaseStage
+ * Lightweight interface each pipeline stage implements. Stages may override
+ * prepare (optional) and must implement execute. Keeping the interface tiny
+ * avoids overhead inside the render loop.
+ */
+class BaseStage {
+	/**
+	 * @param {any} r - Renderer instance.
+	 */
+	constructor(r) {
+		this.r = r;
+	}
+	/** @param {RenderState} _rs */
+	prepare(_rs) {}
+	/** @param {RenderState} _rs */
+	execute(_rs) {}
+}
+
+module.exports = BaseStage;

package/examples/controls/14d) window, canvas globe/pipeline/ClippingStage.js

@@ -0,0 +1,29 @@
+const BaseStage = require('./BaseStage');
+const frontFace = require('./clipping/FrontFaceStrategy');
+const planeClip = require('./clipping/PlaneClipStrategy');
+
+// Strategy registry (extensible)
+const strategies = {
+  frontFace,
+  planeClip
+};
+
+class ClippingStage extends BaseStage {
+  constructor(r){
+    super(r);
+  }
+  /** @param {RenderState} _rs */
+  execute(_rs){
+    const r = this.r;
+    if(!r._continents) return;
+  // Choose best default strategy; allow override via opts.clipping.mode
+  const mode = r.opts.clipping?.mode || 'planeClip';
+    const strat = strategies[mode] || strategies.frontFace;
+    const R = r.R;
+    for(const c of r._continents){
+      strat.process(r, c, R);
+    }
+  }
+}
+
+module.exports = ClippingStage;

package/examples/controls/14d) window, canvas globe/pipeline/ComposeStage.js

@@ -0,0 +1,15 @@
+const BaseStage = require('./BaseStage');
+
+class ComposeStage extends BaseStage {
+  /** @param {RenderState} rs */
+  execute(rs) {
+    const ctx = rs.ctx;
+    ctx.beginPath();
+    ctx.arc(rs.cx, rs.cy, rs.radius, 0, Math.PI * 2);
+    ctx.strokeStyle = 'rgba(0,0,0,0.14)';
+    ctx.lineWidth = 1.1;
+    ctx.stroke();
+  }
+}
+
+module.exports = ComposeStage;

package/examples/controls/14d) window, canvas globe/pipeline/ContinentsStage.js

@@ -0,0 +1,116 @@
+const BaseStage = require('./BaseStage');
+
+class ContinentsStage extends BaseStage {
+  /** @param {RenderState} rs */
+  execute(rs) {
+    const rInst = this.r;
+    if (!rInst._continents) return;
+    const ctx = rInst.ctx;
+    const clippingEnabled = !!rInst.opts.clipping.enabled; // currently front-face only
+
+    for (const c of rInst._continents) {
+  const rot = c._rotated;
+  if (!rot) continue;
+
+      const fillStyle = c.fill || rInst.opts.antarcticaFill;
+      const strokeStyle = c.stroke || rInst.opts.antarcticaStroke;
+      const lw = c.lineWidth || rInst.opts.antarcticaLineWidth;
+
+  // Fill: draw a solid path when available (prevents triangle AA seams)
+      if (c._clipFillPathXY && c._clipFillPathXY.length >= 6) {
+        const path = c._clipFillPathXY;
+        ctx.save();
+        ctx.fillStyle = fillStyle;
+        ctx.beginPath();
+        ctx.moveTo(rs.cx + rs.radius * path[0], rs.cy - rs.radius * path[1]);
+        for (let i = 2; i < path.length; i += 2) {
+          const x = path[i], y = path[i+1];
+          ctx.lineTo(rs.cx + rs.radius * x, rs.cy - rs.radius * y);
+        }
+        ctx.closePath();
+        ctx.fill();
+        ctx.restore();
+      } else if (c._clipFillTris && c._clipFillTrisLen) {
+        const buf = c._clipFillTris;
+        ctx.save();
+        ctx.fillStyle = fillStyle;
+        for (let i = 0; i < c._clipFillTrisLen * 2; i += 6) {
+          const ax = buf[i], ay = buf[i + 1];
+          const bx = buf[i + 2], by = buf[i + 3];
+          const cx = buf[i + 4], cy = buf[i + 5];
+          ctx.beginPath();
+          ctx.moveTo(rs.cx + rs.radius * ax, rs.cy - rs.radius * ay);
+          ctx.lineTo(rs.cx + rs.radius * bx, rs.cy - rs.radius * by);
+          ctx.lineTo(rs.cx + rs.radius * cx, rs.cy - rs.radius * cy);
+          ctx.closePath();
+          ctx.fill();
+        }
+        ctx.restore();
+      } else if (c._visTrisLen) {
+        ctx.save();
+        ctx.fillStyle = fillStyle;
+        ctx.beginPath();
+        const len = c._visTrisLen;
+        for (let i = 0; i < len; i += 3) {
+          const ia = c._visTris[i];
+          const ib = c._visTris[i + 1];
+          const ic = c._visTris[i + 2];
+          const a = ia * 3, b = ib * 3, d = ic * 3;
+          const ax = rot[a], ay = rot[a + 1];
+          const bx = rot[b], by = rot[b + 1];
+          const cx = rot[d], cy = rot[d + 1];
+          ctx.moveTo(rs.cx + rs.radius * ax, rs.cy - rs.radius * ay);
+          ctx.lineTo(rs.cx + rs.radius * bx, rs.cy - rs.radius * by);
+          ctx.lineTo(rs.cx + rs.radius * cx, rs.cy - rs.radius * cy);
+        }
+        ctx.fill();
+        ctx.restore();
+      }
+
+      // Stroke: prefer clipped runs if present, else legacy runs, else legacy polyline
+      if (c._clipStrokeRuns && c._clipStrokeRuns.length) {
+        ctx.save();
+        ctx.strokeStyle = strokeStyle;
+        ctx.lineWidth = lw;
+        for (const buf of c._clipStrokeRuns) {
+          if (!buf || buf.length < 4) continue;
+          ctx.beginPath();
+          let sx = rs.cx + rs.radius * buf[0];
+          let sy = rs.cy - rs.radius * buf[1];
+          ctx.moveTo(sx, sy);
+          for (let i = 2; i < buf.length; i += 2) {
+            sx = rs.cx + rs.radius * buf[i];
+            sy = rs.cy - rs.radius * buf[i + 1];
+            ctx.lineTo(sx, sy);
+          }
+          ctx.stroke();
+        }
+        ctx.restore();
+      } else if (c._strokeRuns && c._strokeRuns.length) {
+        ctx.save();
+        ctx.strokeStyle = strokeStyle;
+        ctx.lineWidth = lw;
+        for (const run of c._strokeRuns) {
+          if (run.idx.length < 2) continue;
+          ctx.beginPath();
+          for (let i = 0; i < run.idx.length; i++) {
+            const vi = run.idx[i] * 3;
+            const x = rot[vi];
+            const y = rot[vi + 1];
+            const sx = rs.cx + rs.radius * x;
+            const sy = rs.cy - rs.radius * y;
+            if (!i) ctx.moveTo(sx, sy); else ctx.lineTo(sx, sy);
+          }
+          ctx.stroke();
+        }
+        ctx.restore();
+      }
+
+      // Placeholder: if future partial clipping is added, use original + rot arrays here
+      void clippingEnabled;
+    }
+  }
+  // Triangulation handled in ClippingStage
+}
+
+module.exports = ContinentsStage;

package/examples/controls/14d) window, canvas globe/pipeline/GridStage.js

@@ -0,0 +1,105 @@
+const BaseStage = require('./BaseStage');
+
+// Precompute constant to avoid repeated division inside loops.
+const DEG = Math.PI / 180;
+
+class GridStage extends BaseStage {
+  /** @param {RenderState} rs */
+  execute(rs) {
+    const rInst = this.r;
+    if (!rInst.opts.grid?.enabled) return;
+
+    const g = rInst.opts.grid;
+    const params = rInst._gridCache?.params;
+
+    const unchanged = (
+      params &&
+      params.stepLat === g.stepLat &&
+      params.stepLon === g.stepLon &&
+      params.sampleStepDeg === g.sampleStepDeg
+    );
+
+    if (!unchanged) {
+      const parallels = [];
+    for (let lat = -80; lat <= 80; lat += g.stepLat) {
+        const pts = [];
+        for (let lon = -180; lon <= 180; lon += g.sampleStepDeg) {
+      const φ = lat * DEG;
+      const λ = lon * DEG;
+          const cφ = Math.cos(φ), sφ = Math.sin(φ);
+          const sλ = Math.sin(λ), cλ = Math.cos(λ);
+          pts.push(cφ * sλ, sφ, cφ * cλ);
+        }
+        parallels.push(new Float32Array(pts));
+      }
+
+      const meridians = [];
+    for (let lon = -180; lon < 180; lon += g.stepLon) {
+        const pts = [];
+        for (let lat = -90; lat <= 90; lat += g.sampleStepDeg) {
+      const φ = lat * DEG;
+      const λ = lon * DEG;
+      const cφ = Math.cos(φ), sφ = Math.sin(φ);
+      const sλ = Math.sin(λ), cλ = Math.cos(λ);
+      pts.push(cφ * sλ, sφ, cφ * cλ);
+        }
+        meridians.push(new Float32Array(pts));
+      }
+
+      rInst._gridCache = {
+        parallels,
+        meridians,
+        params: {
+          stepLat: g.stepLat,
+          stepLon: g.stepLon,
+          sampleStepDeg: g.sampleStepDeg
+        }
+      };
+    }
+
+    const cache = rInst._gridCache;
+    if (!cache) return;
+    const ctx = rInst.ctx;
+    const R = rInst.R;
+    const R00 = R[0], R01 = R[3], R02 = R[6];
+    const R10 = R[1], R11 = R[4], R12 = R[7];
+    const R20 = R[2], R21 = R[5], R22 = R[8];
+
+    ctx.save();
+    ctx.strokeStyle = g.color;
+    ctx.globalAlpha = g.alpha;
+    ctx.lineWidth = g.lineWidth;
+    ctx.lineCap = 'round';
+
+  const drawLines = (lines) => {
+      for (const L of lines) {
+        let drawing = false;
+        ctx.beginPath();
+        for (let i = 0; i < L.length; i += 3) {
+          const vx = L[i], vy = L[i + 1], vz = L[i + 2];
+          const xw = R00 * vx + R01 * vy + R02 * vz;
+          const yw = R10 * vx + R11 * vy + R12 * vz;
+          const zw = R20 * vx + R21 * vy + R22 * vz;
+          if (zw >= 0) {
+            const sx = rs.cx + rs.radius * xw;
+            const sy = rs.cy - rs.radius * yw;
+            if (!drawing) { ctx.moveTo(sx, sy); drawing = true; }
+            else ctx.lineTo(sx, sy);
+          } else if (drawing) {
+            ctx.stroke();
+            ctx.beginPath();
+            drawing = false;
+          }
+        }
+        if (drawing) ctx.stroke();
+      }
+    };
+
+  // Parallels first (visual layering), then meridians.
+  drawLines(cache.parallels);
+  drawLines(cache.meridians);
+    ctx.restore();
+  }
+}
+
+module.exports = GridStage;

package/examples/controls/14d) window, canvas globe/pipeline/HUDStage.js

@@ -0,0 +1,10 @@
+const BaseStage = require('./BaseStage');
+
+class HUDStage extends BaseStage {
+		/** @param {RenderState} _rs */
+		execute(_rs) {
+		if (this.r.opts.showFPS) this.r._drawFPS();
+	}
+}
+
+module.exports = HUDStage;