gladly-plot 0.0.4 → 0.0.6

package/README.md

@@ -19,11 +19,18 @@ Gladly combines WebGL rendering (via regl) with D3.js for interactive axes and z
 - 🌈 Axis to coloring or filtering linking
 - 🌎 Basemap layer with XYZ,WMS and WMTS support and CRS reprojection
 
+## Extensions
+
+- **[gladly-jupyter](https://redhog.github.io/gladly-jupyter/)** - Jupyter notebook widget extension for Gladly
+
 ## Documentation
 
 - **[Quick Start](docs/Quickstart.md)** - Installation and minimal working example
-- **[API Documentation](docs/API.md)** - Complete API reference and usage guide
-- **[Architecture Documentation](docs/ARCHITECTURE.md)** - Developer guide and design patterns
+- **[Concepts](docs/concepts/Overview.md)** - Data model overview: axes, quantity kinds, colorscales, layer types, data format
+- **[Configuration](docs/configuration/overview.md)** - Plot configuration, layers, axes, colorscales, built-in computations
+- **[User API](docs/user-api/overview.md)** - Programmatic APIs for plots, axes, data, and computations
+- **[Extension API](docs/extension-api/overview.md)** - Writing custom layer types and computations
+- **[Architecture](docs/architecture/overview.md)** - Design patterns and module responsibilities
 
 ## Technology Stack
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gladly-plot",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "GPU-powered multi-axis plotting library with regl + d3",
   "type": "module",
   "exports": {
@@ -10,15 +10,14 @@
     "src"
   ],
   "scripts": {
-    "prepare": "node scripts/fix-numjs-wasm.js",
-    "dev": "parcel serve example/index.html --open",
-    "build:example": "parcel build example/index.html --dist-dir dist-example --public-url ./",
-    "preview": "npm run build:example && npx serve dist-example"
+    "dev": "npx serve . -l 1234",
+    "build:example": "bash scripts/build-example.sh",
+    "build:lib": "rollup -c"
   },
   "dependencies": {
     "d3": "^7.8.5",
     "proj4": "^2.15.0",
-    "projnames": "^0.0.2",
+    "projnames": "^0.0.4",
     "regl": "^2.1.0"
   },
   "browserslist": [
@@ -27,12 +26,12 @@
     "last 2 Firefox versions",
     "last 2 Safari versions"
   ],
-
   "devDependencies": {
-    "@jayce789/numjs": "^2.2.6",
     "@json-editor/json-editor": "^2.15.1",
-    "parcel": "^2.9.0",
-    "process": "^0.11.10",
-    "url": "^0.11.4"
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.1",
+    "@rollup/plugin-terser": "^1.0.0",
+    "rollup": "^4.59.1"
   }
 }

package/src/axes/Axis.js

