@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/threesurfaces/ComplexSurface.js

@@ -0,0 +1,156 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { ColorRamp } from "./ColorRamp.js";
+import { short } from "./GridSurfaceBase.js";
+import { SurfaceBase } from "./SurfaceBase.js";
+import { SurfaceField } from "./SurfaceField.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { SurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { quantile } from "d3";
+// src/charts/threesurfaces/ComplexSurface.ts
+var ComplexFunction = /* @__PURE__ */ function(ComplexFunction) {
+	ComplexFunction["PoleZero"] = "pole-zero";
+	ComplexFunction["Square"] = "z-squared";
+	ComplexFunction["Cubic"] = "z-cubed-minus-one";
+	ComplexFunction["Mobius"] = "mobius-map";
+	ComplexFunction["Sine"] = "sine";
+	ComplexFunction["Exponential"] = "exponential";
+	ComplexFunction["Logarithm"] = "logarithm";
+	ComplexFunction["Tangent"] = "tangent";
+	return ComplexFunction;
+}({});
+var ComplexHeight = /* @__PURE__ */ function(ComplexHeight) {
+	ComplexHeight["LogModulus"] = "log-modulus";
+	ComplexHeight["Modulus"] = "modulus";
+	ComplexHeight["Real"] = "real-part";
+	ComplexHeight["Imaginary"] = "imaginary-part";
+	return ComplexHeight;
+}({});
+var mul = ([a, b], [c, d]) => [a * c - b * d, a * d + b * c];
+var div = ([a, b], [c, d]) => {
+	const m = c * c + d * d || 1e-12;
+	return [(a * c + b * d) / m, (b * c - a * d) / m];
+};
+var sub = ([a, b], [c, d]) => [a - c, b - d];
+var add = ([a, b], [c, d]) => [a + c, b + d];
+var sine = ([a, b]) => [Math.sin(a) * Math.cosh(b), Math.cos(a) * Math.sinh(b)];
+var cosine = ([a, b]) => [Math.cos(a) * Math.cosh(b), -Math.sin(a) * Math.sinh(b)];
+var FUNCTIONS = {
+	["z-squared"]: (z) => mul(z, z),
+	["z-cubed-minus-one"]: (z) => sub(mul(z, mul(z, z)), [1, 0]),
+	["mobius-map"]: (z) => div(sub(mul(z, z), [1, 0]), add(mul(z, z), [1, 0])),
+	["sine"]: sine,
+	["exponential"]: ([a, b]) => [Math.exp(a) * Math.cos(b), Math.exp(a) * Math.sin(b)],
+	["logarithm"]: ([a, b]) => [Math.log(Math.hypot(a, b) || 1e-12), Math.atan2(b, a)],
+	["tangent"]: (z) => div(sine(z), cosine(z))
+};
+/** Zeros and poles drawn from the sample points, placed inside the unit disc's neighbourhood. */
+var poleZeroSample = (seed) => SampleData.points(seed, 5, 1).map((row, k) => {
+	const angle = k / 5 * Math.PI * 2 + (row.x - 20) / 40;
+	return {
+		re: +(Math.cos(angle) * 1.15).toFixed(3),
+		im: +(Math.sin(angle) * 1.15).toFixed(3),
+		kind: k % 2 ? "pole" : "zero"
+	};
+});
+/** Height for size, colour for phase: for seeing zeros, poles and branch cuts of a complex function, or a filter's pole-zero map. */
+var ComplexSurface = class extends SurfaceBase {
+	static meta = {
+		id: "complex-surface",
+		name: "Complex surface",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Three,
+		shape: DataShape.Function,
+		description: "Raises a complex function over the z plane by modulus or component, with colour showing its phase and poles saturating at the ceiling.",
+		tags: [
+			"complex",
+			"analytic landscape",
+			"domain colouring",
+			"pole zero",
+			"modulus"
+		],
+		sample: poleZeroSample,
+		variants: {
+			fn: Object.values(ComplexFunction),
+			plotted: Object.values(ComplexHeight),
+			phaseLines: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			fn: "pole-zero",
+			plotted: "log-modulus",
+			phaseLines: true,
+			domain: 2,
+			azimuth: 22,
+			elevation: 30,
+			re: "re",
+			im: "im",
+			kind: "kind",
+			xLabel: "Re z",
+			yLabel: "Im z"
+		};
+	}
+	evaluator() {
+		const { fn, data, re, im, kind } = this.options;
+		if (fn !== "pole-zero") return FUNCTIONS[fn];
+		const rows = Array.isArray(data) ? data : [];
+		const roots = (name) => rows.filter((row) => String(row[kind]) === name).map((row) => [+(row[re] ?? NaN), +(row[im] ?? NaN)]).filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b));
+		const zeros = roots("zero"), poles = roots("pole");
+		return (z) => {
+			const top = zeros.reduce((product, root) => mul(product, sub(z, root)), [1, 0]);
+			return poles.reduce((value, root) => div(value, sub(z, root)), top);
+		};
+	}
+	build(ctx) {
+		const { plotted, phaseLines, domain } = this.options;
+		const f = this.evaluator();
+		const reach = domain, n = 96, axis = Array.from({ length: n }, (_, k) => -reach + 2 * reach * k / 95);
+		const values = axis.map((y) => axis.map((x) => f([x, y])));
+		const raw = (value) => {
+			const size = Math.hypot(...value);
+			if (plotted === "log-modulus") return Math.log(size + .001);
+			if (plotted === "modulus") return size;
+			return plotted === "real-part" ? value[0] : value[1];
+		};
+		const grid = SurfaceField.compute(axis, axis, () => 0);
+		const unclipped = grid.map((_, i, j) => raw(values[j][i]));
+		const sorted = Float64Array.from(unclipped.z.filter((value) => !Number.isNaN(value))).sort();
+		const top = quantile(sorted, .97) ?? 1, bottom = quantile(sorted, plotted === "log-modulus" || plotted === "modulus" ? 0 : .03) ?? 0;
+		const middle = (top + bottom) / 2, half = (top - bottom) / 2 || 1, knee = .8;
+		const saturate = (z) => {
+			const t = (z - middle) / half, size = Math.abs(t);
+			return size <= knee ? z : middle + Math.sign(t) * half * (knee + .19999999999999996 * Math.tanh((size - knee) / .19999999999999996));
+		};
+		const field = unclipped.map(saturate);
+		const space = new SurfaceSpace(field);
+		const phase = new ColorRamp(ctx.palette.diverging, -1, 1);
+		const tone = (i, j) => {
+			const [a, b] = values[j][i];
+			return phase.at(a / (Math.hypot(a, b) || 1));
+		};
+		const ticks = this.ticks([-reach, reach], (v) => v / reach);
+		this.box(ctx, {
+			x: ticks,
+			y: this.ticks([-reach, reach], (v) => -v / reach),
+			z: this.ticks(field.zDomain, space.level, 3).filter(([at]) => at >= space.level(middle - half * knee) && at <= space.level(middle + half * knee))
+		});
+		const lift = this.rise(ctx);
+		this.solid(ctx, SurfaceGeometry.grid(n, n, (i, j) => space.at(i, j), tone), lift, (k) => {
+			const i = k % n, j = Math.floor(k / n), [a, b] = values[j][i];
+			return {
+				title: `z = ${short(axis[i])} ${axis[j] < 0 ? "−" : "+"} ${short(Math.abs(axis[j]))}i`,
+				rows: [["|f|", short(Math.hypot(a, b))], ["arg f", short(Math.atan2(b, a))]]
+			};
+		});
+		if (phaseLines) {
+			const angle = grid.map((_, i, j) => Math.cos(2 * Math.atan2(values[j][i][1], values[j][i][0])));
+			const batch = new TubeBatch(.0045);
+			for (const { paths } of angle.lines([-.5, .5])) for (const path of paths) batch.add(path.map(([i, j]) => space.at(i, j, .004)));
+			this.tubes(batch, lift, ctx.theme.ink, .5);
+		}
+	}
+};
+export { ComplexFunction, ComplexHeight, ComplexSurface };

