@guinetik/gcanvas 1.0.0 → 1.0.2

package/src/util/camera3d.js

@@ -32,6 +32,9 @@ export class Camera3D {
    * @param {number} [options.rotationX=0] - Initial X rotation (tilt up/down) in radians
    * @param {number} [options.rotationY=0] - Initial Y rotation (spin left/right) in radians
    * @param {number} [options.rotationZ=0] - Initial Z rotation (roll) in radians
+   * @param {number} [options.x=0] - Initial X position in world space
+   * @param {number} [options.y=0] - Initial Y position in world space
+   * @param {number} [options.z=0] - Initial Z position in world space
    * @param {number} [options.perspective=800] - Perspective distance (higher = less distortion)
    * @param {number} [options.sensitivity=0.005] - Mouse drag sensitivity
    * @param {number} [options.minRotationX=-1.5] - Minimum X rotation limit
@@ -49,10 +52,18 @@ export class Camera3D {
     this.rotationY = options.rotationY ?? 0;
     this.rotationZ = options.rotationZ ?? 0;
 
+    // Position state (camera location in world space)
+    this.x = options.x ?? 0;
+    this.y = options.y ?? 0;
+    this.z = options.z ?? 0;
+
     // Store initial values for reset
     this._initialRotationX = this.rotationX;
     this._initialRotationY = this.rotationY;
     this._initialRotationZ = this.rotationZ;
+    this._initialX = this.x;
+    this._initialY = this.y;
+    this._initialZ = this.z;
 
     // Perspective
     this.perspective = options.perspective ?? 800;
@@ -86,6 +97,20 @@ export class Camera3D {
     this._lastMouseY = 0;
     this._canvas = null;
     this._boundHandlers = null;
+
+    // Follow target state
+    this._followTarget = null;
+    this._followOffset = { x: 0, y: 0, z: 0 };
+    this._followLookAt = true;  // Auto-orient to look at target's forward direction
+    this._followLerp = 0.1;     // Interpolation speed (0-1, higher = snappier)
+
+    // Position animation state
+    this._targetX = null;
+    this._targetY = null;
+    this._targetZ = null;
+    this._targetRotationX = null;
+    this._targetRotationY = null;
+    this._positionLerp = 0.05;  // Default smooth movement speed
   }
 
   /**
@@ -96,6 +121,12 @@ export class Camera3D {
    * @returns {{x: number, y: number, z: number, scale: number}} Projected 2D coordinates and depth info
    */
   project(x, y, z) {
+    // Translate world relative to camera position
+    // (Moving camera right = moving world left)
+    x -= this.x;
+    y -= this.y;
+    z -= this.z;
+
     // Rotate around Z axis (roll)
     if (this.rotationZ !== 0) {
       const cosZ = Math.cos(this.rotationZ);
@@ -141,12 +172,78 @@ export class Camera3D {
   }
 
   /**
-   * Update camera for auto-rotation and inertia (call in update loop)
+   * Update camera for auto-rotation, inertia, and follow mode (call in update loop)
    * @param {number} dt - Delta time in seconds
    */
   update(dt) {
-    // Apply inertia when not dragging
-    if (this.inertia && !this._isDragging) {
+    // Follow target mode - position camera relative to target
+    if (this._followTarget) {
+      const target = this._followTarget;
+      const targetX = (target.x ?? 0) + this._followOffset.x;
+      const targetY = (target.y ?? 0) + this._followOffset.y;
+      const targetZ = (target.z ?? 0) + this._followOffset.z;
+
+      // Smooth interpolation to target position
+      this.x += (targetX - this.x) * this._followLerp;
+      this.y += (targetY - this.y) * this._followLerp;
+      this.z += (targetZ - this.z) * this._followLerp;
+
+      // Auto-orient to look toward origin (or specified look target)
+      if (this._followLookAt) {
+        const lookX = this._followLookAtTarget?.x ?? 0;
+        const lookY = this._followLookAtTarget?.y ?? 0;
+        const lookZ = this._followLookAtTarget?.z ?? 0;
+
+        // Calculate direction from camera to look target
+        const dx = lookX - this.x;
+        const dy = lookY - this.y;
+        const dz = lookZ - this.z;
+        const distXZ = Math.sqrt(dx * dx + dz * dz);
+
+        // Target rotation to face the look target
+        const targetRotY = Math.atan2(dx, dz);
+        const targetRotX = Math.atan2(-dy, distXZ);
+
+        // Smooth rotation interpolation
+        this.rotationY += this._angleDiff(this.rotationY, targetRotY) * this._followLerp;
+        this.rotationX += (targetRotX - this.rotationX) * this._followLerp;
+      }
+    }
+    // Animated position movement (moveTo)
+    else if (this._targetX !== null) {
+      const lerp = this._positionLerp;
+
+      // Interpolate position
+      this.x += (this._targetX - this.x) * lerp;
+      this.y += (this._targetY - this.y) * lerp;
+      this.z += (this._targetZ - this.z) * lerp;
+
+      // Interpolate rotation if targets set
+      if (this._targetRotationX !== null) {
+        this.rotationX += (this._targetRotationX - this.rotationX) * lerp;
+      }
+      if (this._targetRotationY !== null) {
+        this.rotationY += this._angleDiff(this.rotationY, this._targetRotationY) * lerp;
+      }
+
+      // Check if we've arrived (close enough)
+      const posDist = Math.abs(this._targetX - this.x) +
+                      Math.abs(this._targetY - this.y) +
+                      Math.abs(this._targetZ - this.z);
+      if (posDist < 0.1) {
+        this.x = this._targetX;
+        this.y = this._targetY;
+        this.z = this._targetZ;
+        this._targetX = null;
+        this._targetY = null;
+        this._targetZ = null;
+        this._targetRotationX = null;
+        this._targetRotationY = null;
+      }
+    }
+
+    // Apply inertia when not dragging and not following
+    if (this.inertia && !this._isDragging && !this._followTarget) {
       // Apply velocity to rotation
       if (Math.abs(this._velocityX) > 0.0001 || Math.abs(this._velocityY) > 0.0001) {
         this.rotationY += this._velocityY;
@@ -167,8 +264,8 @@ export class Camera3D {
       }
     }
 
-    // Auto-rotate when not dragging and no significant velocity
-    if (this.autoRotate && !this._isDragging) {
+    // Auto-rotate when not dragging, not following, and no significant velocity
+    if (this.autoRotate && !this._isDragging && !this._followTarget) {
       const hasVelocity = Math.abs(this._velocityX) > 0.001 || Math.abs(this._velocityY) > 0.001;
       if (!hasVelocity) {
         const delta = this.autoRotateSpeed * dt;
@@ -187,6 +284,17 @@ export class Camera3D {
     }
   }
 
+  /**
+   * Calculate shortest angle difference (handles wraparound)
+   * @private
+   */
+  _angleDiff(from, to) {
+    let diff = to - from;
+    while (diff > Math.PI) diff -= Math.PI * 2;
+    while (diff < -Math.PI) diff += Math.PI * 2;
+    return diff;
+  }
+
   /**
    * Enable mouse/touch drag rotation on a canvas
    * @param {HTMLCanvasElement} canvas - The canvas element to attach controls to
@@ -360,15 +468,22 @@ export class Camera3D {
   }
 
   /**
-   * Reset rotation to initial values and stop inertia
+   * Reset rotation and position to initial values, stop inertia and following
    * @returns {Camera3D} Returns this for chaining
    */
   reset() {
     this.rotationX = this._initialRotationX;
     this.rotationY = this._initialRotationY;
     this.rotationZ = this._initialRotationZ;
+    this.x = this._initialX;
+    this.y = this._initialY;
+    this.z = this._initialZ;
     this._velocityX = 0;
     this._velocityY = 0;
+    this._followTarget = null;
+    this._targetX = null;
+    this._targetY = null;
+    this._targetZ = null;
     return this;
   }
 
@@ -382,6 +497,91 @@ export class Camera3D {
     return this;
   }
 
+  /**
+   * Set camera position in world space
+   * @param {number} x - X position
+   * @param {number} y - Y position
+   * @param {number} z - Z position
+   * @returns {Camera3D} Returns this for chaining
+   */
+  setPosition(x, y, z) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    return this;
+  }
+
+  /**
+   * Animate camera to a new position (and optionally rotation)
+   * @param {number} x - Target X position
+   * @param {number} y - Target Y position
+   * @param {number} z - Target Z position
+   * @param {object} [options] - Animation options
+   * @param {number} [options.rotationX] - Target X rotation
+   * @param {number} [options.rotationY] - Target Y rotation
+   * @param {number} [options.lerp=0.05] - Interpolation speed (0-1)
+   * @returns {Camera3D} Returns this for chaining
+   */
+  moveTo(x, y, z, options = {}) {
+    this._targetX = x;
+    this._targetY = y;
+    this._targetZ = z;
+    this._targetRotationX = options.rotationX ?? null;
+    this._targetRotationY = options.rotationY ?? null;
+    this._positionLerp = options.lerp ?? 0.05;
+    return this;
+  }
+
+  /**
+   * Follow a target object (position camera relative to target)
+   * @param {object} target - Object with x, y, z properties to follow
+   * @param {object} [options] - Follow options
+   * @param {number} [options.offsetX=0] - X offset from target
+   * @param {number} [options.offsetY=0] - Y offset from target
+   * @param {number} [options.offsetZ=0] - Z offset from target
+   * @param {boolean} [options.lookAt=true] - Auto-orient to look at lookAtTarget
+   * @param {object} [options.lookAtTarget=null] - Point to look at (default: origin)
+   * @param {number} [options.lerp=0.1] - Interpolation speed (0-1, higher = snappier)
+   * @returns {Camera3D} Returns this for chaining
+   */
+  follow(target, options = {}) {
+    this._followTarget = target;
+    this._followOffset = {
+      x: options.offsetX ?? 0,
+      y: options.offsetY ?? 0,
+      z: options.offsetZ ?? 0,
+    };
+    this._followLookAt = options.lookAt ?? true;
+    this._followLookAtTarget = options.lookAtTarget ?? null;
+    this._followLerp = options.lerp ?? 0.1;
+    return this;
+  }
+
+  /**
+   * Stop following target and optionally reset to initial position
+   * @param {boolean} [resetPosition=false] - Whether to animate back to initial position
+   * @returns {Camera3D} Returns this for chaining
+   */
+  unfollow(resetPosition = false) {
+    this._followTarget = null;
+    if (resetPosition) {
+      this.moveTo(this._initialX, this._initialY, this._initialZ, {
+        rotationX: this._initialRotationX,
+        rotationY: this._initialRotationY,
+        lerp: 0.05,
+      });
+    }
+    return this;
+  }
+
+  /**
+   * Check if camera is currently following a target
+   * @returns {boolean} True if following a target
+   */
+  isFollowing() {
+    return this._followTarget !== null;
+  }
+
   /**
    * Set rotation angles
    * @param {number} x - X rotation in radians
@@ -424,15 +624,21 @@ export class Camera3D {
   }
 
   /**
-   * Look at a specific point (sets rotation to face that direction)
-   * @param {number} x - Target X
-   * @param {number} y - Target Y
-   * @param {number} z - Target Z
+   * Look at a specific point (sets rotation to face that direction from current position)
+   * @param {number} x - Target X in world space
+   * @param {number} y - Target Y in world space
+   * @param {number} z - Target Z in world space
    * @returns {Camera3D} Returns this for chaining
    */
   lookAt(x, y, z) {
-    this.rotationY = Math.atan2(x, z);
-    this.rotationX = Math.atan2(y, Math.sqrt(x * x + z * z));
+    // Calculate direction from camera position to target
+    const dx = x - this.x;
+    const dy = y - this.y;
+    const dz = z - this.z;
+    const distXZ = Math.sqrt(dx * dx + dz * dz);
+
+    this.rotationY = Math.atan2(dx, dz);
+    this.rotationX = Math.atan2(-dy, distXZ);
     return this;
   }
 }

package/src/util/index.js

@@ -3,4 +3,5 @@ export * from "./position";
 export * from "./layout";
 export { TaskManager } from "./tasks";
 export { Camera3D } from "./camera3d";
+export { Camera2D } from "./camera2d";
 export { IsometricCamera } from "./isometric-camera";

package/src/webgl/shaders/plane-shaders.js

@@ -0,0 +1,332 @@
+/**
+ * Plane Shaders for WebGL Rendering
+ *
+ * These shaders render 2D patterns onto a plane quad.
+ * Unlike sphere shaders which use ray-sphere intersection,
+ * these shaders work directly with UV coordinates.
+ */
+
+// =============================================================================
+// VERTEX SHADER
+// =============================================================================
+
+/**
+ * Standard vertex shader for plane rendering
+ * Simply passes through position and UV coordinates
+ */
+export const PLANE_VERTEX = `
+precision highp float;
+
+attribute vec2 aPosition;
+attribute vec2 aUv;
+
+varying vec2 vUv;
+
+void main() {
+    vUv = aUv;
+    gl_Position = vec4(aPosition, 0.0, 1.0);
+}
+`;
+
+// =============================================================================
+// COMMON SHADER FUNCTIONS
+// =============================================================================
+
+/**
+ * Common functions included in all plane fragment shaders
+ */
+export const PLANE_COMMON = `
+precision highp float;
+
+varying vec2 vUv;
+
+uniform float uTime;
+uniform vec2 uResolution;
+
+// =============================================================================
+// NOISE FUNCTIONS
+// =============================================================================
+
+float hash(float n) {
+    return fract(sin(n) * 43758.5453123);
+}
+
+float hash2(vec2 p) {
+    return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+}
+
+// 2D Value noise
+float noise2D(vec2 x) {
+    vec2 i = floor(x);
+    vec2 f = fract(x);
+    f = f * f * (3.0 - 2.0 * f);
+
+    float a = hash2(i);
+    float b = hash2(i + vec2(1.0, 0.0));
+    float c = hash2(i + vec2(0.0, 1.0));
+    float d = hash2(i + vec2(1.0, 1.0));
+
+    return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
+}
+
+// FBM (Fractional Brownian Motion)
+float fbm2D(vec2 p, int octaves) {
+    float value = 0.0;
+    float amplitude = 0.5;
+    float frequency = 1.0;
+
+    for (int i = 0; i < 8; i++) {
+        if (i >= octaves) break;
+        value += amplitude * noise2D(p * frequency);
+        frequency *= 2.0;
+        amplitude *= 0.5;
+    }
+
+    return value;
+}
+`;
+
+// =============================================================================
+// GRADIENT SHADER
+// =============================================================================
+
+/**
+ * Linear gradient shader
+ * Uniforms:
+ * - uColor1: Start color [r, g, b] (0-1)
+ * - uColor2: End color [r, g, b] (0-1)
+ * - uAngle: Gradient angle in radians (0 = horizontal, PI/2 = vertical)
+ */
+export const GRADIENT_FRAGMENT = `
+${PLANE_COMMON}
+
+uniform vec3 uColor1;
+uniform vec3 uColor2;
+uniform float uAngle;
+
+void main() {
+    vec2 uv = vUv;
+
+    // Calculate gradient direction from angle
+    vec2 dir = vec2(cos(uAngle), sin(uAngle));
+
+    // Project UV onto gradient direction
+    // Center at 0.5 so gradient goes through middle
+    float t = dot(uv - 0.5, dir) + 0.5;
+    t = clamp(t, 0.0, 1.0);
+
+    // Interpolate colors
+    vec3 color = mix(uColor1, uColor2, t);
+
+    gl_FragColor = vec4(color, 1.0);
+}
+`;
+
+// =============================================================================
+// GRID SHADER
+// =============================================================================
+
+/**
+ * Grid pattern shader
+ * Uniforms:
+ * - uLineColor: Grid line color [r, g, b] (0-1)
+ * - uBackgroundColor: Background color [r, g, b] (0-1)
+ * - uGridSize: Number of grid cells (e.g., 8.0 = 8x8 grid)
+ * - uLineWidth: Line width as fraction of cell (e.g., 0.05)
+ */
+export const GRID_FRAGMENT = `
+${PLANE_COMMON}
+
+uniform vec3 uLineColor;
+uniform vec3 uBackgroundColor;
+uniform float uGridSize;
+uniform float uLineWidth;
+
+void main() {
+    vec2 uv = vUv;
+
+    // Scale UV to grid space
+    vec2 grid = fract(uv * uGridSize);
+
+    // Calculate distance to nearest grid line
+    float lineX = min(grid.x, 1.0 - grid.x);
+    float lineY = min(grid.y, 1.0 - grid.y);
+
+    // Smoothstep for anti-aliased lines
+    float halfWidth = uLineWidth * 0.5;
+    float edgeSmooth = 0.01;
+
+    float lineAlphaX = 1.0 - smoothstep(halfWidth - edgeSmooth, halfWidth + edgeSmooth, lineX);
+    float lineAlphaY = 1.0 - smoothstep(halfWidth - edgeSmooth, halfWidth + edgeSmooth, lineY);
+    float lineAlpha = max(lineAlphaX, lineAlphaY);
+
+    // Mix colors
+    vec3 color = mix(uBackgroundColor, uLineColor, lineAlpha);
+
+    gl_FragColor = vec4(color, 1.0);
+}
+`;
+
+// =============================================================================
+// CHECKERBOARD SHADER
+// =============================================================================
+
+/**
+ * Checkerboard pattern shader
+ * Uniforms:
+ * - uColor1: First square color [r, g, b] (0-1)
+ * - uColor2: Second square color [r, g, b] (0-1)
+ * - uSize: Number of squares per side (e.g., 8.0 = 8x8)
+ */
+export const CHECKERBOARD_FRAGMENT = `
+${PLANE_COMMON}
+
+uniform vec3 uColor1;
+uniform vec3 uColor2;
+uniform float uSize;
+
+void main() {
+    vec2 uv = vUv;
+
+    // Calculate which square we're in
+    vec2 cell = floor(uv * uSize);
+
+    // Alternating pattern based on cell coordinates
+    float checker = mod(cell.x + cell.y, 2.0);
+
+    // Select color
+    vec3 color = mix(uColor1, uColor2, checker);
+
+    gl_FragColor = vec4(color, 1.0);
+}
+`;
+
+// =============================================================================
+// NOISE SHADER
+// =============================================================================
+
+/**
+ * Animated noise pattern shader
+ * Uniforms:
+ * - uColor1: Base color [r, g, b] (0-1)
+ * - uColor2: Secondary color [r, g, b] (0-1)
+ * - uNoiseScale: Scale of the noise pattern (e.g., 4.0)
+ * - uAnimSpeed: Animation speed (e.g., 0.5)
+ */
+export const NOISE_FRAGMENT = `
+${PLANE_COMMON}
+
+uniform vec3 uColor1;
+uniform vec3 uColor2;
+uniform float uNoiseScale;
+uniform float uAnimSpeed;
+
+void main() {
+    vec2 uv = vUv;
+
+    // Animated noise
+    float n = fbm2D(uv * uNoiseScale + uTime * uAnimSpeed, 4);
+
+    // Map noise to colors
+    vec3 color = mix(uColor1, uColor2, n);
+
+    gl_FragColor = vec4(color, 1.0);
+}
+`;
+
+// =============================================================================
+// RADIAL GRADIENT SHADER
+// =============================================================================
+
+/**
+ * Radial gradient shader
+ * Uniforms:
+ * - uColor1: Center color [r, g, b] (0-1)
+ * - uColor2: Edge color [r, g, b] (0-1)
+ * - uCenterX: Center X position (0-1, default 0.5)
+ * - uCenterY: Center Y position (0-1, default 0.5)
+ * - uRadius: Gradient radius (default 0.5)
+ */
+export const RADIAL_GRADIENT_FRAGMENT = `
+${PLANE_COMMON}
+
+uniform vec3 uColor1;
+uniform vec3 uColor2;
+uniform float uCenterX;
+uniform float uCenterY;
+uniform float uRadius;
+
+void main() {
+    vec2 uv = vUv;
+    vec2 center = vec2(uCenterX, uCenterY);
+
+    // Calculate distance from center
+    float dist = length(uv - center);
+
+    // Normalize by radius
+    float t = clamp(dist / uRadius, 0.0, 1.0);
+
+    // Interpolate colors
+    vec3 color = mix(uColor1, uColor2, t);
+
+    gl_FragColor = vec4(color, 1.0);
+}
+`;
+
+// =============================================================================
+// STRIPES SHADER
+// =============================================================================
+
+/**
+ * Stripe pattern shader
+ * Uniforms:
+ * - uColor1: First stripe color [r, g, b] (0-1)
+ * - uColor2: Second stripe color [r, g, b] (0-1)
+ * - uStripeCount: Number of stripes
+ * - uAngle: Stripe angle in radians
+ */
+export const STRIPES_FRAGMENT = `
+${PLANE_COMMON}
+
+uniform vec3 uColor1;
+uniform vec3 uColor2;
+uniform float uStripeCount;
+uniform float uAngle;
+
+void main() {
+    vec2 uv = vUv;
+
+    // Rotate UV by angle
+    vec2 center = vec2(0.5);
+    vec2 rotated = uv - center;
+    float c = cos(uAngle);
+    float s = sin(uAngle);
+    rotated = vec2(rotated.x * c - rotated.y * s, rotated.x * s + rotated.y * c);
+    rotated += center;
+
+    // Create stripes along one axis
+    float stripe = floor(mod(rotated.x * uStripeCount, 2.0));
+
+    // Select color
+    vec3 color = mix(uColor1, uColor2, stripe);
+
+    gl_FragColor = vec4(color, 1.0);
+}
+`;
+
+// =============================================================================
+// SHADER EXPORT
+// =============================================================================
+
+export const PLANE_SHADERS = {
+    vertex: PLANE_VERTEX,
+    common: PLANE_COMMON,
+    gradient: GRADIENT_FRAGMENT,
+    grid: GRID_FRAGMENT,
+    checkerboard: CHECKERBOARD_FRAGMENT,
+    noise: NOISE_FRAGMENT,
+    radialGradient: RADIAL_GRADIENT_FRAGMENT,
+    stripes: STRIPES_FRAGMENT,
+};
+
+export default PLANE_SHADERS;

package/src/webgl/shaders/sphere-shaders.js

@@ -904,6 +904,7 @@ ${SPHERE_COMMON}
 uniform vec3 uBaseColor;
 uniform float uSeed;
 uniform float uStormIntensity;  // 0-1
+uniform float uRotationSpeed;   // rotation speed multiplier (default ~0.1)
 
 void main() {
     // Setup ray - camera looking at sphere from fixed position
@@ -930,8 +931,9 @@ void main() {
     float latitude = asin(rotatedNormal.y);  // -PI/2 to PI/2
     float longitude = atan(rotatedNormal.z, rotatedNormal.x);  // -PI to PI
 
-    // Animated rotation
-    float time = uTime * 0.1;
+    // Animated rotation (use uRotationSpeed, default to 0.1 if not set)
+    float rotSpeed = uRotationSpeed > 0.0 ? uRotationSpeed : 0.1;
+    float time = uTime * rotSpeed;
 
     // Create bands based on latitude
     float bands = sin(latitude * 15.0 + time) * 0.5 + 0.5;