gladly-plot 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egil Möller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# Gladly
+
+A lightweight, GPU-accelerated plotting library with a declarative API.
+
+## Overview
+
+Gladly combines WebGL rendering (via regl) with D3.js for interactive axes and zoom controls. It features a **declarative API** that lets you create high-performance plots with minimal boilerplate.
+
+**Key Features:**
+- 🚀 GPU-accelerated rendering using WebGL
+- 💨 Zero JavaScript loops over data - all processing in GPU shaders
+- 📊 Declarative plot configuration
+- 🎯 Interactive multi-axis support (up to 4 axes)
+- 🔍 Zoom and pan interactions
+- 🧩 Extensible layer type registry
+- 📏 Unit-aware axis management
+- ⚡ ~250 lines of focused source code
+
+## 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
+
+## Technology Stack
+
+- **WebGL Rendering**: regl v2.1.0
+- **Axes & Interaction**: D3.js v7.8.5
+- **Module Format**: ES6 modules
+- **Build Tool**: Parcel v2.9.0
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "gladly-plot",
+  "version": "0.0.1",
+  "description": "GPU-powered multi-axis plotting library with regl + d3",
+  "type": "module",
+
+  "exports": {
+    ".": "./src/index.js"
+  },
+
+  "files": ["src"],
+
+  "scripts": {
+    "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"
+  },
+
+  "dependencies": {
+    "d3": "^7.8.5",
+    "regl": "^2.1.0"
+  },
+
+  "devDependencies": {
+    "parcel": "^2.9.0",
+    "@json-editor/json-editor": "^2.15.1"
+  }
+}

package/src/Axis.js

@@ -0,0 +1,48 @@
+/**
+ * An Axis represents a single data axis on a plot. Axis instances are stable across
+ * plot.update() calls and can be linked together with linkAxes().
+ *
+ * Public interface (duck-typing compatible):
+ *   - axis.quantityKind   — string | null
+ *   - axis.getDomain()    — [min, max] | null
+ *   - axis.setDomain(domain) — update domain, schedule render, notify subscribers
+ *   - axis.subscribe(callback)   — callback([min, max]) called on domain changes
+ *   - axis.unsubscribe(callback) — remove a previously added callback
+ */
+export class Axis {
+  constructor(plot, name) {
+    this._plot = plot
+    this._name = name
+    this._listeners = new Set()
+    this._propagating = false
+  }
+
+  /** The quantity kind for this axis, or null if the plot hasn't been initialized yet. */
+  get quantityKind() { return this._plot.getAxisQuantityKind(this._name) }
+
+  /** Returns [min, max], or null if the axis has no domain yet. */
+  getDomain() { return this._plot.getAxisDomain(this._name) }
+
+  /**
+   * Sets the axis domain, schedules a render on the owning plot, and notifies all
+   * subscribers (e.g. linked axes). A _propagating guard prevents infinite loops
+   * when axes are linked bidirectionally.
+   */
+  setDomain(domain) {
+    if (this._propagating) return
+    this._propagating = true
+    try {
+      this._plot.setAxisDomain(this._name, domain)
+      this._plot.scheduleRender()
+      for (const cb of this._listeners) cb(domain)
+    } finally {
+      this._propagating = false
+    }
+  }
+
+  /** Add a subscriber. callback([min, max]) is called after every setDomain(). */
+  subscribe(callback) { this._listeners.add(callback) }
+
+  /** Remove a previously added subscriber. */
+  unsubscribe(callback) { this._listeners.delete(callback) }
+}

package/src/AxisLink.js

@@ -0,0 +1,31 @@
+/**
+ * Links two Axis (or duck-typed axis) objects bidirectionally.
+ *
+ * When either axis's domain changes via setDomain(), the other is updated to match.
+ * Quantity kinds are validated at link time if both are known.
+ *
+ * Returns an object with an unlink() method to tear down the link.
+ *
+ * Any object that implements the Axis interface may be used:
+ *   { quantityKind, getDomain(), setDomain(domain), subscribe(cb), unsubscribe(cb) }
+ */
+export function linkAxes(axis1, axis2) {
+  const qk1 = axis1.quantityKind
+  const qk2 = axis2.quantityKind
+  if (qk1 && qk2 && qk1 !== qk2) {
+    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)
+
+  axis1.subscribe(cb1)
+  axis2.subscribe(cb2)
+
+  return {
+    unlink() {
+      axis1.unsubscribe(cb1)
+      axis2.unsubscribe(cb2)
+    }
+  }
+}

package/src/AxisQuantityKindRegistry.js