package/dist/charts/threesurfaces/ContourSurface.js

@@ -0,0 +1,149 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GridSurfaceBase, short } from "./GridSurfaceBase.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { CEIL, FLOOR, SurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { quantile } from "d3";
+import { ExtrudeGeometry, Path, Shape } from "three";
+// src/charts/threesurfaces/ContourSurface.ts
+var LEVEL_GAP = .17;
+var ContourMode = /* @__PURE__ */ function(ContourMode) {
+	ContourMode["Draped"] = "draped";
+	ContourMode["Terraced"] = "terraced";
+	ContourMode["Floating"] = "floating";
+	ContourMode["Flat"] = "floor-map";
+	return ContourMode;
+}({});
+var ContourLevels = /* @__PURE__ */ function(ContourLevels) {
+	ContourLevels["Equal"] = "equal-interval";
+	ContourLevels["Quantile"] = "quantile";
+	return ContourLevels;
+}({});
+/** Iso-levels in space: for reading exact heights off a surface, from draped lines to a laser-cut stack of terraces. */
+var ContourSurface = class extends GridSurfaceBase {
+	static meta = {
+		id: "contour-surface",
+		name: "Contour surface",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Grid,
+		description: "Cuts a height field at iso-levels and shows them draped on the surface, as stacked terraces, floating plates or a floor map.",
+		tags: [
+			"contour",
+			"iso-lines",
+			"topographic",
+			"terraced"
+		],
+		sample: (seed) => SampleData.surface(seed, 56),
+		variants: {
+			mode: [
+				"terraced",
+				"draped",
+				"floating",
+				"floor-map"
+			],
+			levels: [
+				9,
+				6,
+				14
+			],
+			method: ["equal-interval", "quantile"],
+			filled: [true, false]
+		},
+		valid: ({ mode, filled }) => filled === true || mode !== "terraced"
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			mode: "terraced",
+			levels: 9,
+			method: "equal-interval",
+			filled: true
+		};
+	}
+	cuts(space) {
+		const { levels, method } = this.options;
+		const { field } = space;
+		if (method === "equal-interval") return this.thresholds(field, levels);
+		const sorted = Float64Array.from(field.z.filter((value) => !Number.isNaN(value))).sort();
+		return [...new Set(Array.from({ length: levels }, (_, k) => quantile(sorted, (k + 1) / (levels + 1)) ?? 0))];
+	}
+	/** Extruded plate per band, in world space. `Shape` lies in xy, so depth rotates up into y. */
+	plates(space, value, bottom, top, color) {
+		const ring = (points) => points.map(([i, j]) => {
+			const [x, z] = space.ground(i, j);
+			return [x, -z];
+		});
+		return space.field.bands([value]).flatMap(({ polygons }) => polygons.map(([outer, ...holes]) => {
+			const shape = new Shape();
+			ring(outer).forEach(([x, y], k) => k ? shape.lineTo(x, y) : shape.moveTo(x, y));
+			shape.holes = holes.map((hole) => {
+				const path = new Path();
+				ring(hole).forEach(([x, y], k) => k ? path.lineTo(x, y) : path.moveTo(x, y));
+				return path;
+			});
+			const plate = new ExtrudeGeometry(shape, {
+				depth: Math.max(.004, top - bottom),
+				bevelEnabled: false,
+				curveSegments: 1
+			});
+			plate.rotateX(-Math.PI / 2);
+			plate.translate(0, bottom, 0);
+			return SurfaceGeometry.tinted(plate, color);
+		}));
+	}
+	build(ctx) {
+		const { mode, filled } = this.options;
+		const field = this.field(72);
+		const space = new SurfaceSpace(field);
+		const paint = this.painter(ctx, field.zDomain);
+		const cuts = this.cuts(space);
+		this.box(ctx, this.axes(space));
+		const lift = this.rise(ctx);
+		if (!field.hasData) return;
+		const place = (value, path) => path.map(([i, j]) => {
+			if (mode === "draped") return space.at(i, j, .005);
+			const [x, z] = space.ground(i, j);
+			return [
+				x,
+				mode === "floor-map" ? FLOOR + .008 : space.level(value),
+				z
+			];
+		});
+		if (filled) {
+			if (mode === "draped") this.solid(ctx, SurfaceGeometry.grid(field.nx, field.ny, (i, j) => space.at(i, j), (i, j) => paint(field.at(i, j))), lift, this.gridTip(space));
+			else {
+				const stops = [field.zMin - 1, ...cuts];
+				const span = (CEIL - FLOOR) / (cuts.length + 1);
+				const plates = stops.flatMap((value, k) => {
+					const shade = paint(k ? value : field.zMin);
+					if (mode === "terraced") return this.plates(space, value, k ? space.level(cuts[k - 1]) : FLOOR, space.level(stops[k + 1] ?? field.zMax), shade);
+					if (mode === "floating") return this.plates(space, value, (k ? space.level(value) : FLOOR) - span * .14, k ? space.level(value) : FLOOR, shade);
+					return this.plates(space, value, FLOOR + k * .0035, FLOOR + (k + 1) * .0035, shade);
+				});
+				this.solid(ctx, SurfaceGeometry.merge(plates), lift, void 0);
+			}
+		}
+		const rings = new TubeBatch(filled ? .0035 : .0075);
+		if (!filled || mode === "draped") for (const { value, paths } of field.lines(cuts)) {
+			const color = paint(value);
+			for (const path of paths) rings.add(place(value, path), color);
+		}
+		if (mode === "draped" && filled) this.tubes(rings, lift, ctx.theme.ink, .55);
+		else this.tubes(rings, lift);
+		if (mode === "draped") return;
+		let last = -Infinity;
+		for (const value of cuts) {
+			const at = space.level(value);
+			if (at - last < LEVEL_GAP) continue;
+			last = at;
+			ctx.label(short(value), [
+				1.08,
+				at,
+				-1.02
+			], "muted", 9).center.x = 0;
+		}
+	}
+};
+export { ContourLevels, ContourMode, ContourSurface };