@@ -0,0 +1,401 @@
+import { AXIS_GEOMETRY, axisEndpoints, axisPosAtN } from "./AxisRegistry.js"
+import { getAxisQuantityKind } from "./AxisQuantityKindRegistry.js"
+import { projectToScreen } from "../math/mat4.js"
+
+// ─── Tick formatting (same logic as before) ───────────────────────────────────
+
+function formatTick(v) {
+  if (v === 0) return "0"
+  const abs = Math.abs(v)
+  if (abs >= 10000 || abs < 0.01) {
+    return v.toExponential(2).replace(/\.?0+(e)/, '$1')
+  }
+  const s = v.toPrecision(4)
+  if (s.includes('.') && !s.includes('e')) return s.replace(/\.?0+$/, '')
+  return s
+}
+
+function logTickValues(scale, count) {
+  const [dMin, dMax] = scale.domain()
+  if (dMin <= 0 || dMax <= 0) return null
+  const logMin = Math.log10(dMin), logMax = Math.log10(dMax)
+  const startExp = Math.floor(logMin), endExp = Math.ceil(logMax)
+  const candidate = []
+  for (let e = startExp; e < endExp; e++) {
+    const base = Math.pow(10, e)
+    for (const mult of [1, 2, 5]) {
+      const v = base * mult
+      if (v >= dMin * (1 - 1e-10) && v <= dMax * (1 + 1e-10)) candidate.push(v)
+    }
+  }
+  const upperPow = Math.pow(10, endExp)
+  if (upperPow >= dMin * (1 - 1e-10) && upperPow <= dMax * (1 + 1e-10)) candidate.push(upperPow)
+  if (candidate.length >= 2 && candidate.length <= count) return candidate
+  const firstExp = Math.ceil(logMin), lastExp = Math.floor(logMax)
+  if (firstExp > lastExp) return candidate.length >= 2 ? candidate : null
+  const numPowers = lastExp - firstExp + 1
+  const step = numPowers > count ? Math.ceil(numPowers / count) : 1
+  const powers = []
+  for (let e = firstExp; e <= lastExp; e += step) powers.push(Math.pow(10, e))
+  return powers.length >= 2 ? powers : null
+}
+
+// Normalise a data value to [0,1] within its domain (matches GLSL normalize_axis).
+function normaliseValue(v, domain, isLog) {
+  const vt = isLog ? Math.log(v)        : v
+  const d0 = isLog ? Math.log(domain[0]) : domain[0]
+  const d1 = isLog ? Math.log(domain[1]) : domain[1]
+  return (vt - d0) / (d1 - d0)
+}
+
+// ─── Tick mark / label geometry constants ─────────────────────────────────────
+// 3D: fixed model-space offsets (legacy behaviour)
+const TICK_LEN_3D   = 0.05
+const LABEL_DIST_3D = 0.12
+const TITLE_EXTRA_3D = 0.14   // extra outward offset for axis title beyond LABEL_DIST_3D
+const TITLE_LINE_STEP_3D = 0.05  // multi-line title step in model space
+
+// 2D: fractions of the pixel distance from the axis to the nearest canvas edge
+const TICK_LEN_FRAC          = 0.12
+const TICK_LABEL_FRAC        = 0.40
+const AXIS_TITLE_FRAC        = 0.75
+const TITLE_LINE_SPACING_FRAC = 0.12
+
+/**
+ * An Axis represents a single data axis on a plot.
+ *
+ * Public interface (unchanged from before):
+ *   axis.quantityKind, axis.isSpatial, axis.getDomain(), axis.setDomain(),
+ *   axis.subscribe(), axis.unsubscribe()
+ *
+ * Rendering is now entirely WebGL-based. Call axis.render() from Plot.render().
+ */
+export class Axis {
+  constructor(plot, name) {
+    this._plot        = plot
+    this._name        = name
+    this._listeners   = new Set()
+    this._linkedAxes  = new Set()
+    this._propagating = false
+  }
+
+  get quantityKind() { return this._plot.getAxisQuantityKind(this._name) }
+
+  // True for all 12 spatial axes; false for colour/filter axes.
+  get isSpatial() { return Object.prototype.hasOwnProperty.call(AXIS_GEOMETRY, this._name) }
+
+  getDomain() { return this._plot.getAxisDomain(this._name) }
+
+  setDomain(domain, { sourcePlot = null } = {}) {
+    if (this._propagating) return
+    this._propagating = true
+    try {
+      this._plot.setAxisDomain(this._name, domain)
+      this._plot.scheduleRender(sourcePlot)
+      for (const cb of this._listeners) cb(domain)
+    } finally {
+      this._propagating = false
+    }
+  }
+
+  subscribe(callback)   { this._listeners.add(callback) }
+  unsubscribe(callback) { this._listeners.delete(callback) }
+
+  // ─── WebGL rendering ───────────────────────────────────────────────────────
+
+  // Pre-pass: mark all labels this axis needs into the atlas (no flush).
+  // Called by Plot.render() for all axes before the single atlas.flush().
+  prepareAtlas(atlas, axisMvp, cw, ch) {
+    if (!this.isSpatial) return
+    const { axisRegistry, currentConfig } = this._plot
+    if (currentConfig?.axes?.[this._name]?.visible === false) return
+    const scale = axisRegistry.getScale(this._name)
+    if (!scale) return
+
+    const screenLen = this._projectedLength(axisMvp, cw, ch)
+    const pxPerTick = AXIS_GEOMETRY[this._name].dir === 'y' ? 27 : 40
+    const tickCount = Math.max(2, Math.floor(screenLen / pxPerTick))
+    const ticks     = this._computeTicks(scale, tickCount)
+    atlas.markLabels(ticks.map(t => formatTick(t)))
+
+    const qk = axisRegistry.axisQuantityKinds[this._name]
+    if (qk) {
+      const axisConfig = currentConfig?.axes?.[this._name] ?? {}
+      const unitLabel  = axisConfig.label ?? getAxisQuantityKind(qk).label
+      if (unitLabel) atlas.markLabels(String(unitLabel).split('\n'))
+    }
+  }
+
+  // Compute the approximate projected screen length of this axis (for tick density).
+  _projectedLength(axisMvp, cw, ch) {
+    const { start, end } = axisEndpoints(this._name)
+    const s = projectToScreen(start, axisMvp, cw, ch)
+    const e = projectToScreen(end,   axisMvp, cw, ch)
+    if (!s || !e) return 0
+    const dx = e[0] - s[0], dy = e[1] - s[1]
+    return Math.sqrt(dx * dx + dy * dy)
+  }
+
+  // Returns tick values as an array of numbers.
+  _computeTicks(scale, count) {
+    const isLog = typeof scale.base === 'function'
+    if (isLog) {
+      const tv = logTickValues(scale, count)
+      if (tv !== null) return tv
+    }
+    if (count <= 2) return scale.domain()
+    return scale.ticks(count)
+  }
+
+  // Returns the outward screen-space unit direction [dx, dy] (HTML coords, y down).
+  _outwardScreenDir(axisMvp, cw, ch) {
+    const { start, end } = axisEndpoints(this._name)
+    const mid3D  = [(start[0]+end[0])/2, (start[1]+end[1])/2, (start[2]+end[2])/2]
+    const ow = AXIS_GEOMETRY[this._name].outward
+    const tip3D  = [mid3D[0] + ow[0]*0.2, mid3D[1] + ow[1]*0.2, mid3D[2] + ow[2]*0.2]
+    const midS = projectToScreen(mid3D, axisMvp, cw, ch)
+    const tipS = projectToScreen(tip3D, axisMvp, cw, ch)
+    if (!midS || !tipS) return [0, 1]
+    const dx = tipS[0] - midS[0], dy = tipS[1] - midS[1]
+    const len = Math.sqrt(dx*dx + dy*dy)
+    return len > 0.5 ? [dx/len, dy/len] : [0, 1]
+  }
+
+  // Greedy screen-space overlap rejection. Returns an array of indices into `ticks`
+  // that can be rendered without their label boxes overlapping.
+  _visibleTickIndices(ticks, screenPositions, tickLabelAtlas) {
+    const accepted = [], boxes = []
+    for (let i = 0; i < ticks.length; i++) {
+      const sp = screenPositions[i]
+      if (!sp) continue
+      const label = formatTick(ticks[i])
+      const entry = tickLabelAtlas.getEntry(label)
+      const pw = entry ? entry.pw : 48, ph = entry ? entry.ph : 16
+      const box = [sp[0] - pw/2, sp[1] - ph/2, sp[0] + pw/2, sp[1] + ph/2]
+      if (boxes.some(b => box[0] < b[2] && box[2] > b[0] && box[1] < b[3] && box[3] > b[1])) continue
+      accepted.push(i)
+      boxes.push(box)
+    }
+    return accepted
+  }
+
+  /**
+   * Render this axis using the shared WebGL draw commands supplied by Plot.
+   *
+   * @param {object} regl          - regl instance
+   * @param {Float32Array} axisMvp - MVP that maps model space to full-canvas NDC
+   * @param {number} cw            - canvas width in pixels
+   * @param {number} ch            - canvas height in pixels
+   * @param {boolean} is3D         - enables depth testing (3D) vs always-on-top (2D)
+   * @param {TickLabelAtlas} atlas - shared label atlas
+   * @param {Function} lineCmd     - compiled regl command for axis/tick lines
+   * @param {Function} billboardCmd- compiled regl command for label billboards
+   */
+  render(regl, axisMvp, cw, ch, is3D, atlas, lineCmd, billboardCmd) {
+    if (!this.isSpatial) return
+    const { axisRegistry, currentConfig } = this._plot
+    if (currentConfig?.axes?.[this._name]?.visible === false) return
+    const scale = axisRegistry.getScale(this._name)
+    if (!scale) return
+
+    const geom   = AXIS_GEOMETRY[this._name]
+    const isLog  = typeof scale.base === 'function'
+    const domain = scale.domain()
+    const { start, end } = axisEndpoints(this._name)
+    const ow = geom.outward   // [ox, oy, oz]
+
+    // ── 0. Outward screen direction + model-space offset resolution ──────────
+    const mid3D = [(start[0]+end[0])/2, (start[1]+end[1])/2, (start[2]+end[2])/2]
+    const tip3D = [mid3D[0]+ow[0]*0.2, mid3D[1]+ow[1]*0.2, mid3D[2]+ow[2]*0.2]
+    const midS  = projectToScreen(mid3D, axisMvp, cw, ch)
+    const tipS  = projectToScreen(tip3D, axisMvp, cw, ch)
+    const outDirVec = (midS && tipS) ? [tipS[0]-midS[0], tipS[1]-midS[1]] : [0, 1]
+    const outDirLen = Math.sqrt(outDirVec[0]**2 + outDirVec[1]**2)
+    const outDir    = outDirLen > 0.5 ? [outDirVec[0]/outDirLen, outDirVec[1]/outDirLen] : [0, 1]
+    const pxPerModelUnit = outDirLen / 0.2
+
+    let tickModelLen, labelModelDist, titleModelDist, titleLineStep
+    if (!is3D && midS && pxPerModelUnit > 0) {
+      // In 2D: make all offsets proportional to the pixel distance from the axis
+      // to the nearest canvas edge (i.e. the margin width in pixels).
+      const tx = outDir[0] > 1e-6 ? (cw - midS[0]) / outDir[0]
+               : outDir[0] < -1e-6 ? -midS[0]        / outDir[0]
+               : Infinity
+      const ty = outDir[1] > 1e-6 ? (ch - midS[1]) / outDir[1]
+               : outDir[1] < -1e-6 ? -midS[1]        / outDir[1]
+               : Infinity
+      const distToEdge = Math.max(4, Math.min(tx, ty))
+      const scale2d    = distToEdge / pxPerModelUnit
+      tickModelLen   = TICK_LEN_FRAC          * scale2d
+      labelModelDist = TICK_LABEL_FRAC        * scale2d
+      titleModelDist = AXIS_TITLE_FRAC        * scale2d
+      titleLineStep  = TITLE_LINE_SPACING_FRAC * scale2d
+    } else {
+      // In 3D: fixed model-space offsets (original behaviour).
+      tickModelLen   = TICK_LEN_3D
+      labelModelDist = LABEL_DIST_3D
+      titleModelDist = LABEL_DIST_3D + TITLE_EXTRA_3D
+      titleLineStep  = TITLE_LINE_STEP_3D
+    }
+
+    // ── 1. Tick count based on projected screen length ──────────────────────
+    const screenLen   = this._projectedLength(axisMvp, cw, ch)
+    const pxPerTick   = geom.dir === 'y' ? 27 : 40
+    const tickCount   = Math.max(2, Math.floor(screenLen / pxPerTick))
+    const ticks       = this._computeTicks(scale, tickCount)
+
+    // ── 2. Build axis line + tick-mark geometry ─────────────────────────────
+    // Each pair of consecutive floats = one endpoint of a line segment (primitive: 'lines').
+    const lineVerts = []
+
+    // Main axis line
+    lineVerts.push(...start, ...end)
+
+    // Tick marks
+    for (const t of ticks) {
+      const n = normaliseValue(t, domain, isLog)
+      if (!isFinite(n)) continue
+      const pos = axisPosAtN(this._name, n)
+      lineVerts.push(
+        pos[0],                    pos[1],                    pos[2],
+        pos[0] + ow[0]*tickModelLen, pos[1] + ow[1]*tickModelLen, pos[2] + ow[2]*tickModelLen,
+      )
+    }
+
+    const fullViewport = { x: 0, y: 0, width: cw, height: ch }
+
+    lineCmd({
+      positions: new Float32Array(lineVerts),
+      mvp:       axisMvp,
+      color:     [0, 0, 0, 1],
+      viewport:  fullViewport,
+      count:     lineVerts.length / 3,
+      depthEnable: is3D,
+    })
+
+    // ── 3. Tick labels ──────────────────────────────────────────────────────
+    const labels = ticks.map(t => formatTick(t))
+
+    if (!atlas.texture) return
+
+    // Compute label anchor positions in model space and project to screen.
+    const anchors3D = ticks.map((t) => {
+      const n = normaliseValue(t, domain, isLog)
+      if (!isFinite(n)) return null
+      const pos = axisPosAtN(this._name, n)
+      return [pos[0] + ow[0]*labelModelDist, pos[1] + ow[1]*labelModelDist, pos[2] + ow[2]*labelModelDist]
+    })
+    const screenPositions = anchors3D.map(a => a ? projectToScreen(a, axisMvp, cw, ch) : null)
+
+    const visIdx = this._visibleTickIndices(ticks, screenPositions, atlas)
+
+    // Build billboard vertex arrays.
+    const aAnchor = [], aOffsetPx = [], aUV = []
+
+    for (const i of visIdx) {
+      const anchor3D = anchors3D[i]
+      if (!anchor3D) continue
+      const entry = atlas.getEntry(labels[i])
+      if (!entry) continue
+      const { pw, ph, u, v, uw, vh } = entry
+      const hw = pw / 2, hh = ph / 2
+      // 6 vertices (2 triangles): TL TR BL   TR BR BL
+      const corners = [
+        [-hw, -hh, u,    v   ],
+        [+hw, -hh, u+uw, v   ],
+        [-hw, +hh, u,    v+vh],
+        [+hw, -hh, u+uw, v   ],
+        [+hw, +hh, u+uw, v+vh],
+        [-hw, +hh, u,    v+vh],
+      ]
+      for (const [ox, oy, tu, tv] of corners) {
+        aAnchor.push(...anchor3D)
+        aOffsetPx.push(ox, oy)
+        aUV.push(tu, tv)
+      }
+    }
+
+    if (aAnchor.length > 0) {
+      billboardCmd({
+        anchors:    new Float32Array(aAnchor),
+        offsetsPx:  new Float32Array(aOffsetPx),
+        uvs:        new Float32Array(aUV),
+        mvp:        axisMvp,
+        canvasSize: [cw, ch],
+        atlas:      atlas.texture,
+        viewport:   fullViewport,
+        count:      aAnchor.length / 3,
+        depthEnable: is3D,
+      })
+    }
+
+    // ── 4. Axis title ───────────────────────────────────────────────────────
+    const qk        = axisRegistry.axisQuantityKinds[this._name]
+    if (!qk) return
+    const axisConfig = currentConfig?.axes?.[this._name] ?? {}
+    const unitLabel  = axisConfig.label ?? getAxisQuantityKind(qk).label
+    if (!unitLabel) return
+
+    const titleLines = String(unitLabel).split('\n')
+
+    // Place title at axis midpoint + larger outward offset
+    const titleAnchorBase = [
+      mid3D[0] + ow[0] * titleModelDist,
+      mid3D[1] + ow[1] * titleModelDist,
+      mid3D[2] + ow[2] * titleModelDist,
+    ]
+
+    const titleAnchor = [], titleOffsets = [], titleUVs = []
+    let lineOffset = 0
+    for (const line of titleLines) {
+      const entry = atlas.getEntry(line)
+      if (!entry) continue
+      const { pw, ph, u, v, uw, vh } = entry
+      const hw = pw / 2, hh = ph / 2
+      // Shift successive lines along the outward screen direction
+      const anchor3D = [
+        titleAnchorBase[0] + ow[0]*lineOffset,
+        titleAnchorBase[1] + ow[1]*lineOffset,
+        titleAnchorBase[2] + ow[2]*lineOffset,
+      ]
+      const rawCorners = [
+        [-hw, -hh, u,    v   ],
+        [+hw, -hh, u+uw, v   ],
+        [-hw, +hh, u,    v+vh],
+        [+hw, -hh, u+uw, v   ],
+        [+hw, +hh, u+uw, v+vh],
+        [-hw, +hh, u,    v+vh],
+      ]
+      // Rotate the title 90° CW when the axis is more vertical than horizontal
+      // in screen space (works for 2D and 3D).  Rotation: (ox, oy) → (oy, -ox)
+      const sStart = projectToScreen(start, axisMvp, cw, ch)
+      const sEnd   = projectToScreen(end,   axisMvp, cw, ch)
+      const axisDx = sEnd ? sEnd[0] - sStart[0] : 0
+      const axisDy = sEnd ? sEnd[1] - sStart[1] : 0
+      const isVertical = Math.abs(axisDy) > Math.abs(axisDx)
+      const corners = isVertical
+        ? rawCorners.map(([ox, oy, tu, tv]) => [oy, -ox, tu, tv])
+        : rawCorners
+      for (const [ox, oy, tu, tv] of corners) {
+        titleAnchor.push(...anchor3D)
+        titleOffsets.push(ox, oy)
+        titleUVs.push(tu, tv)
+      }
+      lineOffset += titleLineStep  // shift next line further out in model space
+    }
+
+    if (titleAnchor.length > 0) {
+      billboardCmd({
+        anchors:    new Float32Array(titleAnchor),
+        offsetsPx:  new Float32Array(titleOffsets),
+        uvs:        new Float32Array(titleUVs),
+        mvp:        axisMvp,
+        canvasSize: [cw, ch],
+        atlas:      atlas.texture,
+        viewport:   fullViewport,
+        count:      titleAnchor.length / 3,
+        depthEnable: is3D,
+      })
+    }
+  }
+}

