gladly-plot 0.0.4 → 0.0.6

package/src/compute/util.js

@@ -0,0 +1,196 @@
+import { registerTextureComputation, registerGlslComputation, EXPRESSION_REF } from "./ComputationRegistry.js"
+import { TextureComputation, GlslComputation } from "../data/Computation.js"
+import { GlslColumn } from "../data/ColumnData.js"
+
+// Shared helper: allocate an output texture + FBO and run a fullscreen quad.
+function runFullscreenQuad(regl, N, fragGlsl, uniforms = {}) {
+  const nTexels = Math.ceil(N / 4)
+  const w = Math.min(nTexels, regl.limits.maxTextureSize)
+  const h = Math.ceil(nTexels / w)
+  const outputTex = regl.texture({ width: w, height: h, type: 'float', format: 'rgba' })
+  const outputFBO = regl.framebuffer({ color: outputTex, depth: false, stencil: false })
+  regl({
+    framebuffer: outputFBO,
+    vert: `#version 300 es
+precision highp float;
+in vec2 a_position;
+void main() { gl_Position = vec4(a_position, 0.0, 1.0); }`,
+    frag: fragGlsl(w),
+    attributes: { a_position: [[-1, -1], [1, -1], [-1, 1], [1, 1]] },
+    uniforms,
+    count: 4,
+    primitive: 'triangle strip'
+  })()
+  outputTex._dataLength = N
+  return outputTex
+}
+
+// ─── linspace ─────────────────────────────────────────────────────────────────
+// Produces N values in ]0, 1[ : value[i] = (i + 0.5) / N  — fully on GPU.
+class LinspaceComputation extends TextureComputation {
+  compute(regl, inputs, _getAxisDomain) {
+    const N = inputs.length
+    return runFullscreenQuad(regl, N, w => `#version 300 es
+precision highp float;
+uniform int u_N;
+out vec4 fragColor;
+float linVal(int idx) { return (float(idx) + 0.5) / float(u_N); }
+void main() {
+  int texelI = int(gl_FragCoord.y) * ${w} + int(gl_FragCoord.x);
+  int base = texelI * 4;
+  fragColor = vec4(
+    base + 0 < u_N ? linVal(base + 0) : 0.0,
+    base + 1 < u_N ? linVal(base + 1) : 0.0,
+    base + 2 < u_N ? linVal(base + 2) : 0.0,
+    base + 3 < u_N ? linVal(base + 3) : 0.0
+  );
+}`, { u_N: N })
+  }
+
+  schema(_data) {
+    return {
+      type: 'object',
+      title: 'linspace',
+      properties: {
+        length: { type: 'integer', description: 'Number of values' }
+      },
+      required: ['length']
+    }
+  }
+}
+
+registerTextureComputation('linspace', new LinspaceComputation())
+
+// ─── range ────────────────────────────────────────────────────────────────────
+// Produces N integer values: 0, 1, 2, ..., N-1  — fully on GPU.
+class RangeComputation extends TextureComputation {
+  compute(regl, inputs, _getAxisDomain) {
+    const N = inputs.length
+    return runFullscreenQuad(regl, N, w => `#version 300 es
+precision highp float;
+uniform int u_N;
+out vec4 fragColor;
+void main() {
+  int texelI = int(gl_FragCoord.y) * ${w} + int(gl_FragCoord.x);
+  int base = texelI * 4;
+  fragColor = vec4(
+    base + 0 < u_N ? float(base + 0) : 0.0,
+    base + 1 < u_N ? float(base + 1) : 0.0,
+    base + 2 < u_N ? float(base + 2) : 0.0,
+    base + 3 < u_N ? float(base + 3) : 0.0
+  );
+}`, { u_N: N })
+  }
+
+  schema(_data) {
+    return {
+      type: 'object',
+      title: 'range',
+      properties: {
+        length: { type: 'integer', description: 'Number of values' }
+      },
+      required: ['length']
+    }
+  }
+}
+
+registerTextureComputation('range', new RangeComputation())
+
+// ─── glslExpr ─────────────────────────────────────────────────────────────────
+// A GlslComputation where the GLSL expression is a user-supplied string.
+// Named inputs are referenced in expr as {name} placeholders.
+//
+// Example:
+//   { glslExpr: { expr: "sin({x}) * {y}", inputs: { x: "col1", y: "col2" } } }
+class GlslExprComputation extends GlslComputation {
+  glsl(_resolvedExprs) { throw new Error('glslExpr: use createColumn, not glsl()') }
+
+  createColumn(inputs) {
+    const expr = inputs.expr       // raw string from user
+    const colInputs = inputs.inputs ?? {}
+    return new GlslColumn(colInputs, (resolvedExprs) => {
+      let result = expr
+      for (const [name, glslExpr] of Object.entries(resolvedExprs)) {
+        result = result.replaceAll(`{${name}}`, glslExpr)
+      }
+      return result
+    })
+  }
+
+  schema(data) {
+    return {
+      type: 'object',
+      title: 'glslExpr',
+      properties: {
+        expr: {
+          type: 'string',
+          description: 'GLSL expression; reference inputs as {name} placeholders'
+        },
+        inputs: {
+          type: 'object',
+          additionalProperties: EXPRESSION_REF,
+          description: 'Named input columns referenced in expr as {name}'
+        }
+      },
+      required: ['expr']
+    }
+  }
+}
+
+registerGlslComputation('glslExpr', new GlslExprComputation())
+
+// ─── random ───────────────────────────────────────────────────────────────────
+// Produces N pseudorandom values in ]0, 1[ derived from index ^ seed.
+// All computation is done on the GPU via a fullscreen quad render pass.
+// Hash: 3-round xorshift-multiply (good avalanche, no trig, GLSL ES 300).
+class RandomComputation extends TextureComputation {
+  compute(regl, inputs, _getAxisDomain) {
+    const N    = inputs.length
+    const seed = (inputs.seed || 0) === 0 ? (Math.random() * 0x7fffffff) | 0 : inputs.seed
+    return runFullscreenQuad(regl, N, w => `#version 300 es
+precision highp float;
+uniform int u_seed;
+uniform int u_N;
+out vec4 fragColor;
+
+uint uhash(uint x) {
+  x ^= x >> 17u;
+  x *= 0xbf324c81u;
+  x ^= x >> 11u;
+  x *= 0x68bc4b39u;
+  x ^= x >> 16u;
+  return x;
+}
+
+// Maps uint to ]0, 1[ : (bits + 0.5) / 2^24
+float randVal(int idx) {
+  uint h = uhash(uint(idx) ^ uint(u_seed));
+  return (float(h >> 8u) + 0.5) / 16777216.0;
+}
+
+void main() {
+  int texelI = int(gl_FragCoord.y) * ${w} + int(gl_FragCoord.x);
+  int base = texelI * 4;
+  fragColor = vec4(
+    base + 0 < u_N ? randVal(base + 0) : 0.0,
+    base + 1 < u_N ? randVal(base + 1) : 0.0,
+    base + 2 < u_N ? randVal(base + 2) : 0.0,
+    base + 3 < u_N ? randVal(base + 3) : 0.0
+  );
+}`, { u_seed: seed | 0, u_N: N })
+  }
+
+  schema(_data) {
+    return {
+      type: 'object',
+      title: 'random',
+      properties: {
+        length: { type: 'integer', description: 'Number of values' },
+        seed:   { type: 'integer', description: 'Integer seed (default 0)', default: 0 }
+      },
+      required: ['length']
+    }
+  }
+}
+
+registerTextureComputation('random', new RandomComputation())

