gladly-plot 0.0.1 → 0.0.2

package/README.md

@@ -13,8 +13,10 @@ Gladly combines WebGL rendering (via regl) with D3.js for interactive axes and z
 - 🎯 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
+- 📏 Quantity and unit-aware axis management
+- 🎨 Supports all standard colorscales
+- 🔗 Subplot axis linking
+- 🌈 Axis to coloring or filtering linking
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gladly-plot",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "GPU-powered multi-axis plotting library with regl + d3",
   "type": "module",
 
@@ -18,6 +18,8 @@
 
   "dependencies": {
     "d3": "^7.8.5",
+    "proj4": "^2.15.0",
+    "projnames": "^0.0.2",
     "regl": "^2.1.0"
   },
 

package/src/AxisRegistry.js

@@ -16,9 +16,9 @@ export class AxisRegistry {
   }
 
   ensureAxis(axisName, axisQuantityKind, scaleOverride) {
-    if (!AXES.includes(axisName)) throw `Unknown axis ${axisName}`
+    if (!AXES.includes(axisName)) throw new Error(`Unknown axis ${axisName}`)
     if (this.axisQuantityKinds[axisName] && this.axisQuantityKinds[axisName] !== axisQuantityKind)
-      throw `Axis quantity kind mismatch on axis ${axisName}: ${this.axisQuantityKinds[axisName]} vs ${axisQuantityKind}`
+      throw new Error(`Axis quantity kind mismatch on axis ${axisName}: ${this.axisQuantityKinds[axisName]} vs ${axisQuantityKind}`)
 
     if (!this.scales[axisName]) {
       const quantityKindDef = getAxisQuantityKind(axisQuantityKind)

package/src/Data.js

@@ -0,0 +1,67 @@
+export class Data {
+  constructor(raw) {
+    raw = raw ?? {}
+    // Columnar format: { data: {col: Float32Array}, quantity_kinds?: {...}, domains?: {...} }
+    // Detected by the presence of a top-level `data` property that is a plain object.
+    if (raw.data != null && typeof raw.data === 'object' && !(raw.data instanceof Float32Array)) {
+      this._columnar = true
+      this._data = raw.data
+      this._quantityKinds = raw.quantity_kinds ?? {}
+      this._rawDomains = raw.domains ?? {}
+    } else {
+      this._columnar = false
+      this._raw = raw
+    }
+  }
+
+  static wrap(data) {
+    if (data != null && typeof data.columns === 'function' && typeof data.getData === 'function') {
+      return data
+    }
+    return new Data(data)
+  }
+
+  _entry(col) {
+    if (this._columnar) {
+      const rawDomain = this._rawDomains[col]
+      let domain
+      if (Array.isArray(rawDomain)) {
+        domain = [rawDomain[0], rawDomain[1]]
+      } else if (rawDomain && typeof rawDomain === 'object') {
+        domain = [rawDomain.min, rawDomain.max]
+      }
+      return { data: this._data[col], quantityKind: this._quantityKinds[col], domain }
+    }
+
+    const v = this._raw[col]
+    if (v instanceof Float32Array) {
+      return { data: v, quantityKind: undefined, domain: undefined }
+    }
+    if (v && typeof v === 'object') {
+      let domain
+      if (Array.isArray(v.domain)) {
+        domain = [v.domain[0], v.domain[1]]
+      } else if (v.domain && typeof v.domain === 'object') {
+        domain = [v.domain.min, v.domain.max]
+      }
+      return { data: v.data, quantityKind: v.quantity_kind, domain }
+    }
+    return { data: undefined, quantityKind: undefined, domain: undefined }
+  }
+
+  columns() {
+    return this._columnar ? Object.keys(this._data) : Object.keys(this._raw)
+  }
+
+  getData(col) {
+    return this._entry(col).data
+  }
+
+  getQuantityKind(col) {
+    return this._entry(col).quantityKind
+  }
+
+  getDomain(col) {
+    return this._entry(col).domain
+  }
+}

package/src/EpsgUtils.js

@@ -0,0 +1,123 @@
+import proj4 from 'proj4'
+import { byEpsg } from 'projnames'
+import { registerAxisQuantityKind } from './AxisQuantityKindRegistry.js'
+
+/**
+ * Parse an EPSG CRS string or number to a plain integer code.
+ * Accepts: 26911, "26911", "EPSG:26911", "epsg:26911"
+ */
+export function parseCrsCode(crs) {
+  if (typeof crs === 'number') return crs
+  const m = String(crs).match(/(\d+)$/)
+  return m ? parseInt(m[1]) : null
+}
+
+/** "EPSG:26911" → "epsg_26911_x" */
+export function crsToQkX(crs) {
+  return `epsg_${parseCrsCode(crs)}_x`
+}
+
+/** "EPSG:26911" → "epsg_26911_y" */
+export function crsToQkY(crs) {
+  return `epsg_${parseCrsCode(crs)}_y`
+}
+
+/** "epsg_26911_x" or "epsg_26911_y" → 26911, or null if not matching */
+export function qkToEpsgCode(qk) {
+  const m = String(qk).match(/^epsg_(\d+)_[xy]$/)
+  return m ? parseInt(m[1]) : null
+}
+
+/**
+ * Register a proj4 CRS definition and auto-register the matching
+ * epsg_CODE_x / epsg_CODE_y quantity kinds with labels from projnames.
+ * Useful for offline/air-gapped environments where network access is unavailable.
+ *
+ * @param {number} epsgCode - e.g. 26911
+ * @param {string} proj4string - e.g. "+proj=utm +zone=11 +datum=NAD83 +units=m +no_defs"
+ */
+export function registerEpsgDef(epsgCode, proj4string) {
+  proj4.defs(`EPSG:${epsgCode}`, proj4string)
+  _registerQuantityKinds(epsgCode)
+}
+
+// ─── Internal auto-fetch machinery ───────────────────────────────────────────
+
+// Labels for EPSG codes absent from (or wrong in) the projnames package.
+const EPSG_LABEL_OVERRIDES = {
+  4326: 'WGS 84',
+}
+
+// Tracks codes whose quantity kinds have been registered (avoids duplicate work)
+const _registeredQkCodes = new Set()
+
+// In-flight fetch promises keyed by code (deduplicates concurrent requests)
+const _pendingFetches = new Map()
+
+function _registerQuantityKinds(code) {
+  if (_registeredQkCodes.has(code)) return
+  _registeredQkCodes.add(code)
+  const name = EPSG_LABEL_OVERRIDES[code] ?? byEpsg[code] ?? `EPSG:${code}`
+  registerAxisQuantityKind(`epsg_${code}_x`, { label: `${name} X`, scale: 'linear' })
+  registerAxisQuantityKind(`epsg_${code}_y`, { label: `${name} Y`, scale: 'linear' })
+}
+
+/**
+ * Ensure a CRS is defined in proj4 and has quantity kinds registered.
+ * - If already known to proj4, only registers quantity kinds (synchronous work).
+ * - Otherwise fetches the proj4 string from epsg.io (async).
+ * - Concurrent calls for the same code share a single in-flight request.
+ *
+ * @param {string|number} crs - e.g. "EPSG:26911", 26911
+ * @returns {Promise<void>}
+ */
+export async function ensureCrsDefined(crs) {
+  const code = parseCrsCode(crs)
+  if (!code) throw new Error(`Cannot parse CRS code from: ${crs}`)
+
+  const key = `EPSG:${code}`
+
+  // Register quantity kinds first — this is always synchronous (projnames lookup)
+  _registerQuantityKinds(code)
+
+  // If proj4 already has this definition (including built-ins 4326 and 3857), we're done
+  if (proj4.defs(key)) return
+
+  // Deduplicate concurrent fetches for the same code
+  if (!_pendingFetches.has(code)) {
+    const p = fetch(`https://epsg.io/${code}.proj4`)
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        return res.text()
+      })
+      .then(def => {
+        proj4.defs(key, def.trim())
+      })
+      .finally(() => {
+        _pendingFetches.delete(code)
+      })
+    _pendingFetches.set(code, p)
+  }
+
+  try {
+    await _pendingFetches.get(code)
+  } catch (err) {
+    throw new Error(`Failed to fetch proj4 definition for ${key}: ${err.message}`)
+  }
+}
+
+/**
+ * Reproject a [x, y] point from one CRS to another.
+ * Both CRS strings are parsed via parseCrsCode (accepts "EPSG:N", "N", N).
+ * The CRS must already be registered (via registerEpsgDef or ensureCrsDefined).
+ *
+ * @param {string|number} fromCrs
+ * @param {string|number} toCrs
+ * @param {[number, number]} point
+ * @returns {[number, number]}
+ */
+export function reproject(fromCrs, toCrs, point) {
+  const from = `EPSG:${parseCrsCode(fromCrs)}`
+  const to = `EPSG:${parseCrsCode(toCrs)}`
+  return proj4(from, to).forward(point)
+}