package/src/{AxisLink.js → axes/AxisLink.js}

@@ -16,16 +16,20 @@ export function linkAxes(axis1, axis2) {
     throw new Error(`Cannot link axes with incompatible quantity kinds: ${qk1} vs ${qk2}`)
   }
 
-  const cb1 = (domain) => axis2.setDomain(domain)
-  const cb2 = (domain) => axis1.setDomain(domain)
+  const cb1 = (domain) => axis2.setDomain(domain, { sourcePlot: axis1._plot })
+  const cb2 = (domain) => axis1.setDomain(domain, { sourcePlot: axis2._plot })
 
   axis1.subscribe(cb1)
   axis2.subscribe(cb2)
+  axis1._linkedAxes.add(axis2)
+  axis2._linkedAxes.add(axis1)
 
   return {
     unlink() {
       axis1.unsubscribe(cb1)
       axis2.unsubscribe(cb2)
+      axis1._linkedAxes.delete(axis2)
+      axis2._linkedAxes.delete(axis1)
     }
   }
 }

package/src/{AxisQuantityKindRegistry.js → axes/AxisQuantityKindRegistry.js}

@@ -21,3 +21,10 @@ export function getAxisQuantityKind(name) {
 export function getRegisteredAxisQuantityKinds() {
   return Array.from(registry.keys())
 }
+
+// Returns 1.0 for log scale, 0.0 for linear. axesConfig is the `axes` sub-object of plot config.
+export function getScaleTypeFloat(quantityKind, axesConfig) {
+  const configScale = axesConfig?.[quantityKind]?.scale
+  const defScale = getAxisQuantityKind(quantityKind).scale
+  return (configScale ?? defScale) === "log" ? 1.0 : 0.0
+}

package/src/axes/AxisRegistry.js

@@ -0,0 +1,179 @@
+import * as d3 from "d3-scale"
+import { getAxisQuantityKind } from "./AxisQuantityKindRegistry.js"
+
+// 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.height = height
+    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 (this.axisQuantityKinds[axisName] && this.axisQuantityKinds[axisName] !== axisQuantityKind)
+      throw new Error(`Axis quantity kind mismatch on '${axisName}': ${this.axisQuantityKinds[axisName]} vs ${axisQuantityKind}`)
+
+    if (!this.scales[axisName]) {
+      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]
+  }
+
+  getScale(axisName) { return this.scales[axisName] }
+
+  isLogScale(axisName) {
+    const s = this.scales[axisName]
+    return !!s && typeof s.base === 'function'
+  }
+
+  applyAutoDomainsFromLayers(layers, axesOverrides) {
+    const autoDomains = {}
+
+    for (const axis of AXES) {
+      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 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 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) {
+        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?.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}].`)
+    }
+  }
+
+  setScaleType(axisName, scaleType) {
+    const scale = this.scales[axisName]
+    if (!scale) return
+    const currentIsLog = typeof scale.base === 'function'
+    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(range)
+      : d3.scaleLinear().range(range)
+    newScale.domain(currentDomain)
+    this.scales[axisName] = newScale
+  }
+}