package/dist/charts/threesurfaces/DensitySurface.js

@@ -0,0 +1,162 @@
+import { ChartFamily, DataShape, Dimension, ScaleKind } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { short } from "./GridSurfaceBase.js";
+import { SurfaceBase } from "./SurfaceBase.js";
+import { SurfaceField } from "./SurfaceField.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { CEIL, FLOOR, SurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { deviation, group } from "d3";
+// src/charts/threesurfaces/DensitySurface.ts
+var SurfaceDensityKernel = /* @__PURE__ */ function(SurfaceDensityKernel) {
+	SurfaceDensityKernel["Gaussian"] = "gaussian";
+	SurfaceDensityKernel["Epanechnikov"] = "epanechnikov";
+	SurfaceDensityKernel["Triangular"] = "triangular";
+	return SurfaceDensityKernel;
+}({});
+var SurfaceDensityMark = /* @__PURE__ */ function(SurfaceDensityMark) {
+	SurfaceDensityMark["Surface"] = "surface";
+	SurfaceDensityMark["Rings"] = "rings";
+	SurfaceDensityMark["Rows"] = "rows";
+	return SurfaceDensityMark;
+}({});
+var KERNELS = {
+	["gaussian"]: (d2) => Math.exp(-d2 / 2) / (2 * Math.PI),
+	["epanechnikov"]: (d2) => d2 < 5 ? (1 - d2 / 5) * 2 / (Math.PI * 5) : 0,
+	["triangular"]: (d2) => {
+		const d = Math.sqrt(d2) / 2.4;
+		return d < 1 ? (1 - d) * 3 / (Math.PI * 2.4 * 2.4) : 0;
+	}
+};
+/** Bivariate kernel density as terrain: for scatter data too dense to read as points. */
+var DensitySurface = class extends SurfaceBase {
+	static meta = {
+		id: "density-surface",
+		name: "Density surface",
+		family: ChartFamily.Distribution,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Estimates a two-dimensional kernel density from scattered points and raises it into a surface, pooled or per group.",
+		tags: [
+			"kde",
+			"bivariate",
+			"density",
+			"scatter",
+			"joint distribution"
+		],
+		sample: (seed) => SampleData.points(seed, 300, 3),
+		variants: {
+			kernel: Object.values(SurfaceDensityKernel),
+			bandwidth: [
+				1,
+				.6,
+				1.6
+			],
+			mark: [
+				"surface",
+				"rings",
+				"rows"
+			],
+			grouped: [true, false],
+			rug: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			x: "x",
+			y: "y",
+			group: "group",
+			kernel: "gaussian",
+			bandwidth: 1,
+			mark: "surface",
+			grouped: true,
+			rug: true
+		};
+	}
+	estimate(rows, axisX, axisY, hx, hy) {
+		const kernel = KERNELS[this.options.kernel], share = rows.length * hx * hy || 1;
+		return SurfaceField.compute(axisX, axisY, (x, y) => rows.reduce((sum, row) => sum + kernel(((x - row.x) / hx) ** 2 + ((y - row.y) / hy) ** 2), 0) / share);
+	}
+	build(ctx) {
+		const { data, x, y, group: key, bandwidth, mark, grouped, rug } = this.options;
+		const rows = (data ?? []).map((row) => ({
+			x: +(row[x] ?? NaN),
+			y: +(row[y] ?? NaN),
+			name: grouped ? String(row[key] ?? "") : ""
+		})).filter((row) => Number.isFinite(row.x) && Number.isFinite(row.y));
+		const n = 56;
+		const sdx = deviation(rows, (row) => row.x) || 1, sdy = deviation(rows, (row) => row.y) || 1;
+		const factor = Math.max(rows.length, 2) ** (-1 / 6) * bandwidth;
+		const hx = sdx * factor, hy = sdy * factor;
+		const min = (values) => Math.min(...values), max = (values) => Math.max(...values);
+		const xs = rows.map((row) => row.x), ys = rows.map((row) => row.y);
+		const [x0, x1] = rows.length ? [min(xs) - 1.5 * hx, max(xs) + 1.5 * hx] : [0, 1], [y0, y1] = rows.length ? [min(ys) - 1.5 * hy, max(ys) + 1.5 * hy] : [0, 1];
+		const axisX = Array.from({ length: n }, (_, k) => x0 + (x1 - x0) * k / 55), axisY = Array.from({ length: n }, (_, k) => y0 + (y1 - y0) * k / 55);
+		const groups = rows.length ? [...group(rows, (row) => row.name)].map(([name, list]) => ({
+			name,
+			list,
+			field: this.estimate(list, axisX, axisY, hx, hy)
+		})) : [];
+		const peak = Math.max(1e-12, ...groups.map(({ field }) => field.zMax));
+		const domain = [0, peak];
+		const ticks = {
+			x: this.ticks([x0, x1], (v) => (v - x0) / (x1 - x0) * 2 - 1),
+			y: this.ticks([y0, y1], (v) => 1 - (v - y0) / (y1 - y0) * 2),
+			z: []
+		};
+		this.box(ctx, ticks);
+		const lift = this.rise(ctx);
+		const seq = this.painter(ctx, domain);
+		for (const { name, field, list } of groups) {
+			const space = new SurfaceSpace(field, ScaleKind.Linear, [FLOOR, CEIL], domain);
+			const flat = grouped ? ctx.color(ctx.palette.color(name)) : null;
+			const faint = flat?.clone().lerp(ctx.color(ctx.theme.surface), .72);
+			const paint = (value) => flat ? faint.clone().lerp(flat, Math.min(1, value / peak * 3)) : seq(value);
+			if (mark === "surface") this.sheet(ctx, space, paint, lift, name);
+			if (mark === "rings") this.rings(space, paint, lift);
+			if (mark === "rows") this.rowsMark(space, paint, lift);
+			if (rug) this.dots(ctx, list.map((row) => [
+				(row.x - x0) / (x1 - x0) * 2 - 1,
+				FLOOR + .01,
+				1 - (row.y - y0) / (y1 - y0) * 2
+			]), .01, () => flat ?? ctx.color(ctx.theme.inkSecondary), ctx.root);
+		}
+	}
+	sheet(ctx, space, paint, parent, name) {
+		const { field } = space;
+		const floorline = .001 * field.zMax;
+		const place = (i, j) => field.at(i, j) < floorline ? [
+			NaN,
+			NaN,
+			NaN
+		] : space.at(i, j);
+		this.solid(ctx, SurfaceGeometry.grid(field.nx, field.ny, place, (i, j) => paint(field.at(i, j))), parent, (k) => ({
+			title: name || void 0,
+			rows: [["density", short(field.at(k % field.nx, Math.floor(k / field.nx)))]]
+		}));
+	}
+	rings(space, paint, parent) {
+		const { field } = space;
+		const batch = new TubeBatch(.0062);
+		for (const { value, paths } of field.lines(Array.from({ length: 8 }, (_, k) => field.zMax * (k + 1) / 9))) {
+			const color = paint(value);
+			for (const path of paths) batch.add(path.map(([i, j]) => {
+				const [x, z] = space.ground(i, j);
+				return [
+					x,
+					space.level(value),
+					z
+				];
+			}), color);
+		}
+		this.tubes(batch, parent);
+	}
+	rowsMark(space, paint, parent) {
+		const { field } = space;
+		const batch = new TubeBatch(.0052);
+		for (let j = 0; j < field.ny; j += 3) batch.add(Array.from({ length: field.nx }, (_, i) => space.at(i, j)), (k) => paint(field.at(k, j)));
+		this.tubes(batch, parent);
+	}
+};
+export { DensitySurface, SurfaceDensityKernel, SurfaceDensityMark };