package/src/Layer.js

@@ -1,5 +1,5 @@
 export class Layer {
-  constructor({ type, attributes, uniforms, nameMap = {}, domains = {}, lineWidth = 1, primitive = "points", xAxis = "xaxis_bottom", yAxis = "yaxis_left", xAxisQuantityKind, yAxisQuantityKind, colorAxes = [], filterAxes = [], vertexCount = null, instanceCount = null, attributeDivisors = {} }) {
+  constructor({ type, attributes, uniforms, nameMap = {}, domains = {}, lineWidth = 1, primitive = "points", xAxis = "xaxis_bottom", yAxis = "yaxis_left", xAxisQuantityKind, yAxisQuantityKind, colorAxes = [], filterAxes = [], vertexCount = null, instanceCount = null, attributeDivisors = {}, blend = null }) {
     // Validate that all attributes are typed arrays
     for (const [key, value] of Object.entries(attributes)) {
       if (!(value instanceof Float32Array)) {
@@ -39,5 +39,6 @@ export class Layer {
     this.vertexCount = vertexCount
     this.instanceCount = instanceCount
     this.attributeDivisors = attributeDivisors
+    this.blend = blend
   }
 }

package/src/LayerType.js

@@ -22,7 +22,7 @@ export class LayerType {
     // Optional dynamic resolver — overrides statics wherever it returns a non-undefined value
     getAxisConfig,
     // GPU rendering
-    vert, frag, schema, createLayer
+    vert, frag, schema, createLayer, createDrawCommand
   }) {
     this.name = name
     // Static declarations stored as-is (undefined = not declared)
@@ -38,6 +38,7 @@ export class LayerType {
     if (schema) this._schema = schema
     if (createLayer) this._createLayer = createLayer
     if (getAxisConfig) this._getAxisConfig = getAxisConfig
+    if (createDrawCommand) this.createDrawCommand = createDrawCommand
   }
 
   createDrawCommand(regl, layer) {
@@ -100,7 +101,8 @@ export class LayerType {
       viewport: regl.prop("viewport"),
       primitive: layer.primitive,
       lineWidth: layer.lineWidth,
-      count: regl.prop("count")
+      count: regl.prop("count"),
+      ...(layer.blend ? { blend: layer.blend } : {})
     }
 
     if (layer.instanceCount !== null) {
@@ -158,6 +160,7 @@ export class LayerType {
       vertexCount: gpuConfig.vertexCount ?? null,
       instanceCount: gpuConfig.instanceCount ?? null,
       attributeDivisors: gpuConfig.attributeDivisors ?? {},
+      blend: gpuConfig.blend ?? null,
       xAxis: axisConfig.xAxis,
       yAxis: axisConfig.yAxis,
       xAxisQuantityKind: axisConfig.xAxisQuantityKind,

package/src/Plot.js

@@ -385,7 +385,7 @@ export class Plot {
 
       // Create one draw command per GPU config returned by the layer type.
       for (const layer of layerType.createLayer(parameters, data)) {
-        layer.draw = layer.type.createDrawCommand(this.regl, layer)
+        layer.draw = layer.type.createDrawCommand(this.regl, layer, this)
         this.layers.push(layer)
       }
     }

package/src/ScatterLayer.js

@@ -1,18 +1,20 @@
 import { LayerType } from "./LayerType.js"
 import { AXES } from "./AxisRegistry.js"
 import { registerLayerType } from "./LayerTypeRegistry.js"
+import { Data } from "./Data.js"
 
 export const scatterLayerType = new LayerType({
   name: "scatter",
 
-  getAxisConfig: function(parameters) {
+  getAxisConfig: function(parameters, data) {
+    const d = Data.wrap(data)
     const { xData, yData, vData, xAxis, yAxis } = parameters
     return {
       xAxis,
-      xAxisQuantityKind: xData,
+      xAxisQuantityKind: d.getQuantityKind(xData) ?? xData,
       yAxis,
-      yAxisQuantityKind: yData,
-      colorAxisQuantityKinds: [vData],
+      yAxisQuantityKind: d.getQuantityKind(yData) ?? yData,
+      colorAxisQuantityKinds: [d.getQuantityKind(vData) ?? vData],
     }
   },
 
@@ -41,11 +43,13 @@ export const scatterLayerType = new LayerType({
     uniform float color_scale_type;
     varying float value;
     void main() {
-      gl_FragColor = map_color_s(colorscale, color_range, value, color_scale_type);
+      float t = clamp((value - color_range.x) / (color_range.y - color_range.x), 0.0, 1.0);
+      vec4 color = map_color_s(colorscale, color_range, value, color_scale_type);
+      gl_FragColor = vec4(color.rgb, t);
     }
   `,
   schema: (data) => {
-    const dataProperties = data ? Object.keys(data) : []
+    const dataProperties = Data.wrap(data).columns()
     return {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       type: "object",
@@ -76,31 +80,54 @@ export const scatterLayerType = new LayerType({
           enum: AXES.filter(a => a.includes("y")),
           default: "yaxis_left",
           description: "Which y-axis to use for this layer"
+        },
+        alphaBlend: {
+          type: "boolean",
+          default: false,
+          description: "Map the normalized color value to alpha so low values fade to transparent"
         }
       },
       required: ["xData", "yData", "vData"]
     }
   },
   createLayer: function(parameters, data) {
-    const { xData, yData, vData } = parameters
+    const d = Data.wrap(data)
+    const { xData, yData, vData, alphaBlend = false } = parameters
+
+    const xQK = d.getQuantityKind(xData) ?? xData
+    const yQK = d.getQuantityKind(yData) ?? yData
+    const vQK = d.getQuantityKind(vData) ?? vData
+
+    const x = d.getData(xData)
+    const y = d.getData(yData)
+    const v = d.getData(vData)
 
-    const x = data[xData]
-    const y = data[yData]
-    const v = data[vData]
+    if (!x) throw new Error(`Data column '${xData}' not found`)
+    if (!y) throw new Error(`Data column '${yData}' not found`)
+    if (!v) throw new Error(`Data column '${vData}' not found`)
 
-    if (!x) throw new Error(`Data property '${xData}' not found in data object`)
-    if (!y) throw new Error(`Data property '${yData}' not found in data object`)
-    if (!v) throw new Error(`Data property '${vData}' not found in data object`)
+    const domains = {}
+    const xDomain = d.getDomain(xData)
+    const yDomain = d.getDomain(yData)
+    const vDomain = d.getDomain(vData)
+    if (xDomain) domains[xQK] = xDomain
+    if (yDomain) domains[yQK] = yDomain
+    if (vDomain) domains[vQK] = vDomain
 
     return [{
-      attributes: { x, y, [vData]: v },
+      attributes: { x, y, [vQK]: v },
       uniforms: {},
+      domains,
       nameMap: {
-        [vData]: 'color_data',
-        [`colorscale_${vData}`]: 'colorscale',
-        [`color_range_${vData}`]: 'color_range',
-        [`color_scale_type_${vData}`]: 'color_scale_type',
+        [vQK]: 'color_data',
+        [`colorscale_${vQK}`]: 'colorscale',
+        [`color_range_${vQK}`]: 'color_range',
+        [`color_scale_type_${vQK}`]: 'color_scale_type',
       },
+      blend: alphaBlend ? {
+        enable: true,
+        func: { srcRGB: 'src alpha', dstRGB: 'one minus src alpha', srcAlpha: 0, dstAlpha: 1 },
+      } : null,
     }]
   }
 })

package/src/TileLayer.js

@@ -0,0 +1,708 @@
+import proj4 from 'proj4'
+import { LayerType } from './LayerType.js'
+import { AXES } from './AxisRegistry.js'
+import { registerLayerType } from './LayerTypeRegistry.js'
+import { parseCrsCode, crsToQkX, crsToQkY, ensureCrsDefined } from './EpsgUtils.js'
+
+// ─── Tile math (standard Web Mercator / "slippy map" grid) ────────────────────
+
+const EARTH_RADIUS = 6378137          // metres (WGS84 semi-major axis)
+const MERC_MAX = Math.PI * EARTH_RADIUS   // ~20037508.34 m
+
+function mercXToNorm(x) { return (x + MERC_MAX) / (2 * MERC_MAX) }
+function mercYToNorm(y) { return (1 - y / MERC_MAX) / 2 }
+function normToMercX(nx) { return nx * 2 * MERC_MAX - MERC_MAX }
+function normToMercY(ny) { return (1 - 2 * ny) * MERC_MAX }
+
+function mercToTileXY(x, y, z) {
+  const scale = Math.pow(2, z)
+  return [
+    Math.floor(mercXToNorm(x) * scale),
+    Math.floor(mercYToNorm(y) * scale),
+  ]
+}
+
+function tileToMercBbox(tx, ty, z) {
+  const scale = Math.pow(2, z)
+  return {
+    minX: normToMercX(tx / scale),
+    maxX: normToMercX((tx + 1) / scale),
+    minY: normToMercY((ty + 1) / scale),  // tile y is top-down, merc y is bottom-up
+    maxY: normToMercY(ty / scale),
+  }
+}
+
+function optimalZoom(bboxInTileCrs, pixelWidth, pixelHeight, minZoom, maxZoom) {
+  // Assume tile grid is Web Mercator: one tile = 256 px at zoom 0.
+  // Use the minimum of the x- and y-derived zoom levels so that neither
+  // dimension produces an unmanageable number of tiles.  A large y-extent
+  // with a small x-extent used to drive zoom to maxZoom via x alone, which
+  // could generate hundreds-of-thousands of tiles in the y direction.
+  const xExtent = Math.abs(bboxInTileCrs.maxX - bboxInTileCrs.minX)
+  const yExtent = Math.abs(bboxInTileCrs.maxY - bboxInTileCrs.minY)
+  const worldSize = 2 * MERC_MAX
+  const zx = xExtent > 0 ? Math.log2((pixelWidth  / 256) * (worldSize / xExtent)) : Infinity
+  const zy = yExtent > 0 ? Math.log2((pixelHeight / 256) * (worldSize / yExtent)) : Infinity
+  const z = Math.min(zx, zy)
+  return Math.min(Math.max(Math.floor(isFinite(z) ? z : maxZoom), minZoom), maxZoom)
+}
+
+// ─── Source resolution ────────────────────────────────────────────────────────
+
+// source is stored as { xyz: {...} } | { wms: {...} } | { wmts: {...} }
+// Normalize to { type: 'xyz'|'wms'|'wmts', ...params } for the rest of the pipeline.
+function resolveSource(source) {
+  const type = Object.keys(source).find(k => k === 'xyz' || k === 'wms' || k === 'wmts')
+  if (!type) throw new Error(`source must have exactly one key of: xyz, wms, wmts`)
+  return { type, ...source[type] }
+}
+
+// ─── URL builders ──────────────────────────────────────────────────────────────
+
+function buildXyzUrl(source, z, x, y) {
+  const subdomains = source.subdomains ?? ['a', 'b', 'c']
+  const s = subdomains[Math.abs(x + y) % subdomains.length]
+  return source.url
+    .replace('{z}', z)
+    .replace('{x}', x)
+    .replace('{y}', y)
+    .replace('{s}', s)
+}
+
+function buildWmtsUrl(source, z, x, y) {
+  // Support both RESTful template ({TileMatrix}, {TileRow}, {TileCol}) and KVP
+  const url = source.url
+  if (url.includes('{TileMatrix}') || url.includes('{z}')) {
+    return url
+      .replace('{TileMatrix}', z).replace('{z}', z)
+      .replace('{TileRow}', y).replace('{y}', y)
+      .replace('{TileCol}', x).replace('{x}', x)
+  }
+  // KVP style
+  const params = new URLSearchParams({
+    SERVICE: 'WMTS',
+    REQUEST: 'GetTile',
+    VERSION: '1.0.0',
+    LAYER: source.layer,
+    STYLE: source.style ?? 'default',
+    FORMAT: source.format ?? 'image/png',
+    TILEMATRIXSET: source.tileMatrixSet ?? 'WebMercatorQuad',
+    TILEMATRIX: z,
+    TILEROW: y,
+    TILECOL: x,
+  })
+  return `${source.url}?${params}`
+}
+
+function buildWmsUrl(source, bbox, tileCrs, pixelWidth, pixelHeight) {
+  const version = source.version ?? '1.3.0'
+  const crsParam = `EPSG:${parseCrsCode(tileCrs)}`
+
+  // WMS 1.3.0 with geographic CRS (EPSG:4326) swaps axis order: BBOX is minLat,minLon,maxLat,maxLon
+  const is13 = version === '1.3.0'
+  const epsgCode = parseCrsCode(crsParam)
+  // EPSG:4326 and other geographic CRS have swapped axes in WMS 1.3.0
+  const swapAxes = is13 && (epsgCode === 4326)
+  const bboxStr = swapAxes
+    ? `${bbox.minY},${bbox.minX},${bbox.maxY},${bbox.maxX}`
+    : `${bbox.minX},${bbox.minY},${bbox.maxX},${bbox.maxY}`
+
+  const crsKey = is13 ? 'CRS' : 'SRS'
+  const params = new URLSearchParams({
+    SERVICE: 'WMS',
+    VERSION: version,
+    REQUEST: 'GetMap',
+    LAYERS: source.layers,
+    [crsKey]: crsParam,
+    BBOX: bboxStr,
+    WIDTH: Math.round(pixelWidth),
+    HEIGHT: Math.round(pixelHeight),
+    FORMAT: source.format ?? 'image/png',
+    TRANSPARENT: source.transparent !== false ? 'TRUE' : 'FALSE',
+    ...(source.styles ? { STYLES: source.styles } : {}),
+  })
+  return `${source.url}?${params}`
+}
+
+// ─── Tessellated mesh builder ──────────────────────────────────────────────────
+
+/**
+ * Build a tessellated mesh for one tile.
+ *
+ * @param {{ minX, maxX, minY, maxY }} tileBbox  - bbox in tileCrs
+ * @param {string} tileCrs  - e.g. "EPSG:3857"
+ * @param {string} plotCrs  - e.g. "EPSG:26911" (may equal tileCrs)
+ * @param {number} N        - tessellation grid size (N×N quads)
+ * @returns {{ positions: Float32Array, uvs: Float32Array, indices: Uint16Array }}
+ */
+function buildTileMesh(tileBbox, tileCrs, plotCrs, N) {
+  const sameProj = `EPSG:${parseCrsCode(tileCrs)}` === `EPSG:${parseCrsCode(plotCrs)}`
+  const project = sameProj ? null : proj4(`EPSG:${parseCrsCode(tileCrs)}`, `EPSG:${parseCrsCode(plotCrs)}`).forward
+
+  const numVerts = (N + 1) * (N + 1)
+  const positions = new Float32Array(numVerts * 2)
+  const uvs = new Float32Array(numVerts * 2)
+
+  for (let j = 0; j <= N; j++) {
+    for (let i = 0; i <= N; i++) {
+      const u = i / N
+      const v = j / N
+      const tileX = tileBbox.minX + u * (tileBbox.maxX - tileBbox.minX)
+      const tileY = tileBbox.minY + v * (tileBbox.maxY - tileBbox.minY)
+
+      let px, py
+      if (project) {
+        ;[px, py] = project([tileX, tileY])
+      } else {
+        px = tileX
+        py = tileY
+      }
+
+      const vi = j * (N + 1) + i
+      positions[vi * 2]     = px
+      positions[vi * 2 + 1] = py
+      uvs[vi * 2]     = u
+      uvs[vi * 2 + 1] = 1 - v  // flip v: tile y=0 is top, GL texture v=0 is bottom
+    }
+  }
+
+  // Two CCW triangles per cell: (BL, BR, TR) and (BL, TR, TL)
+  const numIndices = N * N * 6
+  const indices = new Uint16Array(numIndices)
+  let idx = 0
+  for (let j = 0; j < N; j++) {
+    for (let i = 0; i < N; i++) {
+      const bl = j * (N + 1) + i
+      const br = bl + 1
+      const tl = bl + (N + 1)
+      const tr = tl + 1
+      indices[idx++] = bl; indices[idx++] = br; indices[idx++] = tr
+      indices[idx++] = bl; indices[idx++] = tr; indices[idx++] = tl
+    }
+  }
+
+  return { positions, uvs, indices }
+}
+
+// ─── TileManager ──────────────────────────────────────────────────────────────
+
+const MAX_TILE_CACHE = 50
+const DOMAIN_CHANGE_THRESHOLD = 0.02  // 2% change triggers tile sync
+
+class TileManager {
+  constructor({ regl, source, tileCrs, plotCrs, tessellation, onLoad }) {
+    this.regl = regl
+    this.source = source
+    this.tileCrs = tileCrs  // CRS of the tile service (e.g. "EPSG:3857")
+    this.plotCrs = plotCrs  // CRS of the plot axes
+    this.tessellation = tessellation
+    this.onLoad = onLoad
+
+    this.tiles = new Map()       // tileKey → tile entry
+    this.accessOrder = []        // LRU tracking
+    this._neededKeys = new Set() // keys required by the most recent syncTiles call
+
+    this._lastXDomain = null
+    this._lastYDomain = null
+    this._lastViewport = null
+
+    // Pre-compute the proj4 converter from plotCrs to tileCrs for bbox conversion
+    const fromCode = parseCrsCode(plotCrs)
+    const toCode = parseCrsCode(tileCrs)
+    this._plotToTile = fromCode === toCode
+      ? (pt) => pt
+      : proj4(`EPSG:${fromCode}`, `EPSG:${toCode}`).forward
+  }
+
+  _domainChanged(xDomain, yDomain, viewport) {
+    if (!this._lastXDomain || !this._lastYDomain) return true
+    const viewChanged = !!(viewport && this._lastViewport && (
+      viewport.width !== this._lastViewport.width ||
+      viewport.height !== this._lastViewport.height
+    ))
+    const dx = Math.abs(xDomain[1] - xDomain[0])
+    const dy = Math.abs(yDomain[1] - yDomain[0])
+    // When a domain has zero width, relative change is undefined; fall back to
+    // exact equality so we don't treat every frame as "changed" (div-by-zero
+    // would give Infinity > threshold = true on every call).
+    if (dx === 0 || dy === 0) {
+      return xDomain[0] !== this._lastXDomain[0] ||
+             xDomain[1] !== this._lastXDomain[1] ||
+             yDomain[0] !== this._lastYDomain[0] ||
+             yDomain[1] !== this._lastYDomain[1] ||
+             viewChanged
+    }
+    const xChange = Math.max(
+      Math.abs(xDomain[0] - this._lastXDomain[0]) / dx,
+      Math.abs(xDomain[1] - this._lastXDomain[1]) / dx
+    )
+    const yChange = Math.max(
+      Math.abs(yDomain[0] - this._lastYDomain[0]) / dy,
+      Math.abs(yDomain[1] - this._lastYDomain[1]) / dy
+    )
+    return xChange > DOMAIN_CHANGE_THRESHOLD || yChange > DOMAIN_CHANGE_THRESHOLD || viewChanged
+  }
+
+  _plotBboxToTileBbox(xDomain, yDomain) {
+    // Reproject all four corners and take the axis-aligned bounding box
+    const corners = [
+      [xDomain[0], yDomain[0]],
+      [xDomain[1], yDomain[0]],
+      [xDomain[0], yDomain[1]],
+      [xDomain[1], yDomain[1]],
+    ].map(pt => this._plotToTile(pt))
+
+    return {
+      minX: Math.min(...corners.map(c => c[0])),
+      maxX: Math.max(...corners.map(c => c[0])),
+      minY: Math.min(...corners.map(c => c[1])),
+      maxY: Math.max(...corners.map(c => c[1])),
+    }
+  }
+
+  _computeNeededTiles(xDomain, yDomain, viewport) {
+    const tileBbox = this._plotBboxToTileBbox(xDomain, yDomain)
+    const source = this.source
+
+    if (source.type === 'wms') {
+      // WMS: one image covering the full viewport
+      const wmsUrl = buildWmsUrl(source, tileBbox, this.tileCrs, viewport.width, viewport.height)
+      return [{ key: wmsUrl, bbox: tileBbox, url: wmsUrl, type: 'wms' }]
+    }
+
+    // XYZ / WMTS: standard tile grid
+    const minZoom = source.minZoom ?? 0
+    const maxZoom = source.maxZoom ?? 19
+    const z = optimalZoom(tileBbox, viewport.width, viewport.height, minZoom, maxZoom)
+
+    const [xMin, yMax] = mercToTileXY(tileBbox.minX, tileBbox.minY, z)  // note: minY → top tile
+    const [xMax, yMin] = mercToTileXY(tileBbox.maxX, tileBbox.maxY, z)  // maxY → bottom tile
+    // Clamp to valid tile range
+    const tileCount = Math.pow(2, z)
+    const txMin = Math.max(0, xMin)
+    const txMax = Math.min(tileCount - 1, xMax)
+    const tyMin = Math.max(0, yMin)
+    const tyMax = Math.min(tileCount - 1, yMax)
+
+    // Safety cap: if the computed tile range is still unreasonably large (e.g.
+    // due to a degenerate bbox or an unsupported CRS), bail out rather than
+    // allocating millions of objects and crashing the tab.
+    const MAX_TILES = 512
+    if ((txMax - txMin + 1) * (tyMax - tyMin + 1) > MAX_TILES) {
+      console.warn(`[TileLayer] tile range too large (${txMax - txMin + 1}×${tyMax - tyMin + 1} at z=${z}), skipping`)
+      return []
+    }
+
+    const tiles = []
+    for (let ty = tyMin; ty <= tyMax; ty++) {
+      for (let tx = txMin; tx <= txMax; tx++) {
+        const url = source.type === 'wmts'
+          ? buildWmtsUrl(source, z, tx, ty)
+          : buildXyzUrl(source, z, tx, ty)
+        const bbox = tileToMercBbox(tx, ty, z)
+        tiles.push({ key: `${z}/${tx}/${ty}`, bbox, url, type: source.type })
+      }
+    }
+    return tiles
+  }
+
+  syncTiles(xDomain, yDomain, viewport) {
+    if (!this._domainChanged(xDomain, yDomain, viewport)) return
+
+    this._lastXDomain = xDomain.slice()
+    this._lastYDomain = yDomain.slice()
+    this._lastViewport = viewport ? { width: viewport.width, height: viewport.height } : null
+
+    const needed = this._computeNeededTiles(xDomain, yDomain, viewport)
+    this._neededKeys = new Set(needed.map(t => t.key))
+
+    // Start loading tiles not yet in cache
+    for (const tileSpec of needed) {
+      if (!this.tiles.has(tileSpec.key)) {
+        this._loadTile(tileSpec)
+      }
+    }
+    // Eviction is deferred to _loadTile() so old tiles stay visible while new ones load.
+  }
+
+  _evictTile(key) {
+    const tile = this.tiles.get(key)
+    if (!tile) return
+    if (tile.texture) tile.texture.destroy()
+    if (tile.posBuffer) tile.posBuffer.destroy()
+    if (tile.uvBuffer) tile.uvBuffer.destroy()
+    if (tile.elements) tile.elements.destroy()
+    this.tiles.delete(key)
+    const i = this.accessOrder.indexOf(key)
+    if (i >= 0) this.accessOrder.splice(i, 1)
+  }
+
+  async _loadTile(tileSpec) {
+    this.tiles.set(tileSpec.key, { status: 'loading' })
+    this.accessOrder.push(tileSpec.key)
+
+    try {
+      const img = new Image()
+      img.crossOrigin = 'anonymous'
+      await new Promise((resolve, reject) => {
+        img.onload = resolve
+        img.onerror = () => reject(new Error(`Failed to load tile: ${tileSpec.url}`))
+        img.src = tileSpec.url
+      })
+
+      // Check we haven't been evicted while loading
+      if (!this.tiles.has(tileSpec.key)) return
+
+      const mesh = buildTileMesh(tileSpec.bbox, this.tileCrs, this.plotCrs, this.tessellation)
+      const texture = this.regl.texture({ data: img, flipY: false, min: 'linear', mag: 'linear' })
+      const posBuffer = this.regl.buffer(mesh.positions)
+      const uvBuffer = this.regl.buffer(mesh.uvs)
+      const elements = this.regl.elements({ data: mesh.indices, type: 'uint16' })
+
+      this.tiles.set(tileSpec.key, {
+        status: 'loaded',
+        texture,
+        posBuffer,
+        uvBuffer,
+        elements,
+        indexCount: mesh.indices.length,
+      })
+
+      // Now that this tile is ready, evict old tiles that are no longer needed.
+      // Eviction is done here (not in syncTiles) so superseded tiles stay visible
+      // as a fallback while their replacements are still loading.
+      const neededKeys = this._neededKeys
+      if (this.source.type === 'wms') {
+        // WMS covers the whole viewport with one image; always evict non-needed tiles.
+        for (const key of [...this.tiles.keys()]) {
+          if (key !== tileSpec.key && !neededKeys.has(key)) this._evictTile(key)
+        }
+      } else if (this.tiles.size > MAX_TILE_CACHE) {
+        // XYZ/WMTS: LRU eviction only when the cache grows too large.
+        for (const key of this.accessOrder) {
+          if (key !== tileSpec.key && !neededKeys.has(key) && this.tiles.has(key)) {
+            this._evictTile(key)
+            if (this.tiles.size <= MAX_TILE_CACHE) break
+          }
+        }
+      }
+
+      this.onLoad()
+    } catch (err) {
+      // Mark as failed so we don't retry endlessly (remove from cache to allow future retry on pan)
+      this.tiles.delete(tileSpec.key)
+      const i = this.accessOrder.indexOf(tileSpec.key)
+      if (i >= 0) this.accessOrder.splice(i, 1)
+      console.warn(`[TileLayer] ${err.message}`)
+    }
+  }
+
+  get loadedTiles() {
+    return [...this.tiles.values()].filter(t => t.status === 'loaded')
+  }
+
+  destroy() {
+    for (const key of [...this.tiles.keys()]) {
+      this._evictTile(key)
+    }
+  }
+}
+
+// ─── GLSL ─────────────────────────────────────────────────────────────────────
+
+const TILE_VERT = `
+  precision mediump float;
+  attribute vec2 position;
+  attribute vec2 uv;
+  uniform vec2 xDomain;
+  uniform vec2 yDomain;
+  uniform float xScaleType;
+  uniform float yScaleType;
+  varying vec2 vUv;
+
+  float normalize_axis(float v, vec2 domain, float scaleType) {
+    float vt = scaleType > 0.5 ? log(v) : v;
+    float d0 = scaleType > 0.5 ? log(domain.x) : domain.x;
+    float d1 = scaleType > 0.5 ? log(domain.y) : domain.y;
+    return (vt - d0) / (d1 - d0);
+  }
+
+  void main() {
+    float nx = normalize_axis(position.x, xDomain, xScaleType);
+    float ny = normalize_axis(position.y, yDomain, yScaleType);
+    gl_Position = vec4(nx * 2.0 - 1.0, ny * 2.0 - 1.0, 0.0, 1.0);
+    vUv = uv;
+  }
+`
+
+const TILE_FRAG = `
+  precision mediump float;
+  uniform sampler2D tileTexture;
+  uniform float opacity;
+  varying vec2 vUv;
+
+  void main() {
+    vec4 color = texture2D(tileTexture, vUv);
+    gl_FragColor = vec4(color.rgb, color.a * opacity);
+  }
+`
+
+// ─── TileLayerType ────────────────────────────────────────────────────────────
+
+class TileLayerType extends LayerType {
+  constructor() {
+    super({ name: 'tile' })
+  }
+
+  schema(_data) {
+    return {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      properties: {
+        source: {
+          type: 'object',
+          description: 'Tile source configuration. Exactly one key (xyz, wms, or wmts) must be present.',
+          anyOf: [
+            {
+              title: 'XYZ',
+              properties: {
+                xyz: {
+                  type: 'object',
+                  properties: {
+                    url: { type: 'string', default: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', description: 'URL template with {z}, {x}, {y}, optional {s}' },
+                    subdomains: { type: 'array', items: { type: 'string' }, default: ['a', 'b', 'c'], description: 'Subdomain letters for {s}' },
+                    minZoom: { type: 'integer', default: 0 },
+                    maxZoom: { type: 'integer', default: 19 },
+                  },
+                  required: ['url'],
+                  default: {
+                    url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
+                    subdomains: ['a', 'b', 'c'],
+                  },
+                },
+              },
+              required: ['xyz'],
+              additionalProperties: false,
+            },
+            {
+              title: 'WMS',
+              properties: {
+                wms: {
+                  type: 'object',
+                  properties: {
+                    url: { type: 'string', default: 'https://gibs.earthdata.nasa.gov/wms/epsg3857/best/wms.cgi', description: 'WMS service base URL' },
+                    layers: { type: 'string', default: 'BlueMarble_NextGeneration', description: 'Comma-separated layer names' },
+                    styles: { type: 'string', default: '', description: 'Comma-separated style names (optional)' },
+                    format: { type: 'string', default: 'image/jpeg' },
+                    version: { type: 'string', enum: ['1.1.1', '1.3.0'], default: '1.1.1' },
+                    transparent: { type: 'boolean', default: false },
+                  },
+                  required: ['url', 'layers'],
+                  default: {
+                    url: 'https://gibs.earthdata.nasa.gov/wms/epsg3857/best/wms.cgi',
+                    layers: 'BlueMarble_NextGeneration',
+                    format: 'image/jpeg',
+                    transparent: false,
+                    version: '1.1.1',
+                  },
+                },
+              },
+              required: ['wms'],
+              additionalProperties: false,
+            },
+            {
+              title: 'WMTS',
+              properties: {
+                wmts: {
+                  type: 'object',
+                  properties: {
+                    url: { type: 'string', default: 'https://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/WMTS', description: 'WMTS base URL (RESTful template or KVP endpoint)' },
+                    layer: { type: 'string', default: 'USGSTopo' },
+                    style: { type: 'string', default: 'default' },
+                    format: { type: 'string', default: 'image/jpeg' },
+                    tileMatrixSet: { type: 'string', default: 'GoogleMapsCompatible' },
+                    minZoom: { type: 'integer', default: 0 },
+                    maxZoom: { type: 'integer', default: 19 },
+                  },
+                  required: ['url', 'layer'],
+                  default: {
+                    url: 'https://basemap.nationalmap.gov/arcgis/rest/services/USGSTopo/MapServer/WMTS',
+                    layer: 'USGSTopo',
+                    tileMatrixSet: 'GoogleMapsCompatible',
+                    format: 'image/jpeg',
+                  },
+                },
+              },
+              required: ['wmts'],
+              additionalProperties: false,
+            },
+          ],
+          default: {
+            xyz: {
+              url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
+              subdomains: ['a', 'b', 'c'],
+            },
+          },
+        },
+        tileCrs: {
+          type: 'string',
+          default: 'EPSG:3857',
+          description: 'CRS of the tile service. For XYZ/WMTS this is the tile grid CRS; for WMS this becomes the CRS/SRS parameter in GetMap requests. Defaults to EPSG:3857 (Web Mercator).',
+          examples: ['EPSG:3857', 'EPSG:4326'],
+        },
+        plotCrs: {
+          type: 'string',
+          description: 'CRS of the plot axes (e.g. "EPSG:26911"). Defaults to tileCrs (no reprojection).',
+        },
+        tessellation: {
+          type: 'integer',
+          default: 8,
+          minimum: 1,
+          description: 'Grid resolution (N×N quads per tile) for reprojection accuracy.',
+        },
+        opacity: {
+          type: 'number',
+          default: 1.0,
+          minimum: 0,
+          maximum: 1,
+        },
+        xAxis: { type: 'string', enum: AXES.filter(a => a.includes('x')), default: 'xaxis_bottom' },
+        yAxis: { type: 'string', enum: AXES.filter(a => a.includes('y')), default: 'yaxis_left' },
+      },
+      required: ['source'],
+    }
+  }
+
+  resolveAxisConfig(parameters, _data) {
+    const {
+      xAxis = 'xaxis_bottom',
+      yAxis = 'yaxis_left',
+      plotCrs,
+      tileCrs,
+    } = parameters
+    const effectiveTileCrs = tileCrs ?? 'EPSG:3857'
+    const effectivePlotCrs = plotCrs ?? effectiveTileCrs
+    return {
+      xAxis,
+      xAxisQuantityKind: crsToQkX(effectivePlotCrs),
+      yAxis,
+      yAxisQuantityKind: crsToQkY(effectivePlotCrs),
+      colorAxisQuantityKinds: [],
+      filterAxisQuantityKinds: [],
+    }
+  }
+
+  createLayer(parameters, _data) {
+    const {
+      xAxis = 'xaxis_bottom',
+      yAxis = 'yaxis_left',
+      plotCrs,
+      tileCrs,
+    } = parameters
+    const effectiveTileCrs = tileCrs ?? 'EPSG:3857'
+    const effectivePlotCrs = plotCrs ?? effectiveTileCrs
+
+    // Return a plain object: compatible with the render loop but no Float32Array required.
+    return [{
+      type: this,
+      xAxis,
+      yAxis,
+      xAxisQuantityKind: crsToQkX(effectivePlotCrs),
+      yAxisQuantityKind: crsToQkY(effectivePlotCrs),
+      colorAxes: [],
+      filterAxes: [],
+      vertexCount: 0,
+      instanceCount: null,
+      attributes: {},
+      domains: {},
+      uniforms: {},
+      parameters,
+    }]
+  }
+
+  createDrawCommand(regl, layer, plot) {
+    const {
+      source: sourceSpec,
+      tileCrs,
+      plotCrs,
+      tessellation = 8,
+      opacity = 1.0,
+    } = layer.parameters
+    const source = resolveSource(sourceSpec)
+    const effectiveTileCrs = tileCrs ?? 'EPSG:3857'
+    const effectivePlotCrs = plotCrs ?? effectiveTileCrs
+
+    // Create the regl draw command immediately — it doesn't need CRS info
+    const drawTile = regl({
+      vert: TILE_VERT,
+      frag: TILE_FRAG,
+      attributes: {
+        position: regl.prop('posBuffer'),
+        uv: regl.prop('uvBuffer'),
+      },
+      elements: regl.prop('elements'),
+      uniforms: {
+        xDomain: regl.prop('xDomain'),
+        yDomain: regl.prop('yDomain'),
+        xScaleType: regl.prop('xScaleType'),
+        yScaleType: regl.prop('yScaleType'),
+        tileTexture: regl.prop('texture'),
+        opacity: opacity,
+      },
+      viewport: regl.prop('viewport'),
+      blend: {
+        enable: true,
+        func: { src: 'src alpha', dst: 'one minus src alpha' },
+      },
+      depth: { enable: false },
+    })
+
+    // TileManager is created once both CRS definitions are ready.
+    // Renders nothing until then; scheduleRender() triggers a repaint once ready.
+    let tileManager = null
+
+    Promise.all([
+      ensureCrsDefined(effectiveTileCrs),
+      ensureCrsDefined(effectivePlotCrs),
+    ]).then(() => {
+      try {
+        tileManager = new TileManager({
+          regl,
+          source,
+          tileCrs: effectiveTileCrs,
+          plotCrs: effectivePlotCrs,
+          tessellation,
+          onLoad: () => plot.scheduleRender(),
+        })
+        plot.scheduleRender()
+      } catch (_) {
+        // regl may have been destroyed if the plot was updated before CRS resolved
+      }
+    }).catch(err => {
+      console.error('[TileLayer] CRS initialization failed:', err)
+    })
+
+    return (props) => {
+      if (!tileManager) return
+      tileManager.syncTiles(props.xDomain, props.yDomain, props.viewport)
+      for (const tile of tileManager.loadedTiles) {
+        drawTile({
+          xDomain: props.xDomain,
+          yDomain: props.yDomain,
+          xScaleType: props.xScaleType,
+          yScaleType: props.yScaleType,
+          viewport: props.viewport,
+          posBuffer: tile.posBuffer,
+          uvBuffer: tile.uvBuffer,
+          elements: tile.elements,
+          texture: tile.texture,
+        })
+      }
+    }
+  }
+}
+
+export const tileLayerType = new TileLayerType()
+registerLayerType('tile', tileLayerType)
+
+export { TileLayerType }

package/src/index.js

@@ -1,5 +1,6 @@
 export { LayerType } from "./LayerType.js"
 export { Layer } from "./Layer.js"
+export { Data } from "./Data.js"
 export { AxisRegistry, AXES } from "./AxisRegistry.js"
 export { ColorAxisRegistry } from "./ColorAxisRegistry.js"
 export { FilterAxisRegistry, buildFilterGlsl } from "./FilterAxisRegistry.js"
@@ -16,6 +17,8 @@ export { Float } from "./Float.js"
 export { Filterbar } from "./Filterbar.js"
 export { filterbarLayerType } from "./FilterbarLayer.js"
 export { FilterbarFloat } from "./FilterbarFloat.js"
+export { tileLayerType, TileLayerType } from "./TileLayer.js"
+export { registerEpsgDef, parseCrsCode, crsToQkX, crsToQkY, qkToEpsgCode, reproject } from "./EpsgUtils.js"
 
 // Register all matplotlib colorscales (side-effect import)
 import "./MatplotlibColorscales.js"