@@ -0,0 +1,23 @@
+const registry = new Map()
+
+export function registerAxisQuantityKind(name, definition) {
+  if (registry.has(name)) {
+    // Merge new properties into existing definition
+    const existing = registry.get(name)
+    registry.set(name, { ...existing, ...definition })
+  } else {
+    registry.set(name, definition)
+  }
+}
+
+export function getAxisQuantityKind(name) {
+  if (!registry.has(name)) {
+    // Return a temporary default definition without registering it
+    return { label: name, scale: "linear" }
+  }
+  return registry.get(name)
+}
+
+export function getRegisteredAxisQuantityKinds() {
+  return Array.from(registry.keys())
+}

package/src/AxisRegistry.js

@@ -0,0 +1,54 @@
+import * as d3 from "d3-scale"
+import { getAxisQuantityKind } from "./AxisQuantityKindRegistry.js"
+
+export const AXES = ["xaxis_bottom","xaxis_top","yaxis_left","yaxis_right"]
+
+export class AxisRegistry {
+  constructor(width, height) {
+    this.scales = {}
+    this.axisQuantityKinds = {}
+    this.width = width
+    this.height = height
+    AXES.forEach(a => {
+      this.scales[a] = null
+      this.axisQuantityKinds[a] = null
+    })
+  }
+
+  ensureAxis(axisName, axisQuantityKind, scaleOverride) {
+    if (!AXES.includes(axisName)) throw `Unknown axis ${axisName}`
+    if (this.axisQuantityKinds[axisName] && this.axisQuantityKinds[axisName] !== axisQuantityKind)
+      throw `Axis quantity kind mismatch on axis ${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])
+      this.axisQuantityKinds[axisName] = axisQuantityKind
+    }
+    return this.scales[axisName]
+  }
+
+  getScale(axisName) { return this.scales[axisName] }
+
+  isLogScale(axisName) {
+    const scale = this.scales[axisName]
+    return !!scale && typeof scale.base === 'function'
+  }
+
+  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 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])
+    newScale.domain(currentDomain)
+    this.scales[axisName] = newScale
+  }
+}

package/src/ColorAxisRegistry.js

@@ -0,0 +1,49 @@
+import { getAxisQuantityKind } from './AxisQuantityKindRegistry.js'
+import { getColorscaleIndex } from './ColorscaleRegistry.js'
+
+export class ColorAxisRegistry {
+  constructor() {
+    this._axes = new Map()
+  }
+
+  ensureColorAxis(quantityKind, colorscaleOverride = null) {
+    if (!this._axes.has(quantityKind)) {
+      this._axes.set(quantityKind, { colorscaleOverride, range: null })
+    } else if (colorscaleOverride !== null) {
+      this._axes.get(quantityKind).colorscaleOverride = colorscaleOverride
+    }
+  }
+
+  setRange(quantityKind, min, max) {
+    if (!this._axes.has(quantityKind)) {
+      throw new Error(`Color axis '${quantityKind}' not found in registry`)
+    }
+    this._axes.get(quantityKind).range = [min, max]
+  }
+
+  getRange(quantityKind) {
+    return this._axes.get(quantityKind)?.range ?? null
+  }
+
+  getColorscale(quantityKind) {
+    const entry = this._axes.get(quantityKind)
+    if (!entry) return null
+    if (entry.colorscaleOverride) return entry.colorscaleOverride
+    const unitDef = getAxisQuantityKind(quantityKind)
+    return unitDef.colorscale ?? null
+  }
+
+  getColorscaleIndex(quantityKind) {
+    const colorscale = this.getColorscale(quantityKind)
+    if (colorscale === null) return 0
+    return getColorscaleIndex(colorscale)
+  }
+
+  hasAxis(quantityKind) {
+    return this._axes.has(quantityKind)
+  }
+
+  getQuantityKinds() {
+    return Array.from(this._axes.keys())
+  }
+}

package/src/Colorbar.js

@@ -0,0 +1,64 @@
+import { Plot } from "./Plot.js"
+import { linkAxes } from "./AxisLink.js"
+import "./ColorbarLayer.js"
+
+const DEFAULT_MARGINS = {
+  horizontal: { top: 5, right: 40, bottom: 45, left: 40 },
+  vertical:   { top: 40, right: 10, bottom: 40, left: 50 }
+}
+
+export class Colorbar extends Plot {
+  constructor(container, targetPlot, colorAxisName, { orientation = "horizontal", margin } = {}) {
+    super(container, { margin: margin ?? DEFAULT_MARGINS[orientation] })
+
+    this._targetPlot = targetPlot
+    this._colorAxisName = colorAxisName
+    this._orientation = orientation
+    this._spatialAxis = orientation === "horizontal" ? "xaxis_bottom" : "yaxis_left"
+
+    this.update({
+      data: {},
+      config: {
+        layers: [{ colorbar: { colorAxis: colorAxisName, orientation } }]
+      }
+    })
+
+    // Link the colorbar's spatial axis to the target's color axis.
+    // Zooming the colorbar propagates domain changes to the target's color range.
+    this._spatialLink = linkAxes(this.axes[this._spatialAxis], targetPlot.axes[colorAxisName])
+
+    // Re-render (with sync) whenever the target plot renders.
+    this._syncCallback = () => this.render()
+    targetPlot._renderCallbacks.add(this._syncCallback)
+  }
+
+  _getScaleTypeFloat(quantityKind) {
+    if (quantityKind === this._colorAxisName && this._targetPlot) {
+      return this._targetPlot._getScaleTypeFloat(quantityKind)
+    }
+    return super._getScaleTypeFloat(quantityKind)
+  }
+
+  render() {
+    // Always pull the current range, colorscale, and scale type from the target plot so the
+    // colorbar stays in sync even after config changes or resizes.
+    if (this.colorAxisRegistry && this.axisRegistry && this._targetPlot) {
+      const range = this._targetPlot.getAxisDomain(this._colorAxisName)
+      if (range) {
+        this.setAxisDomain(this._spatialAxis, range)
+        this.setAxisDomain(this._colorAxisName, range)
+      }
+      const colorscale = this._targetPlot.colorAxisRegistry?.getColorscale(this._colorAxisName)
+      if (colorscale) this.colorAxisRegistry.ensureColorAxis(this._colorAxisName, colorscale)
+      const scaleType = this._targetPlot._getScaleTypeFloat(this._colorAxisName) > 0.5 ? "log" : "linear"
+      this.axisRegistry.setScaleType(this._spatialAxis, scaleType)
+    }
+    super.render()
+  }
+
+  destroy() {
+    this._spatialLink.unlink()
+    this._targetPlot._renderCallbacks.delete(this._syncCallback)
+    super.destroy()
+  }
+}

package/src/ColorbarLayer.js

@@ -0,0 +1,74 @@
+import { LayerType } from "./LayerType.js"
+import { registerLayerType } from "./LayerTypeRegistry.js"
+
+// Four vertices for a triangle-strip quad covering the entire clip space.
+const quadCx = new Float32Array([-1, 1, -1, 1])
+const quadCy = new Float32Array([-1, -1, 1, 1])
+
+export const colorbarLayerType = new LayerType({
+  name: "colorbar",
+
+  getAxisConfig: function(parameters) {
+    const { colorAxis, orientation = "horizontal" } = parameters
+    return {
+      xAxis: orientation === "horizontal" ? "xaxis_bottom" : null,
+      xAxisQuantityKind: orientation === "horizontal" ? colorAxis : undefined,
+      yAxis: orientation === "vertical" ? "yaxis_left" : null,
+      yAxisQuantityKind: orientation === "vertical" ? colorAxis : undefined,
+      colorAxisQuantityKinds: [colorAxis],
+    }
+  },
+
+  vert: `
+    precision mediump float;
+    attribute float cx;
+    attribute float cy;
+    uniform int horizontal;
+    varying float tval;
+    void main() {
+      gl_Position = vec4(cx, cy, 0.0, 1.0);
+      tval = horizontal == 1 ? (cx + 1.0) / 2.0 : (cy + 1.0) / 2.0;
+    }
+  `,
+
+  frag: `
+    precision mediump float;
+    uniform int colorscale;
+    uniform vec2 color_range;
+    uniform float color_scale_type;
+    varying float tval;
+    void main() {
+      float r0 = color_scale_type > 0.5 ? log(color_range.x) : color_range.x;
+      float r1 = color_scale_type > 0.5 ? log(color_range.y) : color_range.y;
+      float v  = r0 + tval * (r1 - r0);
+      gl_FragColor = map_color(colorscale, vec2(r0, r1), v);
+    }
+  `,
+
+  schema: () => ({
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties: {
+      colorAxis: { type: "string", description: "Quantity kind of the color axis to display" },
+      orientation: { type: "string", enum: ["horizontal", "vertical"], default: "horizontal" }
+    },
+    required: ["colorAxis"]
+  }),
+
+  createLayer: function(parameters) {
+    const { colorAxis, orientation = "horizontal" } = parameters
+    return [{
+      attributes: { cx: quadCx, cy: quadCy },
+      uniforms: { horizontal: orientation === "horizontal" ? 1 : 0 },
+      primitive: "triangle strip",
+      vertexCount: 4,
+      nameMap: {
+        [`colorscale_${colorAxis}`]: 'colorscale',
+        [`color_range_${colorAxis}`]: 'color_range',
+        [`color_scale_type_${colorAxis}`]: 'color_scale_type',
+      },
+    }]
+  }
+})
+
+registerLayerType("colorbar", colorbarLayerType)

package/src/ColorscaleRegistry.js

@@ -0,0 +1,49 @@
+const colorscales = new Map()
+
+export function registerColorscale(name, glslFn) {
+  colorscales.set(name, glslFn)
+}
+
+export function getRegisteredColorscales() {
+  return colorscales
+}
+
+export function getColorscaleIndex(name) {
+  let idx = 0
+  for (const key of colorscales.keys()) {
+    if (key === name) return idx
+    idx++
+  }
+  return 0
+}
+
+export function buildColorGlsl() {
+  if (colorscales.size === 0) return ''
+
+  const parts = []
+
+  for (const glslFn of colorscales.values()) {
+    parts.push(glslFn)
+  }
+
+  parts.push('vec4 map_color(int cs, vec2 range, float value) {')
+  parts.push('  float t = clamp((value - range.x) / (range.y - range.x), 0.0, 1.0);')
+
+  let idx = 0
+  for (const name of colorscales.keys()) {
+    parts.push(`  if (cs == ${idx}) return colorscale_${name}(t);`)
+    idx++
+  }
+
+  parts.push('  return vec4(0.5, 0.5, 0.5, 1.0);')
+  parts.push('}')
+
+  parts.push('vec4 map_color_s(int cs, vec2 range, float v, float scaleType) {')
+  parts.push('  float vt = scaleType > 0.5 ? log(v) : v;')
+  parts.push('  float r0 = scaleType > 0.5 ? log(range.x) : range.x;')
+  parts.push('  float r1 = scaleType > 0.5 ? log(range.y) : range.y;')
+  parts.push('  return map_color(cs, vec2(r0, r1), vt);')
+  parts.push('}')
+
+  return parts.join('\n')
+}

package/src/FilterAxisRegistry.js

@@ -0,0 +1,76 @@
+export class FilterAxisRegistry {
+  constructor() {
+    // quantityKind -> { min: number|null, max: number|null, dataExtent: [number,number]|null }
+    this._axes = new Map()
+  }
+
+  ensureFilterAxis(quantityKind) {
+    if (!this._axes.has(quantityKind)) {
+      this._axes.set(quantityKind, { min: null, max: null, dataExtent: null })
+    }
+  }
+
+  setRange(quantityKind, min, max) {
+    if (!this._axes.has(quantityKind)) {
+      throw new Error(`Filter axis '${quantityKind}' not found in registry`)
+    }
+    this._axes.get(quantityKind).min = min
+    this._axes.get(quantityKind).max = max
+  }
+
+  getRange(quantityKind) {
+    const entry = this._axes.get(quantityKind)
+    if (!entry) return null
+    return { min: entry.min, max: entry.max }
+  }
+
+  // Returns [min, max, hasMin, hasMax] for use as a vec4 uniform.
+  // Open bounds (null) are encoded with the corresponding flag set to 0.0.
+  getRangeUniform(quantityKind) {
+    const range = this.getRange(quantityKind)
+    if (!range) return [0.0, 0.0, 0.0, 0.0]
+    return [
+      range.min ?? 0.0,
+      range.max ?? 0.0,
+      range.min !== null ? 1.0 : 0.0,
+      range.max !== null ? 1.0 : 0.0
+    ]
+  }
+
+  // Store the min/max extent of the actual per-point data (used by Filterbar for display).
+  setDataExtent(quantityKind, min, max) {
+    if (!this._axes.has(quantityKind)) {
+      throw new Error(`Filter axis '${quantityKind}' not found in registry`)
+    }
+    this._axes.get(quantityKind).dataExtent = [min, max]
+  }
+
+  // Returns [min, max] extent of the raw data, or null if not yet computed.
+  getDataExtent(quantityKind) {
+    return this._axes.get(quantityKind)?.dataExtent ?? null
+  }
+
+  hasAxis(quantityKind) {
+    return this._axes.has(quantityKind)
+  }
+
+  getQuantityKinds() {
+    return Array.from(this._axes.keys())
+  }
+}
+
+// Injects a GLSL helper used by layer shaders to apply filter axis bounds.
+//
+// filter_in_range(vec4 range, float value):
+//   range.xy = [min, max] (only used when the corresponding flag is set)
+//   range.zw = [hasMin, hasMax] — 1.0 if bound is active, 0.0 if open
+//   Returns false (discard) if value falls outside any active bound.
+export function buildFilterGlsl() {
+  return `
+bool filter_in_range(vec4 range, float value) {
+  if (range.z > 0.5 && value < range.x) return false;
+  if (range.w > 0.5 && value > range.y) return false;
+  return true;
+}
+`
+}