Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// 3D data visualisation — scatter, surface, bars, globe — on the WebGL2 layer.
//
// WHAT WAS ASKED FOR IS THE LOOK, NOT THE LIBRARY. three.js is 600 KB+ against
// a 43 KB shell, and this project already deleted ECharts at 630 KB and refused
// DuckDB-WASM at 9.4 MB. But the expensive part of three.js is GENERALITY — a
// scene graph, a material system, loaders for a dozen formats, a raycaster, a
// shadow pipeline — and none of it is visible to a reader looking at a scatter
// plot. FOUR fixed chart types need one camera (gl.ts has it), four geometry
// builders, and two shaders. That is what is here.
//
// buildScene IS PURE, and that is the whole testing strategy. Every bug in 3D
// geometry renders SOMETHING, plausibly, and no one looking at the screen can
// tell that a surface is inside out or that a normal is 1.4 long. Geometry is
// arithmetic, arithmetic runs in node, so all of it lives above the GL line and
// the rig checks the numbers. Below `mountViz3d` nothing is testable, so that
// half is kept as boring as it can be.
//
// EVERYTHING IS NORMALISED INTO A UNIT CUBE, PER AXIS INDEPENDENTLY. Two
// reasons, both load-bearing. (1) Attributes are f32: a timestamp in ms or
// revenue in pence has more significant digits than 24 bits of mantissa, and
// the plot visibly quantises into rows. (2) Revenue in millions against margin
// in [0,1] shares one cube only if each axis carries its OWN scale — otherwise
// the margin axis collapses to a line, which is not a plot of the data, it is a
// plot of the units. The real numbers live on in `Scene.axes` and the legend.
//
// LIGHTING EXISTS ONCE. `shade()` below is the model, and the GLSL in this file
// is a literal transliteration of it. The 2D fallback shades on the CPU with
// the same function, so a machine without WebGL2 gets the same picture rather
// than a different one — two lighting models is a bug that only ever shows up
// on someone else's laptop. Flat unlit geometry is what makes hand-rolled 3D
// look amateur; a directional key light plus a hemisphere fill is most of what
// separates it from three.js, and it costs four lines in a vertex shader.
//
// THERE IS NO TRANSPARENCY, DELIBERATELY. Correct alpha needs the geometry
// sorted back-to-front from the CURRENT camera, which is a sort per orbit frame
// (100k points, every mouse move) and is STILL wrong for interpenetrating
// triangles and for anything with a cyclic overlap — the surface passing
// through its own bar chart is exactly that case. The depth buffer is exact,
// order-independent and free. So every mesh is opaque, and scatter points are
// discs cut out with `discard` rather than blended: a marginally harder edge in
// exchange for depth that is right at any point count.
//
// NULLS ARE DROPPED, NEVER ZEROED, and the count is reported. chart.ts's rule
// (`nulls are gaps, not zeroes`) matters more in 3D, because a missing value
// coerced to 0 is not an obvious gap in a surface — it is a crater, and craters
// look like findings.
//
// THE FALLBACK IS A PICTURE. `supportsWebGL2()` is false on old iPads, in
// locked-down enterprise browsers, over remote desktop, and in the shell's own
// scriptless preview. A workbook that opens to an empty rectangle there is
// worse than one that never offered 3D at all, so the same Scene is projected
// with the same camera and the same lighting into an SVG.
import {
GLView, Orbit, supportsWebGL2, project,
normalize as vnorm, dot as vdot,
type Mat4, type Vec3,
} from './gl.ts'
import type { Column, TableSheet } from './model.ts'
import { readCell } from './store.ts'
import { isErr } from './formula.ts'
import { t } from './i18n.ts'
// --- colour -----------------------------------------------------------------
/** Channels in 0..1, because that is what a shader wants and what mixing needs. */
export type RGB = [number, number, number]
const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v)
const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
/** An unparseable colour is GREY, not black — black reads as "lit from behind". */
export function hexToRgb(hex: string): RGB {
const s = String(hex).trim().replace(/^#/, '')
const full = s.length === 3 ? s[0] + s[0] + s[1] + s[1] + s[2] + s[2] : s.slice(0, 6)
const n = parseInt(full, 16)
if (full.length < 6 || !Number.isFinite(n)) return [0.5, 0.5, 0.5]
return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255]
}
export const rgbToHex = (c: RGB): string =>
'#' + [c[0], c[1], c[2]]
.map((v) => Math.round(clamp01(v) * 255).toString(16).padStart(2, '0'))
.join('')
/**
* Mix in LINEAR light, not in sRGB.
*
* sRGB is a transfer curve, so the naive midpoint of black and white is 0.5,
* which displays as about 21% of the light — every hand-rolled ramp has that
* mud in the middle, and on a surface it reads as a band of shadow that is not
* in the data. condfmt.mixColors reached the same conclusion for cell
* backgrounds; this one works in floats because a vertex colour is a float.
*/
export function mixRgb(a: RGB, b: RGB, t: number): RGB {
const u = clamp01(t)
const m = (x: number, y: number) => Math.sqrt(x * x * (1 - u) + y * y * u)
return [m(a[0], b[0]), m(a[1], b[1]), m(a[2], b[2])]
}
/**
* Sequential ramps, all monotonic in lightness. That is not decoration: a ramp
* that is not monotonic in lightness (the rainbow) invents ridges where the
* data is smooth, and is unreadable to the ~8% of readers with a red/green
* deficiency. `balance` is the exception and is diverging on purpose — for a
* signed measure, where the MIDDLE is the meaningful value.
*/
export const RAMPS: Record<string, string[]> = {
viridis: ['#3B1E54', '#3C558C', '#2E8B8B', '#63B36A', '#CFD84A'],
thermal: ['#12123A', '#5B2A86', '#C24B6E', '#F08A3C', '#F7E15F'],
ice: ['#0B1B33', '#1B4A73', '#3E86A8', '#84C1CD', '#DCEFF2'],
balance: ['#2166AC', '#7FB3D3', '#F2F2F0', '#EF9A7B', '#B2182B'],
}
/**
* dash's chart palette, repeated rather than imported: chart.ts keeps it as a
* default PARAMETER, so there is nothing to import — and a 3D view that
* disagreed with the 2D chart beside it about what colour "North" is would be
* its own bug report.
*/
export const CATEGORY_COLORS = ['#F7A600', '#5B8DEF', '#2FB47C', '#E1616C', '#8B6FD3', '#3FA9B8']
/**
* Sample a ramp at `t` in [0, 1]. The ends are EXACT: `rampColor(0)` is the
* first stop and `rampColor(1)` is the last, with no interpolation error, so
* the legend's swatches and the extreme vertices are the same colours.
*/
export function rampColor(t: number, stops: RGB[]): RGB {
if (!stops.length) return [0.5, 0.5, 0.5]
if (stops.length === 1) return stops[0]
const u = clamp01(Number.isFinite(t) ? t : 0)
const x = u * (stops.length - 1)
const i = Math.min(stops.length - 2, Math.floor(x))
return mixRgb(stops[i], stops[i + 1], x - i)
}
// --- lighting ---------------------------------------------------------------
/**
* The key light, in WORLD space: over the viewer's left shoulder and above.
* Fixed to the world, not to the camera, so orbiting a surface changes which
* slopes catch the light — a headlight rigidly attached to the eye flattens
* everything and is the single clearest tell of hand-rolled 3D.
*/
export const LIGHT: Vec3 = vnorm([-0.45, 0.82, 0.55])
/** How much light reaches a surface facing away. Never 0: an unlit face that
* goes pure black reads as a hole in the mesh. */
export const AMBIENT = 0.38
/**
* The lighting model, and the ONLY copy of it. The GLSL below is a line-for-line
* transliteration, and the SVG fallback calls this directly.
*
* Lambert for the key, plus a hemisphere fill (`sky`) so the underside of a
* surface is dim rather than uniform — with flat ambient, everything facing away
* from the light is exactly one colour and the shape disappears into a silhouette.
*
* `light` is a parameter because the point-sprite path shades in VIEW space,
* where the light is the world light run through the view rotation. Same model,
* same numbers, different basis.
*/
export function shadeWith(n: Vec3, light: Vec3, ambient = AMBIENT): number {
const d = Math.max(0, vdot(n, light))
const sky = 0.55 + 0.45 * n[1]
return Math.min(1, ambient * sky + (1 - ambient) * d)
}
/** `shadeWith` against the world key light — what a mesh normal wants. */
export const shade = (n: Vec3, ambient = AMBIENT): number => shadeWith(n, LIGHT, ambient)
/**
* A DIRECTION through the view matrix — upper 3x3 only.
*
* `transformPoint` is wrong here: it adds the translation column, so the light
* direction would depend on where the camera IS rather than which way it faces,
* and the scene would appear to change its lighting when you pan. Needed
* because the point-sprite shader reconstructs its normal in VIEW space.
*/
export function dirToView(view: Mat4, d: Vec3): Vec3 {
return vnorm([
view[0] * d[0] + view[4] * d[1] + view[8] * d[2],
view[1] * d[0] + view[5] * d[1] + view[9] * d[2],
view[2] * d[0] + view[6] * d[1] + view[10] * d[2],
])
}
// --- the scene --------------------------------------------------------------
export type Viz3dKind = 'scatter' | 'surface' | 'bars' | 'globe'
/** What each kind is called, as a heading — English, translated at render. */
export const VIZ_TITLE: Record<Viz3dKind, string> = {
scatter: '3D scatter', surface: '3D surface', bars: '3D bars', globe: 'Globe',
}
/** …and on the kind button, which cycles through them. */
export const VIZ_KIND_LABEL: Record<Viz3dKind, string> = {
scatter: 'Scatter', surface: 'Surface', bars: 'Bars', globe: 'Globe',
}
export type Agg = 'sum' | 'avg' | 'count' | 'min' | 'max'
/**
* What to draw, from which columns.
*
* The binding speaks the CHART's language and the scene speaks GL's. For a
* surface and for bars that means `z = f(x, y)`: `x` and `y` are the two axes
* and `z` is the height — which lands on the scene's Y, because Y is up in GL
* and in gl.ts's Orbit. For a scatter there is no remapping; x/y/z are three
* spatial axes and map straight through.
*/
export interface Viz3dBinding {
kind: Viz3dKind
/** scatter: the three spatial axes. surface/bars: x and y are the grid axes,
* z is the measured value. */
x?: string
y?: string
z?: string
/** numeric → ramp; text → categorical palette. */
color?: string
/** numeric; scatter and globe only. Maps to point AREA, not radius. */
size?: string
lat?: string
lon?: string
/** how the value column collapses within one grid cell. Default 'sum'. */
agg?: Agg
/** target bin count for a numeric grid axis. Default 16. */
bins?: number
/** a RAMPS key, or explicit hex stops. */
ramp?: string | string[]
}
/**
* One draw call's worth of geometry. Typed arrays because that is what goes
* into a GPU buffer with no conversion, and because a 100k-point scatter as
* plain arrays of objects is 40 MB of garbage per rebuild.
*/
export interface Mesh {
mode: 'triangles' | 'lines' | 'points'
/** xyz per vertex */
positions: Float32Array
/** rgb per vertex, 0..1 */
colors: Float32Array
/** UNIT normals, xyz per vertex. Absent on `lines` (unlit) and on `points`
* (the sprite shader derives a sphere normal per FRAGMENT — one vertex per
* row instead of the ~80 a real sphere would cost). */
normals?: Float32Array
indices?: Uint32Array
/** per-point radius multiplier; `points` only. */
sizes?: Float32Array
lit: boolean
/** closed geometry, so the SVG fallback may cull back faces. False on an open
* surface, which must stay visible from below. */
cull?: boolean
}
export interface AxisMeta {
title: string
kind: 'value' | 'category'
min?: number
max?: number
labels?: string[]
}
export interface Legend {
title: string
kind: 'ramp' | 'categories'
ramp?: string[]
min?: number
max?: number
items?: Array<{ label: string; color: string }>
}
export interface Scene {
kind: Viz3dKind
meshes: Mesh[]
bounds: { min: Vec3; max: Vec3 }
center: Vec3
radius: number
axes: AxisMeta[]
legend?: Legend
/** rows the binding looked at */
rows: number
/** rows a bound column had no number for. Dropped, and SAID so — a viewer
* that quietly plots 4,000 of 5,000 rows is a wrong answer that looks right. */
dropped: number
/** set when there is nothing to draw, and it says WHY. `mountViz3d` and the
* SVG fallback both render this sentence instead of an empty rectangle. */
empty?: string
}
/** `radius` is 1, never 0: a zero-radius scene puts the camera AT the target,
* lookAt's forward vector is zero-length, and the matrix is NaN. */
const emptyScene = (kind: Viz3dKind, why: string, rows = 0): Scene => ({
kind,
meshes: [],
bounds: { min: [0, 0, 0], max: [0, 0, 0] },
center: [0, 0, 0],
radius: 1,
axes: [],
rows,
dropped: 0,
empty: why,
})
// --- reading the sheet ------------------------------------------------------
/** Never coerces: a blank, a formula error and "n/a" are all `null`, and null
* rows are dropped rather than plotted at the origin. */
const num = (v: unknown): number | null => {
if (v == null || v === '' || isErr(v)) return null
const n = typeof v === 'number' ? v : Number(String(v).replace(/[,\s£$€¥%]/g, ''))
return Number.isFinite(n) ? n : null
}
const fmtNum = (v: number): string => {
if (!Number.isFinite(v)) return ''
const a = Math.abs(v)
if (a >= 1e6 || (a > 0 && a < 1e-3)) return v.toExponential(2)
return String(Math.round(v * 1000) / 1000)
}
/**
* Map finite values onto [-1, 1].
*
* A ZERO EXTENT MAPS TO 0, not to NaN. One constant column — and a filtered
* slice very often has one — would otherwise divide by zero, every position in
* the scene becomes NaN, GL draws absolutely nothing, and there is no error
* anywhere to explain it.
*/
function scaler(vals: Array<number | null>): { lo: number; hi: number; to: (v: number) => number } {
let lo = Infinity
let hi = -Infinity
for (const v of vals) {
if (v === null) continue
if (v < lo) lo = v
if (v > hi) hi = v
}
if (!Number.isFinite(lo)) { lo = 0; hi = 0 }
const span = hi - lo
return { lo, hi, to: (v) => (span > 0 ? ((v - lo) / span) * 2 - 1 : 0) }
}
/** 0..1 within the observed range; a zero range is 0.5 (the middle of the ramp,
* which is honest about "every value here is the same"). */
const norm01 = (v: number, lo: number, hi: number): number =>
hi > lo ? clamp01((v - lo) / (hi - lo)) : 0.5
// --- point sizes ------------------------------------------------------------
const SIZE_MIN = 0.62
const SIZE_MAX = 2.55
/**
* Value → point RADIUS, with AREA proportional to the value.
*
* Mapping the value straight to the radius is the classic bubble-chart
* exaggeration: the reader compares the discs by area, so a 4x number drawn at
* 4x radius looks 16x. Interpolating in area and taking the root is one `sqrt`
* and the difference between a chart and a misrepresentation.
*/
const sizeFor = (t: number): number =>
Math.sqrt(SIZE_MIN * SIZE_MIN + clamp01(t) * (SIZE_MAX * SIZE_MAX - SIZE_MIN * SIZE_MIN))
// --- grid axes --------------------------------------------------------------
const DEFAULT_BINS = 16
/** A surface with 200 categories on a side is 80,000 quads nobody can read. */
const AXIS_MAX_SURFACE = 128
/** Bars cost 24 vertices each, so their cap is tighter — 64x64 is 98k vertices. */
const AXIS_MAX_BARS = 64
interface Axis {
labels: string[]
/** row → bucket index; -1 means this row has no place on this axis. */
slot: number[]
numeric: boolean
min?: number
max?: number
}
/**
* Turn a column into an ordered set of buckets.
*
* ORDER IS THE DECISION HERE. A numeric axis is ASCENDING, because a surface
* interpolates between adjacent samples and interpolating between out-of-order
* bins draws a shape that is not in the data. A text axis is FIRST-SEEN, the
* same rule chart.ts uses, and for the same reason: sorting month names
* alphabetically gives Apr, Aug, Dec, and a surface over that is noise.
*
* Numeric columns with more distinct values than `bins` are binned to equal
* width; with fewer, each distinct value is its own slot. The mesh is ORDINAL
* (samples are evenly spaced regardless of value) — the labels carry the real
* numbers, and for the binned case the two agree exactly.
*/
function categorise(vals: unknown[], bins: number, cap: number): Axis {
const n = vals.length
const nums: Array<number | null> = new Array(n)
let numericCount = 0
let presentCount = 0
for (let i = 0; i < n; i++) {
const v = vals[i]
const blank = v == null || v === ''
if (!blank) presentCount++
const x = blank ? null : num(v)
nums[i] = x
if (x !== null) numericCount++
}
const slot = new Array<number>(n).fill(-1)
if (presentCount > 0 && numericCount === presentCount) {
const uniq = [...new Set(nums.filter((v): v is number => v !== null))].sort((a, b) => a - b)
if (uniq.length <= Math.max(2, bins)) {
const at = new Map(uniq.map((v, i) => [v, i]))
for (let i = 0; i < n; i++) if (nums[i] !== null) slot[i] = at.get(nums[i]!)!
return {
labels: uniq.map(fmtNum), slot, numeric: true,
min: uniq[0], max: uniq[uniq.length - 1],
}
}
const lo = uniq[0]
const hi = uniq[uniq.length - 1]
const k = Math.min(bins, cap)
const w = (hi - lo) / k
for (let i = 0; i < n; i++) {
const v = nums[i]
if (v === null) continue
// the top edge belongs to the LAST bin, not to a k+1'th one
slot[i] = w > 0 ? Math.min(k - 1, Math.floor((v - lo) / w)) : 0
}
const labels = Array.from({ length: k }, (_, i) => fmtNum(lo + w * (i + 0.5)))
return { labels, slot, numeric: true, min: lo, max: hi }
}
const labels: string[] = []
const at = new Map<string, number>()
for (let i = 0; i < n; i++) {
const v = vals[i]
if (v == null || v === '') continue
const s = String(v)
let k = at.get(s)
if (k === undefined) {
// past the cap the row is dropped rather than folded into an "other"
// bucket: an "other" column on a 3D chart is a bar whose height is an
// artefact of the cap, and readers total it.
if (labels.length >= cap) continue
k = labels.length
at.set(s, k)
labels.push(s)
}
slot[i] = k
}
return { labels, slot, numeric: false }
}
/** Collapse rows into (nx x ny) cells. `present` is what stops a missing cell
* becoming a crater at zero. */
function aggregateGrid(
nx: number, ny: number,
sx: number[], sy: number[],
zs: Array<number | null> | null,
agg: Agg,
): { v: Float64Array; present: Uint8Array; used: number } {
const cells = nx * ny
const v = new Float64Array(cells)
const count = new Float64Array(cells)
const present = new Uint8Array(cells)
let used = 0
for (let i = 0; i < sx.length; i++) {
const a = sx[i]
const b = sy[i]
if (a < 0 || b < 0) continue
const z = zs ? zs[i] : 1
if (agg !== 'count' && z === null) continue
const c = b * nx + a
used++
const first = present[c] === 0
present[c] = 1
count[c]++
if (agg === 'count') { v[c] = count[c]; continue }
const x = z as number
if (first) { v[c] = x; continue }
if (agg === 'sum' || agg === 'avg') v[c] += x
else if (agg === 'min') v[c] = Math.min(v[c], x)
else v[c] = Math.max(v[c], x)
}
if (agg === 'avg') for (let c = 0; c < cells; c++) if (present[c]) v[c] /= count[c]
return { v, present, used }
}
// --- geometry primitives ----------------------------------------------------
/**
* Per-vertex normals by AREA-WEIGHTED accumulation of face normals.
*
* Area weighting is not a nicety: an un-weighted average lets a sliver triangle
* — which a binned grid produces at its edges — pull the normal as hard as the
* big quad beside it, and the surface gains a bright seam that is not in the
* data. The un-normalised cross product IS twice the area, so the weighting is
* free: accumulate it before normalising.
*
* A vertex with no usable contribution (an isolated point, a degenerate fan)
* gets +Y rather than zero. A zero normal shades to pure black, which reads as
* a hole in the mesh rather than as the missing information it is.
*/
export function computeNormals(positions: Float32Array, indices: Uint32Array): Float32Array {
const out = new Float32Array(positions.length)
for (let t = 0; t + 2 < indices.length; t += 3) {
const ia = indices[t] * 3, ib = indices[t + 1] * 3, ic = indices[t + 2] * 3
const ax = positions[ib] - positions[ia]
const ay = positions[ib + 1] - positions[ia + 1]
const az = positions[ib + 2] - positions[ia + 2]
const bx = positions[ic] - positions[ia]
const by = positions[ic + 1] - positions[ia + 1]
const bz = positions[ic + 2] - positions[ia + 2]
const nx = ay * bz - az * by
const ny = az * bx - ax * bz
const nz = ax * by - ay * bx
for (const i of [ia, ib, ic]) {
out[i] += nx; out[i + 1] += ny; out[i + 2] += nz
}
}
for (let i = 0; i < out.length; i += 3) {
const l = Math.hypot(out[i], out[i + 1], out[i + 2])
if (l > 1e-12) { out[i] /= l; out[i + 1] /= l; out[i + 2] /= l }
else { out[i] = 0; out[i + 1] = 1; out[i + 2] = 0 }
}
return out
}
/** lat/long in DEGREES → a point on a sphere. lon 0 faces +Z and lat +90 is +Y,
* matching gl.ts's Orbit (azimuth 0 looks down +Z), so "the camera starts over
* the prime meridian" is true rather than approximately true. */
export function latLonToXyz(lat: number, lon: number, r = 1): Vec3 {
const p = (lat * Math.PI) / 180
const l = (lon * Math.PI) / 180
const c = Math.cos(p)
return [r * c * Math.sin(l), r * Math.sin(p), r * c * Math.cos(l)]
}
/**
* A UV sphere. Normals are the normalised POSITIONS — exact by construction,
* where computeNormals would only approximate them, and the poles (where a
* triangle fan's normals are least reliable) are the part of a globe people
* look at first.
*
* The seam column is duplicated so the grid is rectangular; the degenerate
* triangles at each pole are skipped rather than emitted zero-area, because a
* zero-area triangle contributes nothing but still costs a vertex fetch.
*/
function sphereMesh(r: number, segU: number, segV: number): {
positions: Float32Array; normals: Float32Array; indices: Uint32Array
} {
const cols = segU + 1
const rows = segV + 1
const positions = new Float32Array(cols * rows * 3)
const normals = new Float32Array(cols * rows * 3)
for (let j = 0; j < rows; j++) {
const lat = 90 - (180 * j) / segV
for (let i = 0; i < cols; i++) {
const lon = -180 + (360 * i) / segU
const p = latLonToXyz(lat, lon, r)
const k = (j * cols + i) * 3
positions[k] = p[0]; positions[k + 1] = p[1]; positions[k + 2] = p[2]
normals[k] = p[0] / r; normals[k + 1] = p[1] / r; normals[k + 2] = p[2] / r
}
}
const idx: number[] = []
for (let j = 0; j < segV; j++) {
for (let i = 0; i < segU; i++) {
const a = j * cols + i, b = a + 1, c = a + cols, d = c + 1
if (j !== 0) idx.push(a, c, b)
if (j !== segV - 1) idx.push(b, c, d)
}
}
return { positions, normals, indices: new Uint32Array(idx) }
}
/** The six faces of an axis-aligned box, wound counter-clockwise from OUTSIDE
* and carrying their own normals. Flat shading is CORRECT for a box, so these
* are NOT run through computeNormals — smoothed box corners look like melted
* wax, which is a different failure from an unlit one but just as visible. */
const BOX_FACES: Array<{ n: Vec3; c: Array<[number, number, number]> }> = [
{ n: [1, 0, 0], c: [[1, 0, 1], [1, 0, 0], [1, 1, 0], [1, 1, 1]] },
{ n: [-1, 0, 0], c: [[0, 0, 0], [0, 0, 1], [0, 1, 1], [0, 1, 0]] },
{ n: [0, 0, 1], c: [[0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]] },
{ n: [0, 0, -1], c: [[1, 0, 0], [0, 0, 0], [0, 1, 0], [1, 1, 0]] },
{ n: [0, 1, 0], c: [[0, 1, 1], [1, 1, 1], [1, 1, 0], [0, 1, 0]] },
{ n: [0, -1, 0], c: [[0, 0, 0], [1, 0, 0], [1, 0, 1], [0, 0, 1]] },
]
const FRAME_RGB: RGB = [0.42, 0.47, 0.56]
const FRAME_GRID = 4
/**
* The bounding box and floor grid.
*
* Not decoration: a perspective projection of unlabelled points has no scale
* cue at all, and readers systematically misjudge depth without a reference
* plane. Fifty vertices buys the whole depth read.
*/
function frameMesh(min: Vec3, max: Vec3): Mesh {
const pos: number[] = []
const col: number[] = []
const seg = (a: Vec3, b: Vec3, k: number) => {
pos.push(a[0], a[1], a[2], b[0], b[1], b[2])
for (let i = 0; i < 2; i++) col.push(FRAME_RGB[0] * k, FRAME_RGB[1] * k, FRAME_RGB[2] * k)
}
const [x0, y0, z0] = min
const [x1, y1, z1] = max
const corners: Vec3[] = [
[x0, y0, z0], [x1, y0, z0], [x1, y0, z1], [x0, y0, z1],
[x0, y1, z0], [x1, y1, z0], [x1, y1, z1], [x0, y1, z1],
]
const edges = [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5], [5, 6], [6, 7], [7, 4], [0, 4], [1, 5], [2, 6], [3, 7]]
for (const [a, b] of edges) seg(corners[a], corners[b], 1)
for (let i = 1; i < FRAME_GRID; i++) {
const t = i / FRAME_GRID
seg([x0 + (x1 - x0) * t, y0, z0], [x0 + (x1 - x0) * t, y0, z1], 0.5)
seg([x0, y0, z0 + (z1 - z0) * t], [x1, y0, z0 + (z1 - z0) * t], 0.5)
}
return {
mode: 'lines',
positions: new Float32Array(pos),
colors: new Float32Array(col),
lit: false,
}
}
function boundsOf(meshes: Mesh[]): { min: Vec3; max: Vec3 } {
const min: Vec3 = [Infinity, Infinity, Infinity]
const max: Vec3 = [-Infinity, -Infinity, -Infinity]
for (const m of meshes) {
const p = m.positions
for (let i = 0; i + 2 < p.length; i += 3) {
for (let k = 0; k < 3; k++) {
const v = p[i + k]
if (!Number.isFinite(v)) continue
if (v < min[k]) min[k] = v
if (v > max[k]) max[k] = v
}
}
}
for (let k = 0; k < 3; k++) {
if (!Number.isFinite(min[k])) { min[k] = 0; max[k] = 0 }
}
return { min, max }
}
function finish(kind: Viz3dKind, data: Mesh[], extra: Mesh[], rest: {
axes: AxisMeta[]; legend?: Legend; rows: number; dropped: number
}): Scene {
const bounds = boundsOf(data)
const center: Vec3 = [
(bounds.min[0] + bounds.max[0]) / 2,
(bounds.min[1] + bounds.max[1]) / 2,
(bounds.min[2] + bounds.max[2]) / 2,
]
const radius = Math.max(
0.5,
0.5 * Math.hypot(bounds.max[0] - bounds.min[0], bounds.max[1] - bounds.min[1], bounds.max[2] - bounds.min[2]),
)
return { kind, meshes: [...data, ...extra], bounds, center, radius, ...rest }
}
// --- buildScene -------------------------------------------------------------
const rampOf = (b: Viz3dBinding): { hex: string[]; rgb: RGB[] } => {
const hex = (Array.isArray(b.ramp) ? b.ramp : RAMPS[b.ramp ?? 'viridis']) ?? RAMPS.viridis
return { hex, rgb: hex.map(hexToRgb) }
}
/**
* Columns → geometry. PURE: no canvas, no document, no GL — which is what lets
* the rig check the vertex counts, the winding and the normals in node.
*
* `computed` is chart.ts's contract, unchanged: the grid hands in what it just
* recalculated so a formula column plots the numbers the reader is looking at
* rather than the raw column underneath them.
*/
export function buildScene(
sheet: TableSheet,
binding: Viz3dBinding,
computed?: Map<string, unknown[]>,
/**
* The view vector — `store.order[sheet.id]`: the canonical row indices the
* reader can SEE, in the order they see them, or null/undefined for every
* row. Exactly the argument `chart.ts` takes, for exactly the reason its
* comment gives, and this plot did not take it.
*
* Measured before the fix, on the starter workbook filtered to Region =
* North: the grid showed 3 rows, the status bar said "3 of 8 rows", the
* footer said £50,750 — and the plot beside all of that drew all EIGHT
* points, unchanged. That is the same failure as the footer that ignored the
* filter, in the panel next to the one where it was fixed: the fix went into
* `drawChart` and never crossed to `draw3d`.
*
* IT APPLIES TO EVERY BOUND COLUMN OR TO NONE, which is why it is projected
* HERE rather than at the call site. `buildScatter` and `buildGrid` zip x, y,
* z, colour and size BY INDEX; project one and not another and the plot pairs
* the wrong height with the wrong position — plausible, and wrong. Projecting
* inside `col` makes that unrepresentable: after this, `rows` counts the view
* and every array is view-local, so nothing downstream can disagree about
* which population it is describing. `scene.rows`/`scene.dropped` then report
* the VIEW's counts, which is what the reader is being told about.
*/
view?: number[] | null,
): Scene {
const all = sheet.rids.reduce((a, [, c]) => a + c, 0)
const rows = view ? view.length : all
if (all === 0) return emptyScene(binding.kind, t('this sheet has no rows yet'))
// A filter that matches nothing is not the same statement as an empty sheet,
// and saying "no rows yet" over a live filter would send the reader looking
// for data that is right there.
if (rows === 0) return emptyScene(binding.kind, t('the filter leaves no rows to plot'), all)
const nameOf = (id?: string): string =>
id ? (sheet.columns.find((c) => c.id === id)?.name ?? id) : ''
const col = (id?: string): unknown[] | null => {
if (!id) return null
const c = computed?.get(id)
if (c) return view ? view.map((r) => c[r]) : c
const d = sheet.data[id]
if (!d) return null
return Array.from({ length: rows }, (_, i) => readCell(d, view ? view[i] : i))
}
switch (binding.kind) {
case 'globe': return buildGlobe(binding, rows, col, nameOf)
case 'surface': return buildGrid(binding, rows, col, nameOf, true)
case 'bars': return buildGrid(binding, rows, col, nameOf, false)
default: return buildScatter(binding, rows, col, nameOf)
}
}
type ColFn = (id?: string) => unknown[] | null
type NameFn = (id?: string) => string
function buildScatter(b: Viz3dBinding, rows: number, col: ColFn, nameOf: NameFn): Scene {
const cx = col(b.x), cy = col(b.y), cz = col(b.z)
if (!cx || !cy || !cz) {
return emptyScene('scatter', t('a 3D scatter needs three numeric columns — pick X, Y and Z'), rows)
}
const xs = cx.map(num), ys = cy.map(num), zs = cz.map(num)
const cc = col(b.color)
const cNums = cc ? cc.map(num) : null
// A colour column is NUMERIC only if every value present in it is a number;
// one stray "n/a" must not silently turn a category axis into a ramp of NaN.
const colourNumeric = !!cNums && cc!.some((v, i) => v != null && v !== '' && cNums[i] !== null)
&& cc!.every((v, i) => v == null || v === '' || cNums![i] !== null)
const sc = col(b.size)
const sNums = sc ? sc.map(num) : null
const keep: number[] = []
for (let i = 0; i < rows; i++) if (xs[i] !== null && ys[i] !== null && zs[i] !== null) keep.push(i)
if (!keep.length) {
return emptyScene('scatter', t('no row has a number in all three of X, Y and Z'), rows)
}
const sx = scaler(xs), sy = scaler(ys), sz = scaler(zs)
const ramp = rampOf(b)
// Categorical colour: first-seen order, so the 3D view and the 2D chart agree
// about which category is which colour.
const catAt = new Map<string, number>()
const catLabels: string[] = []
if (cc && !colourNumeric) {
for (const i of keep) {
const v = cc[i]
if (v == null || v === '') continue
const s = String(v)
if (!catAt.has(s)) { catAt.set(s, catAt.size); catLabels.push(s) }
}
}
const cScale = colourNumeric ? scaler(cNums!) : null
const sScale = sNums ? scaler(sNums) : null
const positions = new Float32Array(keep.length * 3)
const colors = new Float32Array(keep.length * 3)
const sizes = new Float32Array(keep.length)
keep.forEach((row, k) => {
positions[k * 3] = sx.to(xs[row]!)
positions[k * 3 + 1] = sy.to(ys[row]!)
positions[k * 3 + 2] = sz.to(zs[row]!)
let rgb: RGB
if (cScale) rgb = rampColor(norm01(cNums![row] ?? cScale.lo, cScale.lo, cScale.hi), ramp.rgb)
else if (cc) {
const s = cc[row] == null ? '' : String(cc[row])
const j = catAt.get(s)
rgb = hexToRgb(j === undefined ? '#8A93A5' : CATEGORY_COLORS[j % CATEGORY_COLORS.length])
} else {
// No colour column: ramp over Z anyway. A monochrome cloud in perspective
// has no depth cue at all beyond point size, and the ramp is free.
rgb = rampColor(norm01(zs[row]!, sz.lo, sz.hi), ramp.rgb)
}
colors[k * 3] = rgb[0]; colors[k * 3 + 1] = rgb[1]; colors[k * 3 + 2] = rgb[2]
const sv = sScale && sNums![row] !== null ? norm01(sNums![row]!, sScale.lo, sScale.hi) : 0.42
sizes[k] = sizeFor(sv)
})
const data: Mesh[] = [{ mode: 'points', positions, colors, sizes, lit: true }]
const legend: Legend = cScale
? { title: nameOf(b.color), kind: 'ramp', ramp: ramp.hex, min: cScale.lo, max: cScale.hi }
: cc
? {
title: nameOf(b.color), kind: 'categories',
items: catLabels.slice(0, 8).map((l, i) => ({ label: l, color: CATEGORY_COLORS[i % CATEGORY_COLORS.length] })),
}
: { title: nameOf(b.z), kind: 'ramp', ramp: ramp.hex, min: sz.lo, max: sz.hi }
const bounds = boundsOf(data)
return finish('scatter', data, [frameMesh(bounds.min, bounds.max)], {
axes: [
{ title: nameOf(b.x), kind: 'value', min: sx.lo, max: sx.hi },
{ title: nameOf(b.y), kind: 'value', min: sy.lo, max: sy.hi },
{ title: nameOf(b.z), kind: 'value', min: sz.lo, max: sz.hi },
],
legend,
rows,
dropped: rows - keep.length,
})
}
function buildGrid(b: Viz3dBinding, rows: number, col: ColFn, nameOf: NameFn, surface: boolean): Scene {
const kind: Viz3dKind = surface ? 'surface' : 'bars'
const cx = col(b.x), cy = col(b.y)
/**
* A SURFACE DEFAULTS TO AVERAGE AND BARS TO SUM, and that is not a taste.
*
* A surface is a FIELD — `z = f(x, y)` sampled at points — so a cell holding
* two samples must report what the field is worth there, not their total.
* Summing makes the height depend on SAMPLING DENSITY: bin 40 evenly-spaced x
* values into 24 bins and some bins take two samples and some one, so a
* perfectly smooth field renders as a comb of spikes with a period set by the
* binning. Caught by looking at a `sin(r)/r` surface, which should be smooth
* and was not.
*
* A bar is a TOTAL — revenue by region and quarter — and summing is what
* anyone reading it means. The two defaults are opposite because the two
* charts are answering opposite questions.
*/
const agg = b.agg ?? (surface ? 'avg' : 'sum')
const cz = col(b.z)
if (!cx || !cy || (!cz && agg !== 'count')) {
return emptyScene(kind, surface
? t('a surface needs two axis columns and a value column')
: t('3D bars need two axis columns and a value column'), rows)
}
const cap = surface ? AXIS_MAX_SURFACE : AXIS_MAX_BARS
const bins = Math.max(2, Math.min(cap, b.bins ?? DEFAULT_BINS))
const ax = categorise(cx, bins, cap)
const ay = categorise(cy, bins, cap)
const nx = ax.labels.length
const ny = ay.labels.length
if (nx < 1 || ny < 1) return emptyScene(kind, t('the axis columns are empty'), rows)
if (surface && (nx < 2 || ny < 2)) {
// One row or one column of samples is a line, not a surface, and the quad
// loop would emit nothing at all — say so rather than draw an empty box.
return emptyScene(kind, t('a surface needs at least two distinct values on each axis'), rows)
}
const zs = cz ? cz.map(num) : null
const g = aggregateGrid(nx, ny, ax.slot, ay.slot, zs, agg)
if (!g.used) return emptyScene(kind, t('no row falls on both axes with a value'), rows)
const present: Array<number | null> = []
for (let c = 0; c < nx * ny; c++) present.push(g.present[c] ? g.v[c] : null)
const vs = scaler(present)
const ramp = rampOf(b)
const at = (i: number, n: number) => (n > 1 ? (i / (n - 1)) * 2 - 1 : 0)
const data: Mesh[] = []
if (surface) {
const positions = new Float32Array(nx * ny * 3)
const colors = new Float32Array(nx * ny * 3)
for (let j = 0; j < ny; j++) {
for (let i = 0; i < nx; i++) {
const c = j * nx + i
const k = c * 3
const v = g.present[c] ? g.v[c] : vs.lo
positions[k] = at(i, nx)
positions[k + 1] = vs.to(v)
positions[k + 2] = at(j, ny)
const rgb = rampColor(norm01(v, vs.lo, vs.hi), ramp.rgb)
colors[k] = rgb[0]; colors[k + 1] = rgb[1]; colors[k + 2] = rgb[2]
}
}
// A quad is emitted only when all FOUR corners were measured. Interpolating
// across a gap invents a value, and on a surface an invented value is
// indistinguishable from a measured one.
const idx: number[] = []
for (let j = 0; j + 1 < ny; j++) {
for (let i = 0; i + 1 < nx; i++) {
const a = j * nx + i, bb = a + 1, c = a + nx, d = c + 1
if (!(g.present[a] && g.present[bb] && g.present[c] && g.present[d])) continue
// wound so the face normal is +Y (see the note on BOX_FACES)
idx.push(a, c, bb, bb, c, d)
}
}
const indices = new Uint32Array(idx)
data.push({
mode: 'triangles', positions, colors, indices,
normals: computeNormals(positions, indices), lit: true, cull: false,
})
} else {
// Bars start at ZERO. A bar's LENGTH is the value, so a truncated axis is a
// lie rather than a zoom — the one chart where that is unambiguous.
const span = Math.max(Math.abs(vs.lo), Math.abs(vs.hi))
const yk = span > 0 ? 1 / span : 0
const cells: number[] = []
for (let c = 0; c < nx * ny; c++) if (g.present[c]) cells.push(c)
const positions = new Float32Array(cells.length * 24 * 3)
const normals = new Float32Array(cells.length * 24 * 3)
const colors = new Float32Array(cells.length * 24 * 3)
const indices = new Uint32Array(cells.length * 36)
const wx = (nx > 1 ? 2 / (nx - 1) : 1) * 0.36
const wz = (ny > 1 ? 2 / (ny - 1) : 1) * 0.36
cells.forEach((c, bi) => {
const i = c % nx, j = (c / nx) | 0
const v = g.v[c] * yk
const x0 = at(i, nx) - wx, x1 = at(i, nx) + wx
const z0 = at(j, ny) - wz, z1 = at(j, ny) + wz
const y0 = Math.min(0, v), y1 = Math.max(0, v)
const rgb = rampColor(norm01(g.v[c], vs.lo, vs.hi), ramp.rgb)
let vi = bi * 24
let ii = bi * 36
for (const face of BOX_FACES) {
const base = vi
for (const [fx, fy, fz] of face.c) {
const k = vi * 3
positions[k] = fx ? x1 : x0
positions[k + 1] = fy ? y1 : y0
positions[k + 2] = fz ? z1 : z0
normals[k] = face.n[0]; normals[k + 1] = face.n[1]; normals[k + 2] = face.n[2]
colors[k] = rgb[0]; colors[k + 1] = rgb[1]; colors[k + 2] = rgb[2]
vi++
}
indices[ii++] = base; indices[ii++] = base + 1; indices[ii++] = base + 2
indices[ii++] = base; indices[ii++] = base + 2; indices[ii++] = base + 3
}
})
data.push({ mode: 'triangles', positions, colors, normals, indices, lit: true, cull: true })
}
const bounds = boundsOf(data)
return finish(kind, data, [frameMesh(
[Math.min(-1, bounds.min[0]), bounds.min[1], Math.min(-1, bounds.min[2])],
[Math.max(1, bounds.max[0]), bounds.max[1], Math.max(1, bounds.max[2])],
)], {
axes: [
{ title: nameOf(b.x), kind: ax.numeric ? 'value' : 'category', min: ax.min, max: ax.max, labels: ax.labels },
{ title: nameOf(b.y), kind: ay.numeric ? 'value' : 'category', min: ay.min, max: ay.max, labels: ay.labels },
{ title: agg === 'count' ? 'count' : `${agg} of ${nameOf(b.z)}`, kind: 'value', min: vs.lo, max: vs.hi },
],
legend: { title: agg === 'count' ? 'count' : nameOf(b.z), kind: 'ramp', ramp: ramp.hex, min: vs.lo, max: vs.hi },
rows,
// rows that fell off an axis (blank, unparseable, or past the category cap)
dropped: rows - g.used,
})
}
const GLOBE_R = 1
/** Points sit just off the surface. Exactly ON it z-fights: the depth buffer
* cannot separate two surfaces at the same depth and the dots flicker as the
* camera moves, which reads as a rendering fault rather than as data. */
const GLOBE_LIFT = 1.012
function buildGlobe(b: Viz3dBinding, rows: number, col: ColFn, nameOf: NameFn): Scene {
const clat = col(b.lat), clon = col(b.lon)
if (!clat || !clon) return emptyScene('globe', t('a globe needs a latitude and a longitude column'), rows)
const lats = clat.map(num)
const lons = clon.map(num)
const keep: number[] = []
for (let i = 0; i < rows; i++) {
const la = lats[i], lo = lons[i]
// Out-of-range values are REFUSED, not wrapped. A column that is not really
// a latitude (a row number, a temperature) otherwise paints a confident
// band of dots across the equator and nothing says the binding is wrong.
if (la === null || lo === null) continue
if (la < -90 || la > 90 || lo < -180 || lo > 180) continue
keep.push(i)
}
const ramp = rampOf(b)
const cc = col(b.color)
const cNums = cc ? cc.map(num) : null
const colourNumeric = !!cNums && cc!.some((v, i) => v != null && v !== '' && cNums[i] !== null)
&& cc!.every((v, i) => v == null || v === '' || cNums![i] !== null)
const cScale = colourNumeric ? scaler(cNums!) : null
const sc = col(b.size)
const sNums = sc ? sc.map(num) : null
const sScale = sNums ? scaler(sNums) : null
const catAt = new Map<string, number>()
const catLabels: string[] = []
if (cc && !colourNumeric) {
for (const i of keep) {
const s = cc[i] == null ? '' : String(cc[i])
if (s && !catAt.has(s)) { catAt.set(s, catAt.size); catLabels.push(s) }
}
}
const sphere = sphereMesh(GLOBE_R, 48, 24)
const ocean: RGB = [0.13, 0.22, 0.34]
const sphereColors = new Float32Array(sphere.positions.length)
for (let i = 0; i < sphereColors.length; i += 3) {
sphereColors[i] = ocean[0]; sphereColors[i + 1] = ocean[1]; sphereColors[i + 2] = ocean[2]
}
const meshes: Mesh[] = [{
mode: 'triangles',
positions: sphere.positions,
normals: sphere.normals,
colors: sphereColors,
indices: sphere.indices,
lit: true,
cull: true,
}, graticule()]
if (keep.length) {
const positions = new Float32Array(keep.length * 3)
const colors = new Float32Array(keep.length * 3)
const sizes = new Float32Array(keep.length)
keep.forEach((row, k) => {
const p = latLonToXyz(lats[row]!, lons[row]!, GLOBE_R * GLOBE_LIFT)
positions[k * 3] = p[0]; positions[k * 3 + 1] = p[1]; positions[k * 3 + 2] = p[2]
let rgb: RGB
if (cScale) rgb = rampColor(norm01(cNums![row] ?? cScale.lo, cScale.lo, cScale.hi), ramp.rgb)
else if (cc) {
const j = catAt.get(cc[row] == null ? '' : String(cc[row]))
rgb = hexToRgb(j === undefined ? '#F7A600' : CATEGORY_COLORS[j % CATEGORY_COLORS.length])
} else rgb = hexToRgb('#F7A600')
colors[k * 3] = rgb[0]; colors[k * 3 + 1] = rgb[1]; colors[k * 3 + 2] = rgb[2]
const sv = sScale && sNums![row] !== null ? norm01(sNums![row]!, sScale.lo, sScale.hi) : 0.35
sizes[k] = sizeFor(sv)
})
meshes.push({ mode: 'points', positions, colors, sizes, lit: true })
}
const legend: Legend | undefined = cScale
? { title: nameOf(b.color), kind: 'ramp', ramp: ramp.hex, min: cScale.lo, max: cScale.hi }
: catLabels.length
? {
title: nameOf(b.color), kind: 'categories',
items: catLabels.slice(0, 8).map((l, i) => ({ label: l, color: CATEGORY_COLORS[i % CATEGORY_COLORS.length] })),
}
: undefined
return finish('globe', meshes, [], {
axes: [
{ title: nameOf(b.lat), kind: 'value', min: -90, max: 90 },
{ title: nameOf(b.lon), kind: 'value', min: -180, max: 180 },
],
legend,
rows,
dropped: rows - keep.length,
})
}
/** Meridians and parallels every 30°. The graticule is what makes a sphere read
* as a rotating globe rather than as a flat lit disc — a smooth shaded sphere
* has no features, so nothing on screen moves when the camera does. */
function graticule(): Mesh {
const pos: number[] = []
const col: number[] = []
const c: RGB = [0.38, 0.52, 0.62]
const r = GLOBE_R * 1.003
const push = (a: Vec3, b: Vec3) => {
pos.push(a[0], a[1], a[2], b[0], b[1], b[2])
for (let i = 0; i < 2; i++) col.push(c[0], c[1], c[2])
}
for (let lon = -180; lon < 180; lon += 30) {
for (let lat = -90; lat < 90; lat += 10) {
push(latLonToXyz(lat, lon, r), latLonToXyz(lat + 10, lon, r))
}
}
for (const lat of [-60, -30, 0, 30, 60]) {
for (let lon = -180; lon < 180; lon += 10) {
push(latLonToXyz(lat, lon, r), latLonToXyz(lat, lon + 10, r))
}
}
return { mode: 'lines', positions: new Float32Array(pos), colors: new Float32Array(col), lit: false }
}
/**
* A binding that needs no configuration, so the first 3D view takes one click.
* Mirrors chart.ts's defaultBinding in spirit: prefer the view the columns are
* actually shaped for, and return null rather than force one that is wrong.
*/
export function defaultViz3d(sheet: TableSheet): Viz3dBinding | null {
const isNum = (c: Column): boolean => c.type === 'number' || c.type === 'money' || c.type === 'percent'
/**
* A DERIVED COLUMN IS NEVER AN INDEPENDENT AXIS, and the starter workbook is
* the proof of what happens when the default does not know that.
*
* This bound the first three numeric columns in declaration order. On
* `sheet-pipeline` those are Value (money), Probability (percent) and
* Weighted (money) — `closed` is a date and drops out — and `weighted` is
* `formula: 'value * prob'` (starter.ts). So the plot every new user met was
* x = Value, y = Probability, **z = Value × Probability**: a surface, drawn
* as a cloud, in which the third dimension carries no information the first
* two do not already have. It looked like an argument against 3D and it was
* an argument against this function.
*
* A column with a `formula` is a function of columns already on the sheet, so
* using one as an axis plots a variable against itself. Stored columns are
* preferred for x/y/z; a computed one is still allowed to COLOUR or SIZE the
* points, where being derived is informative rather than degenerate, and is
* still used as an axis if there is nothing else — a sheet of three formula
* columns is better plotted than refused.
*/
const stored = sheet.columns.filter((c) => isNum(c) && !c.formula)
const derived = sheet.columns.filter((c) => isNum(c) && !!c.formula)
const numeric = [...stored, ...derived]
const cat = sheet.columns.filter((c) => c.type === 'text' || c.type === 'enum' || c.type === 'date')
const find = (re: RegExp) => numeric.find((c) => re.test(c.name) || re.test(c.id))
// `\b` matters: without it "platform" is a latitude column.
const lat = find(/^lat(itude)?$/i) ?? find(/\blat/i)
const lon = find(/^(lon|lng|long(itude)?)$/i) ?? find(/\b(lon|lng)/i)
if (lat && lon && lat.id !== lon.id) {
return { kind: 'globe', lat: lat.id, lon: lon.id, color: numeric.find((c) => c.id !== lat.id && c.id !== lon.id)?.id }
}
const scatter = (): Viz3dBinding => ({
kind: 'scatter',
x: numeric[0].id, y: numeric[1].id, z: numeric[2].id,
color: numeric[3]?.id ?? cat[0]?.id,
size: numeric[4]?.id,
})
const bars = (): Viz3dBinding =>
({ kind: 'bars', x: cat[0].id, y: cat[1].id, z: numeric[0].id, agg: 'sum' })
// THREE INDEPENDENT AXES, or this is not a scatter worth drawing.
if (stored.length >= 3) return scatter()
// ONLY TWO STORED MEASURES — the starter workbook's exact shape, and the
// reason preferring stored columns is not on its own enough. `sheet-pipeline`
// has Value and Probability and nothing else independent, so a scatter of it
// can only reach three dimensions by taking a derived column, whatever the
// preference says. There is no honest scatter here to pick.
//
// 3D BARS ARE, and they are the better answer twice over: a category x
// category x measure grid is a genuinely three-dimensional reading of a
// pipeline (who is selling how much, where), and it is the thing a
// spreadsheet cannot draw — which is the whole claim this view is here to
// make. A degenerate scatter drawn ahead of a truthful grid was the default
// arguing against its own feature.
if (cat.length >= 2 && numeric.length >= 1) return bars()
// LAST RESORT, and deliberately still allowed: a sheet whose numeric columns
// are all computed, with nothing to group by, is better plotted than refused.
// Preferring stored columns is a preference, never a ban.
if (numeric.length >= 3) return scatter()
return null
}
// --- the 2D fallback --------------------------------------------------------
/** Past this the SVG is slower to lay out than the data is worth, so triangle
* meshes degrade to their VERTICES as dots. A half-resolution mesh would be
* worse: striding triangles punches holes in the surface, and a surface with
* holes reads as missing data. */
const SVG_MAX_TRIS = 9000
const SVG_MAX_POINTS = 4000
const esc = (s: string): string =>
String(s).replace(/[&<>"]/g, (c) => (c === '&' ? '&' : c === '<' ? '<' : c === '>' ? '>' : '"'))
export interface FallbackOpts {
/** reuse a live camera, so dragging the fallback works exactly like dragging GL */
camera?: Orbit
azimuth?: number
elevation?: number
background?: string
ink?: string
}
/** Frame a scene: far enough back that the bounding sphere fits the vertical fov. */
export function frameCamera(scene: Scene, opts: { azimuth?: number; elevation?: number } = {}): Orbit {
const o = new Orbit()
o.target = [...scene.center] as Vec3
o.fovY = Math.PI / 4
o.distance = Math.max(0.6, scene.radius / Math.sin(o.fovY / 2)) * 0.85
o.minDistance = scene.radius * 0.15
o.maxDistance = scene.radius * 40
o.azimuth = opts.azimuth ?? 0.72
o.elevation = opts.elevation ?? 0.46
o.near = Math.max(0.01, scene.radius / 200)
o.far = scene.radius * 80
return o
}
/**
* The same scene, the same camera and the same lighting, projected into SVG.
*
* PAINTER'S ALGORITHM: every primitive is emitted in one list sorted far-to-near
* by centroid depth. That is exact for convex closed geometry (the globe, a
* bar) and correct in practice for a heightfield; it is WRONG for two triangles
* that interpenetrate, which the depth buffer would resolve per-pixel. Accepted,
* because the alternative on this path is a software rasteriser.
*
* Returns a STRING so it is testable in node — the whole reason the fallback is
* checkable at all.
*/
export function fallbackSvg(scene: Scene, w = 640, h = 420, opts: FallbackOpts = {}): string {
const bg = opts.background ?? '#0E1420'
const ink = opts.ink ?? '#C7D0DE'
const head = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="100%" height="100%" ` +
`role="img" aria-label="${esc(scene.empty ?? t(VIZ_TITLE[scene.kind]))}" style="display:block">` +
`<rect width="${w}" height="${h}" fill="${esc(bg)}"/>`
const tail = '</svg>'
if (scene.empty || !scene.meshes.length) {
// NOT a blank box: the sentence is the point. A reader on a machine without
// WebGL2 must learn that the view exists and why it is not showing data.
return head +
`<text x="${w / 2}" y="${h / 2}" fill="${esc(ink)}" font-family="system-ui,sans-serif" ` +
`font-size="14" text-anchor="middle" opacity="0.85">${esc(scene.empty ?? t('nothing to draw'))}</text>` +
tail
}
const cam = opts.camera ?? frameCamera(scene, opts)
const vp = cam.matrix(w / Math.max(1, h))
let tris = 0
for (const m of scene.meshes) {
if (m.mode === 'triangles') tris += (m.indices ? m.indices.length : m.positions.length / 3) / 3
}
const dots = tris > SVG_MAX_TRIS
const prims: Array<{ z: number; s: string }> = []
const px = (i: number, p: Float32Array) => project(vp, [p[i], p[i + 1], p[i + 2]], w, h)
const hex = (r: number, g: number, b: number, k: number): string =>
rgbToHex([r * k, g * k, b * k])
for (const m of scene.meshes) {
const p = m.positions
const c = m.colors
if (m.mode === 'triangles' && !dots) {
const idx = m.indices ?? new Uint32Array(Array.from({ length: p.length / 3 }, (_, i) => i))
for (let t = 0; t + 2 < idx.length; t += 3) {
const a = idx[t] * 3, b = idx[t + 1] * 3, d = idx[t + 2] * 3
const pa = px(a, p), pb = px(b, p), pd = px(d, p)
if (!(Number.isFinite(pa.x) && Number.isFinite(pb.x) && Number.isFinite(pd.x))) continue
if (pa.z > 1 || pb.z > 1 || pd.z > 1) continue // behind the eye, or past the far plane
if (m.cull) {
// screen-space signed area; y is flipped, so a front face is negative
const area = (pb.x - pa.x) * (pd.y - pa.y) - (pd.x - pa.x) * (pb.y - pa.y)
if (area > 0) continue
}
// FACE normal, not the interpolated vertex normals: SVG cannot shade a
// gradient across a polygon, so flat-per-triangle is the honest choice
// and a fine enough mesh looks smooth anyway.
const nx0 = p[b] - p[a], ny0 = p[b + 1] - p[a + 1], nz0 = p[b + 2] - p[a + 2]
const nx1 = p[d] - p[a], ny1 = p[d + 1] - p[a + 1], nz1 = p[d + 2] - p[a + 2]
let n: Vec3 = vnorm([
ny0 * nz1 - nz0 * ny1,
nz0 * nx1 - nx0 * nz1,
nx0 * ny1 - ny0 * nx1,
])
// A back-facing normal on an OPEN surface is the underside; light it as
// if it faced us rather than painting it black.
if (!m.cull && m.normals) {
const dotv = n[0] * m.normals[a] + n[1] * m.normals[a + 1] + n[2] * m.normals[a + 2]
if (dotv < 0) n = [-n[0], -n[1], -n[2]]
}
const k = m.lit ? shade(n) : 1
const fill = hex((c[a] + c[b] + c[d]) / 3, (c[a + 1] + c[b + 1] + c[d + 1]) / 3, (c[a + 2] + c[b + 2] + c[d + 2]) / 3, k)
prims.push({
z: (pa.z + pb.z + pd.z) / 3,
s: `<polygon points="${pa.x.toFixed(1)},${pa.y.toFixed(1)} ${pb.x.toFixed(1)},${pb.y.toFixed(1)} ${pd.x.toFixed(1)},${pd.y.toFixed(1)}" fill="${fill}"/>`,
})
}
continue
}
if (m.mode === 'lines') {
for (let i = 0; i + 5 < p.length; i += 6) {
const pa = px(i, p), pb = px(i + 3, p)
if (!Number.isFinite(pa.x) || !Number.isFinite(pb.x) || pa.z > 1 || pb.z > 1) continue
prims.push({
z: (pa.z + pb.z) / 2,
s: `<line x1="${pa.x.toFixed(1)}" y1="${pa.y.toFixed(1)}" x2="${pb.x.toFixed(1)}" y2="${pb.y.toFixed(1)}" stroke="${hex(c[i], c[i + 1], c[i + 2], 1)}" stroke-width="1" opacity="0.75"/>`,
})
}
continue
}
// points, and triangle meshes degraded to their vertices
const count = p.length / 3
const stride = Math.max(1, Math.ceil(count / SVG_MAX_POINTS))
// world radius → pixels, the same formula the point shader uses
const scale = ((0.5 * h) / Math.tan(cam.fovY / 2)) * (scene.radius * 0.022)
// A sprite always faces the camera, so its CENTRE normal is +Z in view
// space; SVG cannot vary shading across a circle, so one value per point is
// all there is. Hoisted: eye() and view() allocate, and this is per-mesh.
const k = m.lit ? shadeWith([0, 0, 1], dirToView(cam.view(), LIGHT)) : 1
const eye = cam.eye()
for (let v = 0; v < count; v += stride) {
const i = v * 3
const q = px(i, p)
if (!Number.isFinite(q.x) || q.z > 1) continue
const dist = Math.max(1e-3, Math.hypot(p[i] - eye[0], p[i + 1] - eye[1], p[i + 2] - eye[2]))
const rad = clamp(((m.sizes ? m.sizes[v] : 0.5) * scale) / dist, 0.7, 30)
prims.push({
z: q.z,
s: `<circle cx="${q.x.toFixed(1)}" cy="${q.y.toFixed(1)}" r="${rad.toFixed(2)}" fill="${hex(c[i], c[i + 1], c[i + 2], k)}"/>`,
})
}
}
// far first. `project` returns NDC depth, where +1 is the far plane.
prims.sort((a, b) => b.z - a.z)
return head + prims.map((x) => x.s).join('') + overlaySvg(scene, w, h, ink) + tail
}
/** Axis titles, the colour legend and the dropped-row count. Chrome, but the
* dropped count is not optional: it is the only place the fallback can say
* that some rows are not in the picture. */
function overlaySvg(scene: Scene, w: number, h: number, ink: string): string {
const font = 'font-family="system-ui,-apple-system,sans-serif"'
let out = ''
const titles = scene.axes.map((a) => a.title).filter(Boolean).join(' · ')
if (titles) {
out += `<text x="12" y="${h - 12}" fill="${esc(ink)}" ${font} font-size="11" opacity="0.75">${esc(titles)}</text>`
}
if (scene.dropped > 0) {
out += `<text x="${w - 12}" y="${h - 12}" fill="${esc(ink)}" ${font} font-size="11" ` +
`text-anchor="end" opacity="0.6">${scene.dropped} of ${scene.rows} rows had no value</text>`
}
const lg = scene.legend
if (lg && lg.kind === 'ramp' && lg.ramp?.length) {
const id = 'v3lg'
const stops = lg.ramp.map((c, i) =>
`<stop offset="${((i / (lg.ramp!.length - 1)) * 100).toFixed(0)}%" stop-color="${esc(c)}"/>`).join('')
out += `<defs><linearGradient id="${id}" x1="0" y1="1" x2="0" y2="0">${stops}</linearGradient></defs>` +
`<rect x="${w - 26}" y="24" width="10" height="96" fill="url(#${id})" rx="2"/>` +
`<text x="${w - 32}" y="30" fill="${esc(ink)}" ${font} font-size="10" text-anchor="end" opacity="0.8">${esc(fmtNum(lg.max ?? 0))}</text>` +
`<text x="${w - 32}" y="122" fill="${esc(ink)}" ${font} font-size="10" text-anchor="end" opacity="0.8">${esc(fmtNum(lg.min ?? 0))}</text>` +
(lg.title ? `<text x="12" y="20" fill="${esc(ink)}" ${font} font-size="11" opacity="0.8">${esc(lg.title)}</text>` : '')
} else if (lg && lg.items?.length) {
lg.items.slice(0, 6).forEach((it, i) => {
const y = 24 + i * 16
out += `<rect x="${w - 26}" y="${y}" width="10" height="10" fill="${esc(it.color)}" rx="2"/>` +
`<text x="${w - 32}" y="${y + 9}" fill="${esc(ink)}" ${font} font-size="10" text-anchor="end" opacity="0.8">${esc(it.label)}</text>`
})
}
return out
}
// --- GL (browser only) ------------------------------------------------------
// GLSL ES 3.00. `#version` MUST be the very first characters of the source, so
// these template literals open on it with no leading newline.
const MESH_VS = `#version 300 es
precision highp float;
in vec3 a_pos;
in vec3 a_normal;
in vec3 a_color;
uniform mat4 u_vp;
uniform vec3 u_light;
uniform float u_ambient;
uniform float u_lit;
out vec3 v_color;
void main() {
// transliterated from shade() — the two must not disagree
float d = max(0.0, dot(a_normal, u_light));
float sky = 0.55 + 0.45 * a_normal.y;
float s = min(1.0, u_ambient * sky + (1.0 - u_ambient) * d);
v_color = mix(a_color, a_color * s, u_lit);
gl_Position = u_vp * vec4(a_pos, 1.0);
}`
const MESH_FS = `#version 300 es
precision highp float;
in vec3 v_color;
out vec4 fragColor;
void main() { fragColor = vec4(v_color, 1.0); }`
// One vertex per row. A real sphere per point would be ~80 vertices each, so a
// 100k-row scatter is 8M vertices instead of 100k — the impostor is what makes
// the scatter the size of its data rather than eighty times it.
const POINT_VS = `#version 300 es
precision highp float;
in vec3 a_pos;
in vec3 a_color;
in float a_size;
uniform mat4 u_vp;
uniform float u_pscale;
out vec3 v_color;
void main() {
v_color = a_color;
gl_Position = u_vp * vec4(a_pos, 1.0);
// gl_Position.w is the view-space distance for a perspective matrix, so this
// is the true projected diameter of a sphere of world radius a_size. Clamped
// because drivers cap gl_PointSize and SILENTLY DROP points that exceed it.
gl_PointSize = clamp(a_size * u_pscale / max(0.0001, gl_Position.w), 1.5, 96.0);
}`
const POINT_FS = `#version 300 es
precision highp float;
in vec3 v_color;
uniform vec3 u_lightv;
uniform float u_ambient;
out vec4 fragColor;
void main() {
vec2 pc = gl_PointCoord * 2.0 - 1.0;
float r2 = dot(pc, pc);
// A hard cut, not a blended edge: blending would need the points sorted
// back-to-front every frame and would still be wrong where they overlap.
if (r2 > 1.0) discard;
// gl_PointCoord counts DOWN, so y is negated to make +Y up.
vec3 n = vec3(pc.x, -pc.y, sqrt(max(0.0, 1.0 - r2)));
float d = max(0.0, dot(n, u_lightv));
float sky = 0.55 + 0.45 * n.y;
float s = min(1.0, u_ambient * sky + (1.0 - u_ambient) * d);
fragColor = vec4(v_color * s, 1.0);
}`
export interface Viz3dOpts {
background?: string
/** spin gently. Off by default: a dashboard of auto-rotating tiles is a
* laptop fan, and motion the reader did not ask for. */
autoRotate?: boolean
azimuth?: number
elevation?: number
/** point radius as a fraction of the scene radius */
pointScale?: number
/** label colour for the overlay — same default as the fallback's, so the two
* renderers cannot drift apart on the one thing they now both draw. */
ink?: string
}
/**
* Pointer control shared by BOTH paths, so the fallback drags exactly like GL
* does. One pointer rotates (shift or the right button pans); two pinch and
* pan, because `touch-action: none` is required for the first and disables the
* browser's own pinch along with it.
*/
function orbitControls(el: HTMLElement, orb: Orbit, changed: () => void): () => void {
const pts = new Map<number, { x: number; y: number }>()
let spread = 0
const centreOf = (): { x: number; y: number; d: number } => {
const l = [...pts.values()]
const x = l.reduce((a, p) => a + p.x, 0) / l.length
const y = l.reduce((a, p) => a + p.y, 0) / l.length
const d = l.length > 1 ? Math.hypot(l[0].x - l[1].x, l[0].y - l[1].y) : 0
return { x, y, d }
}
const down = (e: PointerEvent) => {
pts.set(e.pointerId, { x: e.clientX, y: e.clientY })
spread = centreOf().d
el.setPointerCapture?.(e.pointerId)
}
const move = (e: PointerEvent) => {
const was = pts.get(e.pointerId)
if (!was) return
const dx = e.clientX - was.x
const dy = e.clientY - was.y
pts.set(e.pointerId, { x: e.clientX, y: e.clientY })
if (pts.size >= 2) {
const now = centreOf()
if (spread > 0 && now.d > 0) orb.zoom(spread / now.d)
spread = now.d
orb.pan(dx / 2, dy / 2)
} else if (e.shiftKey || e.buttons === 2 || e.buttons === 4) {
orb.pan(dx, dy)
} else {
orb.rotate(dx, dy)
}
changed()
}
const up = (e: PointerEvent) => {
pts.delete(e.pointerId)
spread = pts.size > 1 ? centreOf().d : 0
el.releasePointerCapture?.(e.pointerId)
}
// preventDefault so the page behind a tile does not scroll away under the
// gesture. A 3D view that does not zoom on the wheel is the bigger surprise.
const wheel = (e: WheelEvent) => {
e.preventDefault()
orb.zoom(Math.exp(clamp(e.deltaY, -120, 120) * 0.0016))
changed()
}
const menu = (e: Event) => e.preventDefault()
el.addEventListener('pointerdown', down)
el.addEventListener('pointermove', move)
el.addEventListener('pointerup', up)
el.addEventListener('pointercancel', up)
el.addEventListener('wheel', wheel, { passive: false })
el.addEventListener('contextmenu', menu)
return () => {
el.removeEventListener('pointerdown', down)
el.removeEventListener('pointermove', move)
el.removeEventListener('pointerup', up)
el.removeEventListener('pointercancel', up)
el.removeEventListener('wheel', wheel)
el.removeEventListener('contextmenu', menu)
}
}
function mountFallback(host: HTMLElement, scene: Scene, opts: Viz3dOpts): () => void {
const box = document.createElement('div')
box.className = 'dash-viz3d dash-viz3d-2d'
box.style.cssText = 'width:100%;height:100%;touch-action:none;user-select:none'
host.appendChild(box)
const cam = frameCamera(scene, opts)
let raf = 0
const paint = () => {
raf = 0
cam.height = box.clientHeight || 420
box.innerHTML = fallbackSvg(scene, box.clientWidth || 640, box.clientHeight || 420, {
camera: cam, background: opts.background,
})
}
const schedule = () => {
if (!raf) raf = requestAnimationFrame(paint)
}
paint()
const detach = scene.empty ? () => {} : orbitControls(box, cam, schedule)
const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null
ro?.observe(box)
return () => {
if (raf) cancelAnimationFrame(raf)
detach()
ro?.disconnect()
box.remove()
}
}
/**
* Mount a scene into a host element. Returns a teardown.
*
* THE LOOP IDLES. A frame is scheduled only when something changed — a drag, a
* wheel, a resize, a context restore — and `draw` clears the flag rather than
* re-arming it. A permanent requestAnimationFrame loop is the default shape of
* every 3D example on the web and it is wrong here: a dashboard holds several
* tiles, none of them are moving, and between them they would keep the GPU and
* the compositor awake for as long as the file is open. `autoRotate` is the one
* case that re-arms, and it is opt-in.
*/
export function mountViz3d(host: HTMLElement, scene: Scene, opts: Viz3dOpts = {}): () => void {
host.textContent = ''
if (scene.empty || !supportsWebGL2()) return mountFallback(host, scene, opts)
// A POSITIONED WRAPPER, because the labels go OVER the canvas.
//
// `overlaySvg` — axis titles, the colour legend and the dropped-row count —
// had exactly one call site, inside `fallbackSvg`. So the machine that CANNOT
// do WebGL2 got the labelled, honest picture and every ordinary browser got a
// bare canvas: measured in the built shell, one <canvas>, zero text nodes,
// zero overlay elements. `Scene.axes` and `Scene.legend` were computed on
// every build and thrown away.
//
// The dropped-row count is the half that is not cosmetic, and this file
// already says so: nulls are dropped rather than zeroed (correctly — a
// missing value coerced to 0 is a crater, and craters look like findings),
// and `overlaySvg`'s own comment calls the count "not optional: it is the
// only place the fallback can say that some rows are not in the picture".
// It was the only place FULL STOP, and the primary renderer said nothing.
//
// Deliberately a sibling layer rather than anything inside the GL path:
// the same string the fallback builds, positioned over the canvas,
// `pointer-events:none` so the orbit drag still lands on the canvas beneath.
const wrap = document.createElement('div')
wrap.className = 'dash-viz3d dash-viz3d-gl'
wrap.style.cssText = 'position:relative;width:100%;height:100%'
host.appendChild(wrap)
const canvas = document.createElement('canvas')
// `touch-action:none` so a one-finger drag orbits instead of scrolling the
// page; `user-select:none` because an orbit drag that runs off the canvas
// otherwise selects the surrounding page text and leaves it highlighted.
canvas.style.cssText = 'display:block;width:100%;height:100%;touch-action:none;user-select:none'
wrap.appendChild(canvas)
const view = new GLView(canvas)
// supportsWebGL2() can be TRUE while this particular context fails: browsers
// cap live contexts at about 16, and a dashboard that swaps tiles reaches it.
// Falling back to the SVG is much better than a blank canvas.
if (!view.ok) {
view.dispose()
wrap.remove()
return mountFallback(host, scene, opts)
}
const meshProg = view.compile(MESH_VS, MESH_FS)
const pointProg = view.compile(POINT_VS, POINT_FS)
const bufs = scene.meshes.map((m) => ({
m,
pos: view.buffer(m.positions),
col: view.buffer(m.colors),
nrm: m.normals ? view.buffer(m.normals) : null,
siz: m.sizes ? view.buffer(m.sizes) : null,
idx: m.indices ? view.buffer(m.indices, { index: true }) : null,
}))
const labels = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
labels.setAttribute('aria-hidden', 'true')
labels.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none'
wrap.appendChild(labels)
// Only when the BOX changes. The overlay is a function of the scene and the
// size, never of the camera, so redrawing it per orbit frame would rebuild
// this markup on every mouse move for no change at all.
let lw = -1, lh = -1
const drawLabels = (w: number, h: number) => {
if (w === lw && h === lh) return
lw = w; lh = h
labels.setAttribute('viewBox', `0 0 ${w} ${h}`)
labels.innerHTML = overlaySvg(scene, w, h, opts.ink ?? '#C7D0DE')
}
const cam = frameCamera(scene, opts)
const bg = hexToRgb(opts.background ?? '#0E1420')
const pointRadius = scene.radius * (opts.pointScale ?? 0.022)
let raf = 0
const draw = () => {
raf = 0
view.resize()
cam.height = canvas.clientHeight || 420
const vp = cam.matrix(view.aspect)
const lightView = dirToView(cam.view(), LIGHT)
const pscale = (2 * pointRadius * canvas.height * 0.5) / Math.tan(cam.fovY / 2)
view.clear(bg[0], bg[1], bg[2], 1)
for (const b of bufs) {
if (b.m.mode === 'points') {
view.draw({
program: pointProg,
attribs: {
a_pos: { buffer: b.pos, size: 3 },
a_color: { buffer: b.col, size: 3 },
...(b.siz ? { a_size: { buffer: b.siz, size: 1 } } : {}),
},
uniforms: { u_vp: vp, u_pscale: pscale, u_lightv: lightView, u_ambient: AMBIENT },
count: b.m.positions.length / 3,
mode: 'points',
})
continue
}
view.draw({
program: meshProg,
attribs: {
a_pos: { buffer: b.pos, size: 3 },
a_color: { buffer: b.col, size: 3 },
...(b.nrm ? { a_normal: { buffer: b.nrm, size: 3 } } : {}),
},
uniforms: { u_vp: vp, u_light: LIGHT, u_ambient: AMBIENT, u_lit: b.m.lit ? 1 : 0 },
count: b.idx ? b.m.indices!.length : b.m.positions.length / 3,
mode: b.m.mode,
...(b.idx ? { index: b.idx } : {}),
})
}
drawLabels(canvas.clientWidth || 640, canvas.clientHeight || 420)
if (opts.autoRotate) { cam.rotate(-0.4, 0); schedule() }
}
const schedule = () => {
if (!raf) raf = requestAnimationFrame(draw)
}
view.onRestore = schedule
view.onLost = () => { if (raf) { cancelAnimationFrame(raf); raf = 0 } }
const detach = orbitControls(canvas, cam, schedule)
const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null
ro?.observe(canvas)
schedule()
return () => {
if (raf) cancelAnimationFrame(raf)
detach()
ro?.disconnect()
view.dispose()
wrap.remove()
}
}
export const _internals = {
categorise, aggregateGrid, scaler, norm01, sizeFor, sphereMesh, frameMesh, boundsOf,
num, fmtNum, SIZE_MIN, SIZE_MAX, AXIS_MAX_SURFACE, AXIS_MAX_BARS, DEFAULT_BINS,
SVG_MAX_TRIS, SVG_MAX_POINTS, BOX_FACES, esc,
}