package/dist/charts/threesurfaces/GridSurfaceBase.js

@@ -0,0 +1,64 @@
+import { SurfaceBase, SurfaceProjection } from "./SurfaceBase.js";
+import { SurfaceField } from "./SurfaceField.js";
+import { format } from "d3";
+// src/charts/threesurfaces/GridSurfaceBase.ts
+var short = format(".3~g");
+/** Charts over one `z = f(x, y)` grid. Accepts `GridData`, or rows with `x`, `y`, `z` columns. */
+var GridSurfaceBase = class extends SurfaceBase {
+	defaults() {
+		return {
+			...super.defaults(),
+			x: "x",
+			y: "y",
+			z: "z"
+		};
+	}
+	field(limit = 90) {
+		const { data, x, y, z } = this.options;
+		return SurfaceField.from(data, {
+			x,
+			y,
+			z
+		}).capped(limit);
+	}
+	table() {
+		const field = SurfaceField.from(this.options.data, this.options);
+		return {
+			columns: [
+				"x",
+				"y",
+				"z"
+			],
+			rows: Array.from({ length: field.ny }, (_, j) => Array.from({ length: field.nx }, (_, i) => [
+				field.x[i],
+				field.y[j],
+				field.at(i, j)
+			])).flat()
+		};
+	}
+	axes(space) {
+		const { field } = space;
+		const [x0, x1] = field.xDomain, [y0, y1] = field.yDomain;
+		return {
+			x: this.ticks(field.xDomain, (v) => (v - x0) / (x1 - x0 || 1) * 2 - 1),
+			y: this.ticks(field.yDomain, (v) => 1 - (v - y0) / (y1 - y0 || 1) * 2),
+			z: this.ticks(field.zDomain, space.level, 3)
+		};
+	}
+	gridTip({ field }) {
+		return (k) => {
+			const i = k % field.nx, j = Math.floor(k / field.nx), { x, y, z } = this.options;
+			return { rows: [
+				[x ?? "x", short(field.x[i])],
+				[y ?? "y", short(field.y[j])],
+				[z ?? "z", short(field.at(i, j))]
+			] };
+		};
+	}
+	project(ctx, space, kind, paint) {
+		if (kind === SurfaceProjection.FloorContours) this.floorContours(ctx, space, paint);
+		if (kind === SurfaceProjection.FloorHeatmap) this.floorHeatmap(ctx, space, paint);
+		if (kind === SurfaceProjection.Walls) this.wallProfiles(ctx, space, paint);
+	}
+};
+export { GridSurfaceBase, short };