package/src/core/ComputePipeline.js

@@ -0,0 +1,153 @@
+import { GlBase } from "./GlBase.js"
+import { FilterAxisRegistry } from "../axes/FilterAxisRegistry.js"
+import { DataGroup, normalizeData } from "../data/Data.js"
+import { ColumnData, ArrayColumn } from "../data/ColumnData.js"
+
+// Read a 4-packed RGBA float texture back to a flat Float32Array of length dataLength.
+function readTextureToArray(regl, texture) {
+  const dataLength = texture._dataLength ?? (texture.width * texture.height * 4)
+  const fbo = regl.framebuffer({ color: texture, depth: false })
+  let pixels
+  try {
+    regl({ framebuffer: fbo })(() => {
+      pixels = regl.read()
+    })
+  } finally {
+    fbo.destroy()
+  }
+  const arr = pixels instanceof Float32Array ? pixels : new Float32Array(pixels.buffer, pixels.byteOffset, pixels.byteLength / 4)
+  return arr.slice(0, dataLength)
+}
+
+// Wraps any ColumnData and adds getArray() for CPU readback.
+class ReadableColumn extends ColumnData {
+  constructor(col, regl) {
+    super()
+    this._col = col
+    this._regl = regl
+  }
+
+  get length()       { return this._col.length }
+  get domain()       { return this._col.domain }
+  get quantityKind() { return this._col.quantityKind }
+
+  resolve(path, regl) { return this._col.resolve(path, regl) }
+  toTexture(regl)     { return this._col.toTexture(regl) }
+  refresh(plot)       { return this._col.refresh(plot) }
+  withOffset(expr)    { return this._col.withOffset(expr) }
+
+  getArray() {
+    if (this._col instanceof ArrayColumn) return this._col.array
+    const tex = this._col.toTexture(this._regl)
+    return readTextureToArray(this._regl, tex)
+  }
+}
+
+// Output object returned by ComputePipeline.update().
+// Like DataGroup but getData() returns ReadableColumn with getArray(),
+// and getArrays() reads all columns to CPU at once.
+export class ComputeOutput {
+  constructor(dataGroup, regl) {
+    this._dataGroup = dataGroup
+    this._regl = regl
+  }
+
+  columns() {
+    return this._dataGroup.columns()
+  }
+
+  getData(col) {
+    const colData = this._dataGroup.getData(col)
+    if (!colData) return null
+    return new ReadableColumn(colData, this._regl)
+  }
+
+  getArrays() {
+    const result = {}
+    for (const col of this.columns()) {
+      const readable = this.getData(col)
+      if (readable) {
+        try {
+          result[col] = readable.getArray()
+        } catch (e) {
+          console.warn(`[gladly] ComputeOutput.getArrays(): failed to read column '${col}': ${e.message}`)
+        }
+      }
+    }
+    return result
+  }
+}
+
+// Headless GPU compute pipeline for running data transforms without any visual output.
+// Creates its own offscreen WebGL context; no DOM container needed.
+//
+// Usage:
+//   const pipeline = new ComputePipeline()
+//   const output = pipeline.update({ data, transforms, axes })
+//   const arr = output.getData('hist.counts').getArray()   // Float32Array
+//   const all = output.getArrays()                         // { 'hist.counts': Float32Array, ... }
+//   pipeline.destroy()
+export class ComputePipeline extends GlBase {
+  constructor() {
+    super()
+    const canvas = typeof OffscreenCanvas !== 'undefined'
+      ? new OffscreenCanvas(1, 1)
+      : document.createElement('canvas')
+    this._initRegl(canvas)
+    this.filterAxisRegistry = new FilterAxisRegistry()
+  }
+
+  // Runs the given transforms over data and returns a ComputeOutput.
+  //
+  // axes: { [quantityKind]: { min, max } } — sets filter axis ranges before computing.
+  // Transforms that access a filter axis will see the configured range.
+  async update({ data, transforms = [], axes = {} } = {}) {
+    const epoch = ++this._initEpoch
+
+    if (data !== undefined) {
+      this._rawData = normalizeData(data)
+    }
+
+    this._dataTransformNodes = []
+    this.filterAxisRegistry = new FilterAxisRegistry()
+
+    if (this._rawData != null) {
+      const fresh = new DataGroup({})
+      fresh._children = { ...this._rawData._children }
+      this.currentData = fresh
+    } else {
+      this.currentData = new DataGroup({})
+    }
+
+    // Run transforms; filter axes are registered and data extents set during this step.
+    // At this point filter ranges are all null (open bounds).
+    await this._processTransforms(transforms, epoch)
+    if (this._initEpoch !== epoch) return new ComputeOutput(this.currentData, this.regl)
+
+    // Apply axes config to set filter ranges on any registered filter axis.
+    for (const [axisId, axisConfig] of Object.entries(axes)) {
+      if (this.filterAxisRegistry.hasAxis(axisId)) {
+        this.filterAxisRegistry.setRange(
+          axisId,
+          axisConfig.min !== undefined ? axisConfig.min : null,
+          axisConfig.max !== undefined ? axisConfig.max : null
+        )
+      }
+    }
+
+    // Refresh transforms whose output depends on any filter axis that now has a range set.
+    for (const node of this._dataTransformNodes) {
+      await node.refreshIfNeeded(this)
+      if (this._initEpoch !== epoch) return new ComputeOutput(this.currentData, this.regl)
+    }
+
+    return new ComputeOutput(this.currentData, this.regl)
+  }
+
+  destroy() {
+    if (this.regl) {
+      this.regl.destroy()
+      this.regl = null
+    }
+  }
+}

