Gladly API Documentation

Overview

Gladly is a GPU-accelerated multi-axis plotting library that uses WebGL (via regl) for high-performance data rendering and D3.js for interactive axes and zoom controls.

The library features a declarative API where you register layer types once and then create plots by specifying data and layer configurations.

Data Model

Understanding the core data model makes all other concepts fall into place.

flowchart LR
    LD["Layer\n{ layerTypeName: params }"]
    LT["LayerType"]
    SA["Spatial Axis"]
    CA["Color Axis"]
    FA["Filter Axis"]
    QK["Quantity Kind\n(string)"]
    R["Range\n[min, max]"]
    CS["Colorscale"]

    LD -- has --> LT
    LD -- declares --> SA
    LD -- declares --> CA
    LD -- declares --> FA
    SA & CA & FA -- identified by --> QK
    QK -- has --> R
    CA -- has --> CS

Axes

All axes — spatial, color, and filter — share two concepts:

A plot has up to four spatial axes (xaxis_bottom, xaxis_top, yaxis_left, yaxis_right). For spatial axes the quantity kind is any string; it determines the axis label and, for the special value "log10", switches to a logarithmic scale.

In addition to spatial axes, each layer can declare:

All axes can have their ranges overridden in config.axes.

Colorscale

A colorscale maps a normalized value in [0, 1] to an RGBA color. Every color axis has a colorscale, referenced by name (e.g. "viridis", "plasma"). The layer type sets a default; it can be overridden per quantity kind in config.axes.

All standard matplotlib colorscales are available without any setup. Custom colorscales can be registered with registerColorscale(). See the colorscales reference.

LayerType

A LayerType defines a visualization strategy. It specifies:

Layers in Config

Each entry in config.layers is a JSON object { layerTypeName: parameters }. The plot creates a rendered layer for each entry by calling the layer type’s createLayer factory with those parameters and the current data object.

A layer’s parameters typically include:

See Configuring Plots for the full config format.

Data Format

The plotting framework is agnostic about the shape of the data object passed to plot.update(). It stores it and passes it unchanged to each layer type’s createLayer and getAxisConfig functions. What those functions do with it is entirely up to the layer type author.

Each value in the attributes map returned from createLayer must be one of:

// Correct — plain Float32Arrays
const data = {
  x: new Float32Array([1, 2, 3]),
  y: new Float32Array([4, 5, 6]),
  v: new Float32Array([0.1, 0.5, 0.9])
}

// Also correct — computed attribute expression
attributes: {
  count: { histogram: { input: normalized, bins: 50 } }
}

// Incorrect — plain JS arrays will throw
const bad = { x: [1, 2, 3], y: [4, 5, 6] }

See Computed Attributes for the full expression syntax, built-in computations, and how to write custom ones.

Optional: the Data class

For convenience, Gladly provides an optional Data class that normalises several common plain-object shapes — including per-column metadata (quantity kinds, pre-computed domains) and a columnar format separating arrays from their metadata — into a single consistent interface. The built-in layer types use it internally; custom layer types may adopt it voluntarily.

The framework itself never calls Data. See Data in the API reference for the full interface and all supported formats.

Config Structure

plot.update({
  data: { /* named Float32Arrays */ },
  config: {
    layers: [
      // Each entry: { layerTypeName: { ...parameters } }
      { points: { xData: "x", yData: "y", vData: "v" } }
    ],
    axes: {
      // Spatial axes — omit for auto-calculated range
      xaxis_bottom: { min: 0, max: 100 },
      yaxis_left:   { min: 0, max: 50 },
      // Color axes — key is the quantity kind
      temperature: { min: 20, max: 80, colorscale: "plasma" },
      // Filter axes — both bounds optional (open interval)
      depth: { min: 10, max: 500 }
    }
  }
})

Sub-topics