gladly-plot 0.0.5 → 0.0.6

package/src/axes/AxisRegistry.js

@@ -1,31 +1,94 @@
 import * as d3 from "d3-scale"
 import { getAxisQuantityKind } from "./AxisQuantityKindRegistry.js"
 
-export const AXES = ["xaxis_bottom","xaxis_top","yaxis_left","yaxis_right"]
+// Geometry of every spatial axis position in the normalised unit cube [-1, +1]³.
+//   dir:     which dimension varies along this axis ('x', 'y', or 'z')
+//   fixed:   the two non-varying coordinates on the unit cube faces
+//   outward: model-space unit vector pointing away from the cube face
+//            (tick marks and labels are offset in this direction)
+export const AXIS_GEOMETRY = {
+  // X-axes: x ∈ [-1,+1] varies; y and z are fixed
+  'xaxis_bottom':      { dir: 'x', fixed: { y: -1, z: +1 }, outward: [0, -1, 0] },
+  'xaxis_top':         { dir: 'x', fixed: { y: +1, z: +1 }, outward: [0, +1, 0] },
+  'xaxis_bottom_back': { dir: 'x', fixed: { y: -1, z: -1 }, outward: [0, -1, 0] },
+  'xaxis_top_back':    { dir: 'x', fixed: { y: +1, z: -1 }, outward: [0, +1, 0] },
+  // Y-axes: y ∈ [-1,+1] varies; x and z are fixed
+  'yaxis_left':        { dir: 'y', fixed: { x: -1, z: +1 }, outward: [-1, 0, 0] },
+  'yaxis_right':       { dir: 'y', fixed: { x: +1, z: +1 }, outward: [+1, 0, 0] },
+  'yaxis_left_back':   { dir: 'y', fixed: { x: -1, z: -1 }, outward: [-1, 0, 0] },
+  'yaxis_right_back':  { dir: 'y', fixed: { x: +1, z: -1 }, outward: [+1, 0, 0] },
+  // Z-axes: z ∈ [-1,+1] varies; x and y are fixed
+  'zaxis_bottom_left':  { dir: 'z', fixed: { x: -1, y: -1 }, outward: [0, -1, 0] },
+  'zaxis_bottom_right': { dir: 'z', fixed: { x: +1, y: -1 }, outward: [0, -1, 0] },
+  'zaxis_top_left':     { dir: 'z', fixed: { x: -1, y: +1 }, outward: [0, +1, 0] },
+  'zaxis_top_right':    { dir: 'z', fixed: { x: +1, y: +1 }, outward: [0, +1, 0] },
+}
+
+// All 12 spatial axis names.
+export const AXES = Object.keys(AXIS_GEOMETRY)
+
+// The four original 2D axis positions (used by ZoomController for 2D pan/zoom).
+export const AXES_2D = ['xaxis_bottom', 'xaxis_top', 'yaxis_left', 'yaxis_right']
+
+// Returns the start and end model-space points [x,y,z] of an axis in the unit cube.
+export function axisEndpoints(axisName) {
+  const { dir, fixed } = AXIS_GEOMETRY[axisName]
+  const start = [0, 0, 0], end = [0, 0, 0]
+  if (dir === 'x') {
+    start[0] = -1; end[0] = +1
+    start[1] = end[1] = fixed.y
+    start[2] = end[2] = fixed.z
+  } else if (dir === 'y') {
+    start[0] = end[0] = fixed.x
+    start[1] = -1; end[1] = +1
+    start[2] = end[2] = fixed.z
+  } else {
+    start[0] = end[0] = fixed.x
+    start[1] = end[1] = fixed.y
+    start[2] = -1; end[2] = +1
+  }
+  return { start, end }
+}
+
+// Returns the model-space position of a point at normalised position n ∈ [0,1] along an axis.
+export function axisPosAtN(axisName, n) {
+  const u = n * 2 - 1   // [0,1] → [-1,+1]
+  const { dir, fixed } = AXIS_GEOMETRY[axisName]
+  if (dir === 'x') return [u, fixed.y, fixed.z]
+  if (dir === 'y') return [fixed.x, u, fixed.z]
+  return [fixed.x, fixed.y, u]
+}
 
 export class AxisRegistry {
   constructor(width, height) {
     this.scales = {}
     this.axisQuantityKinds = {}
-    this.width = width
+    this.width  = width
     this.height = height
-    AXES.forEach(a => {
-      this.scales[a] = null
+    for (const a of AXES) {
+      this.scales[a]            = null
       this.axisQuantityKinds[a] = null
-    })
+    }
   }
 
   ensureAxis(axisName, axisQuantityKind, scaleOverride) {
-    if (!AXES.includes(axisName)) throw new Error(`Unknown axis ${axisName}`)
+    if (!AXES.includes(axisName))
+      throw new Error(`Unknown axis '${axisName}'`)
     if (this.axisQuantityKinds[axisName] && this.axisQuantityKinds[axisName] !== axisQuantityKind)
-      throw new Error(`Axis quantity kind mismatch on axis ${axisName}: ${this.axisQuantityKinds[axisName]} vs ${axisQuantityKind}`)
+      throw new Error(`Axis quantity kind mismatch on '${axisName}': ${this.axisQuantityKinds[axisName]} vs ${axisQuantityKind}`)
 
     if (!this.scales[axisName]) {
-      const quantityKindDef = getAxisQuantityKind(axisQuantityKind)
-      const scaleType = scaleOverride ?? quantityKindDef.scale
-      this.scales[axisName] = scaleType === "log"
-        ? d3.scaleLog().range(axisName.includes("y") ? [this.height,0] : [0,this.width])
-        : d3.scaleLinear().range(axisName.includes("y") ? [this.height,0] : [0,this.width])
+      const qkDef    = getAxisQuantityKind(axisQuantityKind)
+      const scaleType = scaleOverride ?? qkDef.scale
+      const dir = AXIS_GEOMETRY[axisName].dir
+      // D3 scale range: pixel length for x/y axes (used for tick-density hints in 2D).
+      // Z-axes use [0, 1] (no direct pixel mapping; tick density computed from projected length).
+      const range = dir === 'z' ? [0, 1]
+        : dir === 'y' ? [this.height, 0]   // inverted so y=0 → top
+        : [0, this.width]
+      this.scales[axisName] = scaleType === 'log'
+        ? d3.scaleLog().range(range)
+        : d3.scaleLinear().range(range)
       this.axisQuantityKinds[axisName] = axisQuantityKind
     }
     return this.scales[axisName]
@@ -34,55 +97,65 @@ export class AxisRegistry {
   getScale(axisName) { return this.scales[axisName] }
 
   isLogScale(axisName) {
-    const scale = this.scales[axisName]
-    return !!scale && typeof scale.base === 'function'
+    const s = this.scales[axisName]
+    return !!s && typeof s.base === 'function'
   }
 
   applyAutoDomainsFromLayers(layers, axesOverrides) {
     const autoDomains = {}
 
     for (const axis of AXES) {
-      const layersUsingAxis = layers.filter(l => l.xAxis === axis || l.yAxis === axis)
-      if (layersUsingAxis.length === 0) continue
+      const used = layers.filter(l => l.xAxis === axis || l.yAxis === axis || l.zAxis === axis)
+      if (used.length === 0) continue
 
       let min = Infinity, max = -Infinity
-      for (const layer of layersUsingAxis) {
-        const isXAxis = layer.xAxis === axis
-        const qk = isXAxis ? layer.xAxisQuantityKind : layer.yAxisQuantityKind
+      for (const layer of used) {
+        const qk = layer.xAxis === axis ? layer.xAxisQuantityKind
+          : layer.yAxis === axis        ? layer.yAxisQuantityKind
+          : layer.zAxisQuantityKind
         if (layer.domains[qk] !== undefined) {
           const [dMin, dMax] = layer.domains[qk]
           if (dMin < min) min = dMin
           if (dMax > max) max = dMax
-        } else {
-          const dataArray = isXAxis ? layer.attributes.x : layer.attributes.y
-          if (!dataArray) continue
-          for (let i = 0; i < dataArray.length; i++) {
-            const val = dataArray[i]
-            if (val < min) min = val
-            if (val > max) max = val
-          }
+        } else if (qk && !layer.type?.suppressWarnings) {
+          console.warn(
+            `[gladly] Layer type '${layer.type?.name ?? 'unknown'}' has no domain for ` +
+            `quantity kind '${qk}' on axis '${axis}'. ` +
+            `Auto-domain for this axis cannot be computed from this layer.`
+          )
         }
       }
-      if (min !== Infinity) autoDomains[axis] = [min, max]
+      if (min !== Infinity) {
+        if (!isFinite(min) || !isFinite(max))
+          throw new Error(`[gladly] Axis '${axis}': auto-computed domain [${min}, ${max}] is non-finite.`)
+        if (min === max)
+          console.warn(`[gladly] Axis '${axis}': auto-computed domain is degenerate (all data at ${min}).`)
+        autoDomains[axis] = [min, max]
+      }
     }
 
     for (const axis of AXES) {
       const scale = this.getScale(axis)
       if (!scale) continue
       const override = axesOverrides[axis]
-      const domain = override ? [override.min, override.max] : autoDomains[axis]
-      if (domain) scale.domain(domain)
+      const domain   = (override?.min != null && override?.max != null)
+        ? [override.min, override.max]
+        : autoDomains[axis]
+      if (domain) {
+        const [lo, hi] = domain
+        if (lo == null || hi == null || !isFinite(lo) || !isFinite(hi))
+          throw new Error(`[gladly] Axis '${axis}': domain [${lo}, ${hi}] contains null or non-finite values.`)
+        if (lo === hi)
+          console.warn(`[gladly] Axis '${axis}': domain [${lo}] is degenerate (min equals max).`)
+        scale.domain(domain)
+      }
     }
 
     for (const axis of AXES) {
       if (!this.isLogScale(axis)) continue
       const [dMin, dMax] = this.getScale(axis).domain()
-      if ((isFinite(dMin) && dMin <= 0) || (isFinite(dMax) && dMax <= 0)) {
-        throw new Error(
-          `Axis '${axis}' uses log scale but has non-positive domain [${dMin}, ${dMax}]. ` +
-          `All data values and min/max must be > 0 for log scale.`
-        )
-      }
+      if ((isFinite(dMin) && dMin <= 0) || (isFinite(dMax) && dMax <= 0))
+        throw new Error(`Axis '${axis}' uses log scale but has non-positive domain [${dMin}, ${dMax}].`)
     }
   }
 
@@ -90,12 +163,16 @@ export class AxisRegistry {
     const scale = this.scales[axisName]
     if (!scale) return
     const currentIsLog = typeof scale.base === 'function'
-    const wantLog = scaleType === "log"
+    const wantLog = scaleType === 'log'
     if (currentIsLog === wantLog) return
     const currentDomain = scale.domain()
+    const dir = AXIS_GEOMETRY[axisName].dir
+    const range = dir === 'z' ? [0, 1]
+      : dir === 'y' ? [this.height, 0]
+      : [0, this.width]
     const newScale = wantLog
-      ? d3.scaleLog().range(axisName.includes("y") ? [this.height, 0] : [0, this.width])
-      : d3.scaleLinear().range(axisName.includes("y") ? [this.height, 0] : [0, this.width])
+      ? d3.scaleLog().range(range)
+      : d3.scaleLinear().range(range)
     newScale.domain(currentDomain)
     this.scales[axisName] = newScale
   }

package/src/axes/Camera.js

@@ -0,0 +1,47 @@
+import {
+  mat4Identity, mat4Multiply, mat4Perspective, mat4LookAt,
+  sphericalToCartesian, vec3Normalize, vec3Cross,
+} from '../math/mat4.js'
+
+/**
+ * Camera manages the MVP matrix for the plot.
+ *
+ * In 2D mode (is3D=false): getMVP() returns the identity matrix.
+ * In 3D mode (is3D=true):  orbit camera (y-up) with perspective projection.
+ * Mouse interaction is handled by ZoomController.
+ */
+export class Camera {
+  constructor(is3D) {
+    this._is3D   = is3D
+    this._theta  = Math.PI / 4   // azimuth (rotation around y-axis)
+    this._phi    = Math.PI / 6   // elevation (clamped away from poles)
+    this._radius = 3.0
+    this._fov    = Math.PI / 4   // vertical field-of-view (45°)
+    this._aspect = 1.0           // width / height, updated by resize()
+  }
+
+  resize(width, height) {
+    this._aspect = width / height
+  }
+
+  // Returns the camera MVP matrix as a column-major Float32Array[16].
+  // In 2D mode this is the identity (data coordinates already map to NDC via domain uniforms).
+  getMVP() {
+    if (!this._is3D) return mat4Identity()
+    const eye  = sphericalToCartesian(this._theta, this._phi, this._radius)
+    const view = mat4LookAt(eye, [0, 0, 0], [0, 1, 0])
+    const proj = mat4Perspective(this._fov, this._aspect, 0.1, 100)
+    return mat4Multiply(proj, view)
+  }
+
+  // Returns the camera right and up unit vectors in world space.
+  // Used to orient billboard quads so they always face the camera.
+  getCameraVectors() {
+    if (!this._is3D) return { right: [1, 0, 0], up: [0, 1, 0] }
+    const eye = sphericalToCartesian(this._theta, this._phi, this._radius)
+    const fwd = vec3Normalize([-eye[0], -eye[1], -eye[2]])
+    const right = vec3Normalize(vec3Cross(fwd, [0, 1, 0]))
+    const up    = vec3Normalize(vec3Cross(right, fwd))
+    return { right, up }
+  }
+}

package/src/axes/ColorAxisRegistry.js

@@ -8,12 +8,16 @@ export class ColorAxisRegistry {
 
   ensureColorAxis(quantityKind, colorscaleOverride = null) {
     if (!this._axes.has(quantityKind)) {
-      this._axes.set(quantityKind, { colorscaleOverride, range: null })
+      this._axes.set(quantityKind, { colorscaleOverride, range: null, alphaBlend: 0.0 })
     } else if (colorscaleOverride !== null) {
       this._axes.get(quantityKind).colorscaleOverride = colorscaleOverride
     }
   }
 
+  getAlphaBlend(quantityKind) {
+    return this._axes.get(quantityKind)?.alphaBlend ?? 0.0
+  }
+
   setRange(quantityKind, min, max) {
     if (!this._axes.has(quantityKind)) {
       throw new Error(`Color axis '${quantityKind}' not found in registry`)
@@ -52,11 +56,13 @@ export class ColorAxisRegistry {
       const override = axesOverrides[quantityKind]
       if (override?.colorscale && override?.colorscale != "none")
         this.ensureColorAxis(quantityKind, override.colorscale)
+      if (override?.alpha_blend !== undefined)
+        this._axes.get(quantityKind).alphaBlend = override.alpha_blend
       
       let min = Infinity, max = -Infinity
 
       for (const layer of layers) {
-        for (const qk of layer.colorAxes) {
+        for (const qk of Object.values(layer.colorAxes)) {
           if (qk !== quantityKind) continue
           if (layer.domains[qk] !== undefined) {
             const [dMin, dMax] = layer.domains[qk]
@@ -75,6 +81,8 @@ export class ColorAxisRegistry {
 
       if (min !== Infinity) {
         this.setRange(quantityKind, override?.min ?? min, override?.max ?? max)
+      } else if (override?.min !== undefined && override?.max !== undefined) {
+        this.setRange(quantityKind, override.min, override.max)
       }
     }
 

package/src/axes/FilterAxisRegistry.js

@@ -65,7 +65,7 @@ export class FilterAxisRegistry {
       let extMin = Infinity, extMax = -Infinity
 
       for (const layer of layers) {
-        for (const qk of layer.filterAxes) {
+        for (const qk of Object.values(layer.filterAxes)) {
           if (qk !== quantityKind) continue
           if (layer.domains[qk] !== undefined) {
             const [dMin, dMax] = layer.domains[qk]

package/src/axes/TickLabelAtlas.js

@@ -0,0 +1,99 @@
+// Canvas-backed texture atlas for tick and axis title labels.
+// Labels are rendered with Canvas 2D and packed into a single GPU texture (shelf packing).
+// UV coordinates use the convention: v = canvas_y / ATLAS_SIZE (v=0 = canvas top).
+// The atlas texture is uploaded with flipY: false, so texture(sampler, (u,v)) samples
+// canvas pixel (u*W, v*H). Billboard quads use matching UV assignments.
+
+const ATLAS_SIZE  = 1024
+const FONT        = '12px sans-serif'
+const PADDING     = 2
+const ROW_HEIGHT  = 16   // fixed text-line height in pixels
+
+export class TickLabelAtlas {
+  constructor(regl) {
+    this._regl   = regl
+    this._canvas = null
+    this._ctx    = null
+    this._texture     = null
+    this._entries     = new Map()   // text → { u, v, uw, vh, pw, ph } | null (pending)
+    this._needsRebuild = false
+  }
+
+  // Mark a set of label strings as needed. Call before flush().
+  markLabels(labels) {
+    for (const l of labels) {
+      if (!this._entries.has(l)) {
+        this._entries.set(l, null)
+        this._needsRebuild = true
+      }
+    }
+  }
+
+  // Re-render the atlas canvas and re-upload the GPU texture if anything changed.
+  flush() {
+    if (!this._needsRebuild) return
+    this._needsRebuild = false
+
+    if (!this._canvas) {
+      this._canvas = document.createElement('canvas')
+      this._canvas.width  = ATLAS_SIZE
+      this._canvas.height = ATLAS_SIZE
+      this._ctx = this._canvas.getContext('2d')
+    }
+
+    const ctx = this._ctx
+    ctx.clearRect(0, 0, ATLAS_SIZE, ATLAS_SIZE)
+    ctx.font         = FONT
+    ctx.fillStyle    = '#000'
+    ctx.textBaseline = 'top'
+
+    const rowH = ROW_HEIGHT + PADDING * 2
+    let x = 0, y = 0
+
+    for (const label of this._entries.keys()) {
+      const metrics = ctx.measureText(label)
+      const pw = Math.ceil(metrics.width) + PADDING * 2
+      const ph = rowH
+
+      if (x + pw > ATLAS_SIZE) { x = 0; y += rowH }
+      if (y + ph > ATLAS_SIZE) {
+        console.warn('[gladly] TickLabelAtlas: atlas is full; some labels may be missing')
+        break
+      }
+
+      ctx.fillText(label, x + PADDING, y + PADDING)
+
+      this._entries.set(label, {
+        u:  x  / ATLAS_SIZE,
+        v:  y  / ATLAS_SIZE,
+        uw: pw / ATLAS_SIZE,
+        vh: ph / ATLAS_SIZE,
+        pw,
+        ph,
+      })
+      x += pw
+    }
+
+    // flipY: false — v = canvas_y / ATLAS_SIZE; v=0 samples canvas top.
+    if (!this._texture) {
+      this._texture = this._regl.texture({
+        width:  ATLAS_SIZE,
+        height: ATLAS_SIZE,
+        format: 'rgba',
+        mag:    'nearest',
+        min:    'nearest',
+        flipY:  false,
+      })
+    }
+    this._texture.subimage({ data: this._canvas, x: 0, y: 0, flipY: false })
+  }
+
+  // Returns the atlas entry for a label, or null if it hasn't been built yet.
+  getEntry(label) { return this._entries.get(label) ?? null }
+
+  get texture() { return this._texture }
+
+  destroy() {
+    if (this._texture) { this._texture.destroy(); this._texture = null }
+  }
+}