package/src/core/GlBase.js

@@ -0,0 +1,141 @@
+import reglInit from "regl"
+import { FilterAxisRegistry } from "../axes/FilterAxisRegistry.js"
+import { Axis } from "../axes/Axis.js"
+import { DataGroup, ComputedDataNode } from "../data/Data.js"
+import { getComputedData } from "../compute/ComputationRegistry.js"
+
+export class GlBase {
+  constructor() {
+    this.regl = null
+    this.currentData = null
+    this._rawData = null
+    this._dataTransformNodes = []
+    this.filterAxisRegistry = null
+    this._axisCache = new Map()
+    this._axesProxy = null
+    this._initEpoch = 0
+  }
+
+  _initRegl(canvas) {
+    const gl = canvas.getContext('webgl2', { desynchronized: true })
+    if (!gl) throw new Error('WebGL 2.0 is required but not supported')
+
+    const origGetExtension = gl.getExtension.bind(gl)
+    gl.getExtension = (name) => {
+      const lname = name.toLowerCase()
+      const wgl2CoreExts = ['oes_texture_float', 'oes_texture_float_linear']
+      if (wgl2CoreExts.includes(lname)) return origGetExtension(name) ?? {}
+      if (lname === 'angle_instanced_arrays') {
+        return origGetExtension(name) ?? {
+          vertexAttribDivisorANGLE: gl.vertexAttribDivisor.bind(gl),
+          drawArraysInstancedANGLE: gl.drawArraysInstanced.bind(gl),
+          drawElementsInstancedANGLE: gl.drawElementsInstanced.bind(gl),
+          VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE: 0x88FE
+        }
+      }
+      return origGetExtension(name)
+    }
+
+    const GL_RGBA = 0x1908, GL_FLOAT = 0x1406, GL_RGBA32F = 0x8814
+    const origTexImage2D = gl.texImage2D.bind(gl)
+    gl.texImage2D = function (...args) {
+      if (args.length >= 8 && args[2] === GL_RGBA && args[7] === GL_FLOAT) {
+        args = [...args]
+        args[2] = GL_RGBA32F
+      }
+      return origTexImage2D(...args)
+    }
+
+    this.regl = reglInit({
+      gl,
+      extensions: ['OES_texture_float', 'EXT_color_buffer_float', 'ANGLE_instanced_arrays'],
+      optionalExtensions: ['OES_texture_float_linear'],
+    })
+  }
+
+  /**
+   * Returns a stable Axis instance for the given axis name, creating one on first access.
+   * The same instance is returned across update() calls so links survive updates.
+   *
+   * Usage: plot.axes.xaxis_bottom, pipeline.axes["velocity_ms"], etc.
+   */
+  get axes() {
+    if (!this._axesProxy) {
+      this._axesProxy = new Proxy(this._axisCache, {
+        get: (cache, name) => {
+          if (typeof name !== 'string') return undefined
+          if (!cache.has(name)) cache.set(name, new Axis(this, name))
+          return cache.get(name)
+        }
+      })
+    }
+    return this._axesProxy
+  }
+
+  _getAxis(name) {
+    if (!this._axisCache.has(name)) this._axisCache.set(name, new Axis(this, name))
+    return this._axisCache.get(name)
+  }
+
+  // For filter axes the axis ID is the quantity kind. Overridden by Plot for spatial axes.
+  getAxisQuantityKind(axisId) {
+    return axisId
+  }
+
+  // Default: filter axes only. Overridden by Plot to add spatial + color axes.
+  getAxisDomain(axisId) {
+    const filterRange = this.filterAxisRegistry?.getRange(axisId)
+    if (filterRange) return [filterRange.min, filterRange.max]
+    return null
+  }
+
+  // Default: filter axes only. Overridden by Plot to add spatial + color axes.
+  setAxisDomain(axisId, domain) {
+    if (this.filterAxisRegistry?.hasAxis(axisId)) {
+      this.filterAxisRegistry.setRange(axisId, domain[0], domain[1])
+    }
+  }
+
+  // No-op in base class. Overridden by Plot to schedule a WebGL render frame.
+  scheduleRender() {}
+
+  async _processTransforms(transforms, epoch) {
+    if (!transforms || transforms.length === 0) return
+
+    const TDR_STEP_MS = 500
+    for (const { name, transform: spec } of transforms) {
+      const entries = Object.entries(spec)
+      if (entries.length !== 1) throw new Error(`Transform '${name}' must have exactly one key`)
+      const [className, params] = entries[0]
+
+      const computedData = getComputedData(className)
+      if (!computedData) throw new Error(`Unknown computed data type: '${className}'`)
+
+      const filterAxes = computedData.filterAxes(params, this.currentData)
+      for (const quantityKind of Object.values(filterAxes)) {
+        this.filterAxisRegistry.ensureFilterAxis(quantityKind)
+      }
+
+      const node = new ComputedDataNode(computedData, params)
+      const stepStart = performance.now()
+      try {
+        await node._initialize(this.regl, this.currentData, this)
+      } catch (e) {
+        throw new Error(`Transform '${name}' (${className}) failed to initialize: ${e.message}`, { cause: e })
+      }
+      if (performance.now() - stepStart > TDR_STEP_MS)
+        await new Promise(r => requestAnimationFrame(r))
+      if (this._initEpoch !== epoch) return
+
+      const filterDataExtents = node._meta?.filterDataExtents ?? {}
+      for (const [qk, extent] of Object.entries(filterDataExtents)) {
+        if (this.filterAxisRegistry.hasAxis(qk)) {
+          this.filterAxisRegistry.setDataExtent(qk, extent[0], extent[1])
+        }
+      }
+
+      this.currentData._children[name] = node
+      this._dataTransformNodes.push(node)
+    }
+  }
+}