package/dist/charts/threesurfaces/HeightfieldBars.js

@@ -0,0 +1,138 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GridSurfaceBase, short } from "./GridSurfaceBase.js";
+import { CEIL, FLOOR, SurfaceSpace } from "./SurfaceSpace.js";
+import { ConeGeometry, CylinderGeometry, InstancedMesh, MeshStandardMaterial, Object3D } from "three";
+import { RoundedBoxGeometry } from "three/addons/geometries/RoundedBoxGeometry.js";
+// src/charts/threesurfaces/HeightfieldBars.ts
+var HeightBarShape = /* @__PURE__ */ function(HeightBarShape) {
+	HeightBarShape["Box"] = "box";
+	HeightBarShape["Cylinder"] = "cylinder";
+	HeightBarShape["Hexagon"] = "hexagon";
+	HeightBarShape["Spike"] = "spike";
+	return HeightBarShape;
+}({});
+var HeightBarLayout = /* @__PURE__ */ function(HeightBarLayout) {
+	HeightBarLayout["Square"] = "square";
+	HeightBarLayout["Staggered"] = "staggered";
+	return HeightBarLayout;
+}({});
+var HeightBarBaseline = /* @__PURE__ */ function(HeightBarBaseline) {
+	HeightBarBaseline["Zero"] = "zero";
+	HeightBarBaseline["Magnitude"] = "magnitude";
+	return HeightBarBaseline;
+}({});
+/** Discrete columns over a grid: when exact cell values matter more than a smooth impression. */
+var HeightfieldBars = class extends GridSurfaceBase {
+	static meta = {
+		id: "heightfield-bars",
+		name: "Heightfield bars",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Three,
+		shape: DataShape.Grid,
+		description: "Bins a height field into columns from a true zero baseline, so each cell reads as a countable value.",
+		tags: [
+			"lego plot",
+			"city",
+			"columns",
+			"3d histogram"
+		],
+		sample: (seed) => SampleData.surface(seed, 40),
+		variants: {
+			shape: [
+				"box",
+				"cylinder",
+				"hexagon",
+				"spike"
+			],
+			layout: ["square", "staggered"],
+			baseline: ["zero", "magnitude"],
+			bins: [
+				18,
+				12,
+				26
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			shape: "box",
+			layout: "square",
+			baseline: "zero",
+			bins: 18
+		};
+	}
+	unit(width) {
+		const radius = width * .46;
+		switch (this.options.shape) {
+			case "cylinder": return new CylinderGeometry(radius, radius, 1, 20).translate(0, .5, 0);
+			case "hexagon": return new CylinderGeometry(radius * 1.08, radius * 1.08, 1, 6).translate(0, .5, 0);
+			case "spike": return new ConeGeometry(radius, 1, 12).translate(0, .5, 0);
+			default: return new RoundedBoxGeometry(width * .86, 1, width * .86, 2, width * .08).translate(0, .5, 0);
+		}
+	}
+	build(ctx) {
+		const { bins, layout, baseline, shape } = this.options;
+		const source = this.field(200);
+		const cols = bins, stagger = layout === "staggered";
+		const cells = [];
+		const width = 2 / cols;
+		for (let j = 0; j < cols; j++) for (let i = 0; i < cols; i++) {
+			if (stagger && j % 2 === 1 && i === cols - 1) continue;
+			const shift = stagger && j % 2 === 1 ? .5 : 0;
+			let total = 0, count = 0;
+			const fi0 = (i + shift) / cols * (source.nx - 1), fi1 = (i + shift + 1) / cols * (source.nx - 1), fj0 = j / cols * (source.ny - 1), fj1 = (j + 1) / cols * (source.ny - 1);
+			for (let v = Math.floor(fj0); v <= Math.ceil(fj1); v++) for (let u = Math.floor(fi0); u <= Math.ceil(fi1); u++) {
+				const z = source.at(u, v);
+				if (!Number.isNaN(z)) {
+					total += z;
+					count++;
+				}
+			}
+			if (count) cells.push({
+				x: -1 + (i + shift + .5) * width,
+				z: 1 - (j + .5) * width,
+				value: total / count,
+				i,
+				j
+			});
+		}
+		const signed = baseline === "zero";
+		const values = cells.map(({ value }) => signed ? value : Math.abs(value));
+		const top = Math.max(0, ...values), low = Math.min(0, ...values);
+		const domain = [low, top > low ? top : low + 1];
+		const height = (value) => FLOOR + (value - domain[0]) / (domain[1] - domain[0]) * (CEIL - FLOOR);
+		const zero = height(0);
+		const space = new SurfaceSpace(source);
+		const paint = this.painter(ctx, domain);
+		const ticks = this.axes(space);
+		this.box(ctx, {
+			...ticks,
+			z: this.ticks(domain, height, 3)
+		});
+		if (!cells.length) return;
+		const bars = new InstancedMesh(this.unit(width), new MeshStandardMaterial({ roughness: shape === "spike" ? .4 : .55 }), cells.length);
+		bars.castShadow = true;
+		const dummy = new Object3D();
+		const place = (progress) => {
+			values.forEach((value, k) => {
+				const h = height(value) - zero;
+				dummy.position.set(cells[k].x, h < 0 ? zero + h * progress : zero, cells[k].z);
+				dummy.scale.set(1, Math.max(1e-4, Math.abs(h) * progress), 1);
+				dummy.updateMatrix();
+				bars.setMatrixAt(k, dummy.matrix);
+			});
+			bars.instanceMatrix.needsUpdate = true;
+		};
+		values.forEach((value, k) => bars.setColorAt(k, paint(value)));
+		ctx.reveal(place);
+		ctx.root.add(bars);
+		ctx.pick(bars, (k) => ({ rows: [
+			["column", cells[k].i],
+			["row", cells[k].j],
+			["value", short(values[k])]
+		] }));
+	}
+};
+export { HeightBarBaseline, HeightBarLayout, HeightBarShape, HeightfieldBars };