Built-in Layer Types

Gladly ships five pre-registered layer types. For writing custom layer types see Writing Layer Types.

points

A scatter plot that renders individual points coloured by a per-point value mapped through a colorscale.

Auto-registered on import of PointsLayer.js. pointsLayerType is also exported if you need the LayerType object directly (e.g. to inspect its schema).

Parameters:

Behavior:

• Point size: 4.0 px
• Uses Data.wrap internally, so it accepts flat { col: Float32Array } objects, per-column rich objects, and the columnar format — any of the three formats described in the Data reference
• Spatial quantity kinds: taken from the data’s quantity_kind metadata for the named column if present; otherwise the column name itself
• Color axis quantity kind: same resolution for vData; the key in config.axes must match the resolved quantity kind
• Colorscale: from config.axes[quantityKind].colorscale, or the quantity kind registry
• Supports log scales on all axes via config.axes[...].scale: "log"

Example (simple flat format):

plot.update({
  data: { x, y, temperature },
  config: {
    layers: [
      { points: { xData: "x", yData: "y", vData: "temperature" } }
    ],
    axes: {
      temperature: { min: 0, max: 100, colorscale: "plasma" }
    }
  }
})

Example (columnar format with quantity kinds):

When the data carries quantity_kinds, the resolved quantity kind — not the column name — is used as the axis key in config.axes:

plot.update({
  data: {
    data: { x, y, temperature },
    quantity_kinds: { x: "distance_m", y: "voltage_V", temperature: "temperature_K" }
  },
  config: {
    layers: [
      { points: { xData: "x", yData: "y", vData: "temperature" } }
    ],
    axes: {
      // key is the resolved quantity kind, not the column name "temperature"
      temperature_K: { min: 0, max: 100, colorscale: "plasma" }
    }
  }
})

lines

A connected-line plot that renders segments between consecutive points, with per-point color mapped through a colorscale. Uses instanced rendering: segment endpoints are uploaded once as per-instance data and a two-vertex template is replicated for each segment.

Auto-registered on import of LinesLayer.js. linesLayerType is also exported if you need the LayerType object directly.

Parameters:

Behavior:

• Uses instanced rendering: one instance per segment (N−1 instances for N points)
• Segment boundary handling: when lineSegmentIdData is used and two adjacent points have different IDs, both template vertices collapse to the same position, producing a zero-length segment the rasterizer discards
• Same quantity kind resolution as points

Example:

plot.update({
  data: { x, y, temperature },
  config: {
    layers: [
      { lines: { xData: "x", yData: "y", vData: "temperature", lineColorMode: "gradient" } }
    ],
    axes: {
      temperature: { min: 0, max: 100, colorscale: "plasma" }
    }
  }
})

tile

A geographic map underlay that fetches and renders raster tiles from XYZ, WMS, or WMTS services. Tiles are reprojected from the tile service’s CRS to the plot’s CRS using tessellated meshes, so any pair of projected coordinate systems is supported. proj4 definitions are fetched automatically from epsg.io on first use; quantity kind labels are looked up from the projnames package.

Auto-registered on import. tileLayerType and TileLayerType are also exported if needed.

Parameters:

Source types:

source.type: "xyz" — Standard slippy-map tiles (OpenStreetMap, Mapbox, etc.)

source.type: "wms" — OGC Web Map Service. Fetches a single image per viewport change.

source.type: "wmts" — OGC Web Map Tile Service. Uses the same Web Mercator tile grid as XYZ.

Behavior:

• Tiles are loaded asynchronously; the plot renders other layers immediately and tiles appear as they arrive
• Tile textures are cached (up to 50 tiles for XYZ/WMTS; WMS keeps only the current and previous image)
• A new tile load is triggered when the visible domain shifts or zooms by more than ~2%
• EPSG quantity kinds (epsg_CODE_x / epsg_CODE_y) are registered automatically using projnames labels when a new CRS code is first encountered, so axis labels are populated without any user setup
• proj4 definitions for EPSG:4326 (WGS84) and EPSG:3857 (Web Mercator) are built-in; all others are fetched from https://epsg.io/{code}.proj4 on first use. For offline use, pre-register with registerEpsgDef
• The tile layer contributes no domain data — axis bounds must come from other layers or explicit axes.min/max config
• Alpha blending is enabled; use opacity for transparent overlays

Example — OSM tiles reprojected from Web Mercator to WGS84 lon/lat:

import { Plot, registerAxisQuantityKind } from 'gladly-plot'

registerAxisQuantityKind('city_index', { label: 'City', scale: 'linear', colorscale: 'plasma' })

const lon     = new Float32Array([-74.006, -0.118, 139.691])
const lat     = new Float32Array([ 40.714, 51.509,  35.690])
const cityIdx = new Float32Array([0, 1, 2])

const data = {
  data: { lon, lat, cityIdx },
  quantity_kinds: { lon: 'epsg_4326_x', lat: 'epsg_4326_y', cityIdx: 'city_index' },
}

plot.update({
  config: {
    layers: [
      {
        tile: {
          source: {
            type: 'xyz',
            url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
          },
          tileCrs: 'EPSG:3857',
          plotCrs: 'EPSG:4326',
          opacity: 0.9,
        },
      },
      { points: { xData: 'lon', yData: 'lat', vData: 'cityIdx' } },
    ],
    axes: {
      xaxis_bottom: { min: -180, max: 180 },
      yaxis_left:   { min: -80,  max: 80  },
      city_index:   { colorbar: 'vertical', colorscale: 'plasma', min: 0, max: 2 },
    },
  },
  data,
})

Example — WMS service:

plot.update({
  config: {
    layers: [
      {
        tile: {
          source: {
            type: 'wms',
            url: 'https://example.com/wms',
            layers: 'MyLayer',
            format: 'image/png',
            version: '1.3.0',
          },
          tileCrs: 'EPSG:3857',
          plotCrs: 'EPSG:26911',   // NAD83 / UTM zone 11N — fetched automatically
        },
      },
    ],
    axes: {
      xaxis_bottom: { min: 400000, max: 700000 },
      yaxis_left:   { min: 3700000, max: 4000000 },
    },
  },
  data: {},
})

colorbar

A layer type that fills the entire plot canvas with a color gradient. Used internally by Colorbar, but can also be used directly in custom plot setups.

Auto-registered on import. colorbarLayerType is also exported if you need the LayerType object directly.

Parameters:

Behavior:

• Renders a triangle-strip quad that fills the entire canvas with a color gradient
• Horizontal: gradient runs left → right; vertical: bottom → top
• The spatial axis of the plot (x for horizontal, y for vertical) is bound to the color axis quantity kind, so the axis tick labels show actual data values
• The color axis range and colorscale are sourced from the owning plot’s color axis registry

Typical use: Create a standalone Plot with one colorbar layer, link its spatial axis to the color axis of a data plot. The Colorbar class does exactly this.

filterbar

A layer type that registers a filter axis for axis-display purposes without rendering any geometry. Used internally by Filterbar, but can also be used directly in custom plot setups.

Auto-registered on import. filterbarLayerType is also exported if you need the LayerType object directly.

Parameters:

Behavior:

• Registers the named filter axis with the plot (so it is accessible via plot.axes[name] and can be linked via linkAxes)
• Renders no geometry (vertexCount: 0)
• Binds the spatial axis (x for horizontal, y for vertical) to the filter axis quantity kind, so tick labels show the filter range

The Filterbar class wraps a plot using this layer type and adds interactive UI (∞ checkboxes for open bounds, zoom/pan to adjust the filter range).