package/src/core/Layer.js

@@ -0,0 +1,59 @@
+export class Layer {
+  constructor({ type, attributes, uniforms, domains = {}, lineWidth = 1, primitive = "points", xAxis = "xaxis_bottom", yAxis = "yaxis_left", zAxis = null, xAxisQuantityKind, yAxisQuantityKind, zAxisQuantityKind, colorAxes = {}, colorAxes2d = {}, filterAxes = {}, vertexCount = null, instanceCount = null, attributeDivisors = {}, blend = null }) {
+    // Validate that all attributes are non-null/undefined
+    // (Float32Array, regl textures, numbers, and expression objects are all valid)
+    for (const [key, value] of Object.entries(attributes)) {
+      if (value == null) {
+        throw new Error(`Attribute '${key}' must not be null or undefined`)
+      }
+    }
+
+    // Validate colorAxes: must be a dict mapping GLSL name suffix to quantity kind string
+    for (const quantityKind of Object.values(colorAxes)) {
+      if (typeof quantityKind !== 'string') {
+        throw new Error(`Color axis quantity kind must be a string, got ${typeof quantityKind}`)
+      }
+    }
+
+    // Validate filterAxes: must be a dict mapping GLSL name suffix to quantity kind string
+    for (const quantityKind of Object.values(filterAxes)) {
+      if (typeof quantityKind !== 'string') {
+        throw new Error(`Filter axis quantity kind must be a string, got ${typeof quantityKind}`)
+      }
+    }
+
+    if (!type?.suppressWarnings) {
+      if (vertexCount !== null && vertexCount === 0) {
+        console.warn(`[gladly] Layer '${type?.name ?? 'unknown'}': vertexCount is 0 — this layer will draw nothing`)
+      }
+      if (instanceCount !== null && instanceCount === 0) {
+        console.warn(`[gladly] Layer '${type?.name ?? 'unknown'}': instanceCount is 0 — this layer will draw nothing`)
+      }
+    }
+
+    this.type = type
+    this.attributes = attributes
+    this.uniforms = uniforms
+    this.domains = domains
+    this.lineWidth = lineWidth
+    this.primitive = primitive
+    this.xAxis = xAxis
+    this.yAxis = yAxis
+    this.zAxis = zAxis
+    this.xAxisQuantityKind = xAxisQuantityKind
+    this.yAxisQuantityKind = yAxisQuantityKind
+    this.zAxisQuantityKind = zAxisQuantityKind
+    // colorAxes: Record<suffix, qk> — maps GLSL name suffix to quantity kind for each color axis
+    // e.g. { '': 'temperature_K' } or { '': 'temp_K', '2': 'pressure_Pa' }
+    this.colorAxes = colorAxes
+    // colorAxes2d: Record<suffix2d, [suffix1, suffix2]> — maps a 2D function name suffix to a pair
+    // of colorAxes suffixes; generates map_color_2d_SUFFIX(vec2) GLSL wrapper
+    this.colorAxes2d = colorAxes2d
+    // filterAxes: Record<suffix, qk> — maps GLSL name suffix to quantity kind for each filter axis
+    this.filterAxes = filterAxes
+    this.vertexCount = vertexCount
+    this.instanceCount = instanceCount
+    this.attributeDivisors = attributeDivisors
+    this.blend = blend
+  }
+}