@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/matrix/MatrixDotChart.js

@@ -0,0 +1,98 @@
+import { ChartFamily, DataShape, Dimension, SymbolKind } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixChart } from "./MatrixChart.js";
+import { MatrixNormalize } from "./matrixEnums.js";
+import { CHAR } from "./MatrixSurface.js";
+// src/charts/matrix/MatrixDotChart.ts
+var MatrixDotFill = /* @__PURE__ */ function(MatrixDotFill) {
+	MatrixDotFill["Rows"] = "fill-rows";
+	MatrixDotFill["Columns"] = "fill-columns";
+	MatrixDotFill["Centre"] = "fill-centre";
+	return MatrixDotFill;
+}({});
+var KEY = 20;
+var dot = (symbol, x, y, r) => {
+	if (symbol === SymbolKind.Square) return `M${(x - r).toFixed(2)},${(y - r).toFixed(2)}h${2 * r}v${2 * r}h${-2 * r}Z`;
+	if (symbol === SymbolKind.Diamond) return `M${x.toFixed(2)},${(y - r).toFixed(2)}l${r},${r}l${-r},${r}l${-r},${-r}Z`;
+	return `M${(x - r).toFixed(2)},${y.toFixed(2)}a${r},${r} 0 1,0 ${2 * r},0a${r},${r} 0 1,0 ${-2 * r},0Z`;
+};
+/** Unit counting inside a matrix: every dot is the same amount, so a cell's value can be read by counting. */
+var MatrixDotChart = class extends MatrixChart {
+	static meta = {
+		id: "matrix-dot",
+		name: "Matrix dot chart",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Two,
+		shape: DataShape.Matrix,
+		description: "Fills each matrix cell with countable unit dots, for showing counts where exact quantity matters.",
+		tags: [
+			"unit chart",
+			"isotype",
+			"dot matrix"
+		],
+		sample: (seed) => SampleData.categories(seed, 5, 7),
+		variants: {
+			capacity: [
+				16,
+				9,
+				25
+			],
+			fill: [
+				"fill-rows",
+				"fill-columns",
+				"fill-centre"
+			],
+			symbol: [
+				SymbolKind.Circle,
+				SymbolKind.Square,
+				SymbolKind.Diamond
+			],
+			normalize: [
+				MatrixNormalize.None,
+				MatrixNormalize.Row,
+				MatrixNormalize.Column
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			capacity: 16,
+			fill: "fill-rows",
+			symbol: SymbolKind.Circle,
+			normalize: MatrixNormalize.None
+		};
+	}
+	/** Slot positions on a `side × side` lattice, in fill order. */
+	slots(side) {
+		const grid = Array.from({ length: side * side }, (_, i) => [i % side, Math.floor(i / side)]);
+		const { fill } = this.options, mid = (side - 1) / 2;
+		if (fill === "fill-rows") return grid.map(([x, y]) => [x, side - 1 - y]);
+		if (fill === "fill-columns") return grid.map(([x, y]) => [y, side - 1 - x]);
+		return grid.sort((a, b) => Math.hypot(a[0] - mid, a[1] - mid) - Math.hypot(b[0] - mid, b[1] - mid) || a[1] - b[1] || a[0] - b[0]);
+	}
+	drawMatrix(ctx, source) {
+		const { normalize, capacity, symbol } = this.options;
+		const model = source.normalize(normalize);
+		const frame = this.frame(ctx, model, { bottom: KEY });
+		const side = Math.max(2, Math.round(Math.sqrt(capacity))), unit = model.reach / (side * side);
+		const slots = this.slots(side);
+		const pitch = Math.min((frame.cw - 6) / side, (frame.ch - 6) / side), r = Math.max(1, pitch * .4);
+		const fill = ctx.palette.sequential(.68), low = ctx.palette.diverging(-.9);
+		const count = (cell) => Math.round(Math.abs(cell.value ?? 0) / unit);
+		const path = (cell) => slots.slice(0, count(cell)).map(([x, y]) => dot(symbol, (x - (side - 1) / 2) * pitch, (y - (side - 1) / 2) * pitch, +r.toFixed(2))).join("");
+		const cells = ctx.marks("cells", "path", model.cells.filter(count), (cell) => cell.key).attr("d", path).attr("fill", (cell) => cell.value < 0 ? low : fill);
+		ctx.set(cells, { transform: (cell) => `translate(${frame.cx(cell.c)},${frame.cy(cell.r)})` }, { transform: (cell) => `translate(${frame.cx(cell.c)},${frame.cy(cell.r)}) scale(0)` }, 2);
+		ctx.hover(cells, (cell) => ({
+			title: `${cell.row} · ${cell.column}`,
+			color: fill,
+			rows: [["Dots", count(cell)], ["Value", normalize === MatrixNormalize.None ? +cell.value.toFixed(2) : `${(cell.value * 100).toFixed(1)}%`]]
+		}));
+		this.axisLabels(ctx, model, frame);
+		const text = `= ${normalize === MatrixNormalize.None ? +unit.toFixed(2) : `${(unit * 100).toFixed(1)}%`}`;
+		const y = frame.y + frame.height + 12;
+		ctx.marks("unit-key", "path", [0]).attr("d", dot(symbol, frame.x + 5, y, 4)).attr("fill", fill);
+		ctx.text(ctx.marks("unit-key-label", "text", [text]), 10.5).attr("x", frame.x + 14).attr("y", y + 3.5).text((d) => d.slice(0, Math.floor(160 / CHAR)));
+	}
+};
+export { MatrixDotChart, MatrixDotFill };

package/dist/charts/matrix/MatrixGlyphs.js

@@ -0,0 +1,82 @@
+import { MatrixGlyph } from "./matrixEnums.js";
+import { arc } from "d3";
+// src/charts/matrix/MatrixGlyphs.ts
+var circle = (r) => `M${-r},0a${r},${r} 0 1,0 ${2 * r},0a${r},${r} 0 1,0 ${-2 * r},0Z`;
+var round = (value) => +value.toFixed(2);
+/** SVG paths for one cell, centred on the origin. `t` is magnitude 0..1; area, never radius, carries it. */
+var MatrixGlyphs = class MatrixGlyphs {
+	static tile(w, h, radius = 2, x = -w / 2, y = -h / 2) {
+		const r = round(Math.min(radius, w / 2, h / 2));
+		return `M${round(x + r)},${round(y)}h${round(w - 2 * r)}a${r},${r} 0 0 1 ${r},${r}v${round(h - 2 * r)}a${r},${r} 0 0 1 ${-r},${r}h${round(2 * r - w)}a${r},${r} 0 0 1 ${-r},${-r}v${round(2 * r - h)}a${r},${r} 0 0 1 ${r},${-r}Z`;
+	}
+	static hexagon(radius) {
+		return `M${[
+			0,
+			1,
+			2,
+			3,
+			4,
+			5
+		].map((i) => {
+			const angle = Math.PI / 6 + i * Math.PI / 3;
+			return `${round(radius * Math.cos(angle))},${round(radius * Math.sin(angle))}`;
+		}).join("L")}Z`;
+	}
+	static polygon(points) {
+		return `M${points.map(([x, y]) => `${round(x)},${round(y)}`).join("L")}Z`;
+	}
+	static path(glyph, w, h, size, sign = 1) {
+		const t = Math.max(0, Math.min(1, size)), reach = Math.min(w, h) / 2, a = reach * Math.sqrt(t);
+		switch (glyph) {
+			case MatrixGlyph.Circle: return circle(round(a));
+			case MatrixGlyph.Square: return MatrixGlyphs.tile(2 * a, 2 * a, Math.min(2, a / 2));
+			case MatrixGlyph.Diamond: return MatrixGlyphs.polygon([
+				[0, -a],
+				[a, 0],
+				[0, a],
+				[-a, 0]
+			]);
+			case MatrixGlyph.Triangle: return MatrixGlyphs.polygon(sign < 0 ? [
+				[-a, -a * .8],
+				[a, -a * .8],
+				[0, a]
+			] : [
+				[0, -a],
+				[a, a * .8],
+				[-a, a * .8]
+			]);
+			case MatrixGlyph.Bar: return MatrixGlyphs.bar(w, h, t);
+			case MatrixGlyph.Column: return MatrixGlyphs.column(w, h, t);
+			case MatrixGlyph.Pie: return MatrixGlyphs.pie(reach, t, sign);
+			case MatrixGlyph.Ellipse: return MatrixGlyphs.ellipse(reach, t, sign);
+			default: return MatrixGlyphs.tile(w, h);
+		}
+	}
+	/** Length from the cell's left edge. */
+	static bar(w, h, t) {
+		const long = Math.max(1, w * t), thick = h * .64;
+		return MatrixGlyphs.tile(long, thick, 2, -w / 2);
+	}
+	/** Height from the cell's bottom edge. */
+	static column(w, h, t) {
+		const tall = Math.max(1, h * t), thick = w * .64;
+		return MatrixGlyphs.tile(thick, tall, 2, -thick / 2, h / 2 - tall);
+	}
+	/** A thin ring for the whole with a filled wedge for the part, clockwise for positive. */
+	static pie(reach, t, sign) {
+		const r = round(reach * .92), turn = Math.PI * 2 * Math.min(1, t) * (sign < 0 ? -1 : 1);
+		return `${arc()({
+			innerRadius: 0,
+			outerRadius: r,
+			startAngle: 0,
+			endAngle: turn
+		}) ?? ""}${circle(r)}${circle(round(r - 1))}`;
+	}
+	/** Murdoch's correlation ellipse: axes follow `sqrt(1 ± r)`, leaning with the sign. */
+	static ellipse(reach, t, sign) {
+		const major = round(reach * Math.sqrt(1 + t) * .68), minor = round(Math.max(.5, reach * Math.sqrt(1 - t) * .68));
+		const lean = sign < 0 ? 45 : -45, dx = round(major * Math.cos(lean * Math.PI / 180)), dy = round(major * Math.sin(lean * Math.PI / 180));
+		return `M${-dx},${-dy}A${major},${minor} ${lean} 1,1 ${dx},${dy}A${major},${minor} ${lean} 1,1 ${-dx},${-dy}Z`;
+	}
+};
+export { MatrixGlyphs };

package/dist/charts/matrix/MatrixModel.js

@@ -0,0 +1,99 @@
+import { MatrixNormalize } from "./matrixEnums.js";
+import { extent, sum } from "d3";
+// src/charts/matrix/MatrixModel.ts
+var numeric = (value) => {
+	if (value === null || value === void 0 || value === "") return null;
+	const parsed = +value;
+	return Number.isFinite(parsed) ? parsed : null;
+};
+var plain = (value) => value ?? 0;
+/**
+* Rows × columns of numbers, built from `MatrixData` or long-form rows. Source positions, not labels,
+* identify cells: duplicate labels are safe, and a cell keeps its identity through any reordering.
+*/
+var MatrixModel = class MatrixModel {
+	rows;
+	columns;
+	values;
+	rowIds;
+	columnIds;
+	constructor(rows, columns, values, rowIds = rows.map((_, i) => i), columnIds = columns.map((_, i) => i)) {
+		this.rows = rows;
+		this.columns = columns;
+		this.values = values;
+		this.rowIds = rowIds;
+		this.columnIds = columnIds;
+	}
+	static from(data, { x = "series", y = "category", value = "value" } = {}) {
+		if (!data) return new MatrixModel([], [], []);
+		if (!Array.isArray(data)) {
+			const { rows = [], columns = [], values = [] } = data;
+			return new MatrixModel(rows.map(String), columns.map(String), rows.map((_, r) => columns.map((_, c) => numeric(values[r]?.[c]))));
+		}
+		const rows = /* @__PURE__ */ new Map(), columns = /* @__PURE__ */ new Map();
+		const place = (keys, key) => {
+			if (!keys.has(key)) keys.set(key, keys.size);
+			return keys.get(key);
+		};
+		const placed = data.map((row) => [
+			place(rows, String(row[y])),
+			place(columns, String(row[x])),
+			numeric(row[value])
+		]);
+		const values = Array.from(rows, () => Array.from(columns, () => null));
+		for (const [r, c, amount] of placed) if (amount !== null) values[r][c] = (values[r][c] ?? 0) + amount;
+		return new MatrixModel([...rows.keys()], [...columns.keys()], values);
+	}
+	get empty() {
+		return !this.rows.length || !this.columns.length;
+	}
+	/** Every cell, always in source order, so a reordered matrix redraws the same marks in new places. */
+	get cells() {
+		const rows = this.rows.map((_, r) => r).sort((a, b) => this.rowIds[a] - this.rowIds[b]);
+		const columns = this.columns.map((_, c) => c).sort((a, b) => this.columnIds[a] - this.columnIds[b]);
+		return rows.flatMap((r) => columns.map((c) => ({
+			r,
+			c,
+			row: this.rows[r],
+			column: this.columns[c],
+			value: this.values[r][c],
+			key: `${this.rowIds[r]}/${this.columnIds[c]}`
+		})));
+	}
+	/** Lowest and highest value present; `[0, 1]` when there are none. */
+	get domain() {
+		const [low, high] = extent(this.values.flat(), (value) => value ?? void 0);
+		return low === void 0 || high === void 0 ? [0, 1] : [low, high];
+	}
+	get reach() {
+		const [low, high] = this.domain;
+		return Math.max(Math.abs(low), Math.abs(high)) || 1;
+	}
+	get rowTotals() {
+		return this.values.map((row) => sum(row, plain));
+	}
+	get columnTotals() {
+		return this.columns.map((_, c) => sum(this.values, (row) => plain(row[c])));
+	}
+	/** Rows as plain vectors, nulls as zero. */
+	get rowVectors() {
+		return this.values.map((row) => row.map(plain));
+	}
+	get columnVectors() {
+		return this.columns.map((_, c) => this.values.map((row) => plain(row[c])));
+	}
+	reorder(rows, columns) {
+		return new MatrixModel(rows.map((r) => this.rows[r]), columns.map((c) => this.columns[c]), rows.map((r) => columns.map((c) => this.values[r][c])), rows.map((r) => this.rowIds[r]), columns.map((c) => this.columnIds[c]));
+	}
+	transpose() {
+		return new MatrixModel(this.columns, this.rows, this.columns.map((_, c) => this.values.map((row) => row[c])), this.columnIds, this.rowIds);
+	}
+	normalize(kind = MatrixNormalize.None) {
+		if (kind === MatrixNormalize.None) return this;
+		const magnitude = (list) => sum(list, (value) => Math.abs(plain(value))) || 1;
+		const rows = this.values.map(magnitude), columns = this.columns.map((_, c) => magnitude(this.values.map((row) => row[c]))), total = sum(rows);
+		const divisor = (r, c) => kind === MatrixNormalize.Row ? rows[r] : kind === MatrixNormalize.Column ? columns[c] : total;
+		return new MatrixModel(this.rows, this.columns, this.values.map((row, r) => row.map((value, c) => value === null ? null : value / divisor(r, c))), this.rowIds, this.columnIds);
+	}
+};
+export { MatrixModel };

package/dist/charts/matrix/MatrixSeriation.js

@@ -0,0 +1,162 @@
+import { MatrixDistance, MatrixLinkage } from "./matrixEnums.js";
+import { deviation, mean, range, sum } from "d3";
+// src/charts/matrix/MatrixSeriation.ts
+var CLUSTER_LIMIT = 400;
+/** Row and column reordering algorithms. Each returns a permutation of indices. */
+var MatrixSeriation = class MatrixSeriation {
+	static distance(a, b, metric = MatrixDistance.Euclidean) {
+		if (metric === MatrixDistance.Manhattan) return sum(a, (value, i) => Math.abs(value - b[i]));
+		if (metric === MatrixDistance.Correlation) return 1 - MatrixSeriation.correlation(a, b);
+		return Math.sqrt(sum(a, (value, i) => (value - b[i]) ** 2));
+	}
+	static correlation(a, b) {
+		const spreadA = deviation(a) ?? 0, spreadB = deviation(b) ?? 0;
+		if (!spreadA || !spreadB) return 0;
+		const meanA = mean(a), meanB = mean(b);
+		return sum(a, (value, i) => (value - meanA) * (b[i] - meanB)) / ((a.length - 1) * spreadA * spreadB);
+	}
+	/** Agglomerative clustering by Lance-Williams update. Returns null above 400 items, where it stops being interactive. */
+	static cluster(vectors, metric = MatrixDistance.Euclidean, linkage = MatrixLinkage.Average) {
+		if (!vectors.length || vectors.length > CLUSTER_LIMIT) return null;
+		const n = vectors.length;
+		const d = vectors.map((a) => vectors.map((b) => MatrixSeriation.distance(a, b, metric)));
+		const nodes = vectors.map((_, leaf) => ({
+			id: leaf,
+			leaf,
+			height: 0,
+			size: 1
+		}));
+		const active = new Set(range(n));
+		let next = n;
+		while (active.size > 1) {
+			let a = -1, b = -1, best = Infinity;
+			for (const i of active) for (const j of active) if (i < j && d[i][j] < best) {
+				best = d[i][j];
+				a = i;
+				b = j;
+			}
+			const left = nodes[a], right = nodes[b];
+			active.delete(b);
+			for (const k of active) {
+				if (k === a) continue;
+				const blended = MatrixSeriation.linked(linkage, d[a][k], d[b][k], best, left.size, right.size, nodes[k].size);
+				d[a][k] = d[k][a] = blended;
+			}
+			const earlier = MatrixSeriation.first(left) <= MatrixSeriation.first(right);
+			nodes[a] = {
+				id: next++,
+				height: best,
+				size: left.size + right.size,
+				left: earlier ? left : right,
+				right: earlier ? right : left
+			};
+		}
+		return nodes[[...active][0]];
+	}
+	static first(node) {
+		return node.leaf ?? MatrixSeriation.first(node.left);
+	}
+	static linked(linkage, ak, bk, ab, na, nb, nk) {
+		switch (linkage) {
+			case MatrixLinkage.Single: return Math.min(ak, bk);
+			case MatrixLinkage.Complete: return Math.max(ak, bk);
+			case MatrixLinkage.Ward: return Math.sqrt(Math.max(0, ((na + nk) * ak ** 2 + (nb + nk) * bk ** 2 - nk * ab ** 2) / (na + nb + nk)));
+			default: return (na * ak + nb * bk) / (na + nb);
+		}
+	}
+	static leaves(node) {
+		if (!node) return [];
+		return node.leaf !== void 0 ? [node.leaf] : [...MatrixSeriation.leaves(node.left), ...MatrixSeriation.leaves(node.right)];
+	}
+	/** Splits the tree at its `k` tallest merges; returns the subtrees. */
+	static cut(root, k) {
+		const groups = [root];
+		while (groups.length < k) {
+			const tallest = groups.reduce((top, node) => node.height > top.height ? node : top);
+			if (tallest.leaf !== void 0) break;
+			groups.splice(groups.indexOf(tallest), 1, tallest.left, tallest.right);
+		}
+		return groups;
+	}
+	static clustered(vectors, metric, linkage) {
+		const order = MatrixSeriation.leaves(MatrixSeriation.cluster(vectors, metric, linkage));
+		return order.length ? order : range(vectors.length);
+	}
+	/** Orders by score on the first principal component, found by power iteration from a fixed start. */
+	static spectral(vectors) {
+		const width = vectors[0]?.length ?? 0;
+		if (!width) return range(vectors.length);
+		const centres = range(width).map((i) => mean(vectors, (vector) => vector[i]));
+		const centred = vectors.map((vector) => vector.map((value, i) => value - centres[i]));
+		let axis = range(width).map((i) => 1 + i / width);
+		for (let step = 0; step < 40; step++) {
+			const scores = centred.map((vector) => sum(vector, (value, i) => value * axis[i]));
+			const moved = range(width).map((i) => sum(centred, (vector, r) => vector[i] * scores[r]));
+			const length = Math.sqrt(sum(moved, (value) => value * value)) || 1;
+			axis = moved.map((value) => value / length);
+		}
+		const scores = centred.map((vector) => sum(vector, (value, i) => value * axis[i]));
+		return range(vectors.length).sort((a, b) => scores[a] - scores[b] || a - b);
+	}
+	/** Alternates sorting rows and columns by the weighted mean position of their mass. */
+	static barycenter(model) {
+		const weights = model.rowVectors.map((row) => row.map(Math.abs));
+		let rows = range(model.rows.length), columns = range(model.columns.length);
+		const centre = (list) => {
+			const total = sum(list);
+			return total ? sum(list, (w, i) => w * i) / total : list.length / 2;
+		};
+		for (let step = 0; step < 12; step++) {
+			const rowScore = weights.map((row) => centre(columns.map((c) => row[c])));
+			rows = [...rows].sort((a, b) => rowScore[a] - rowScore[b] || a - b);
+			const columnScore = model.columns.map((_, c) => centre(rows.map((r) => weights[r][c])));
+			columns = [...columns].sort((a, b) => columnScore[a] - columnScore[b] || a - b);
+		}
+		return {
+			rows,
+			columns
+		};
+	}
+	/** Shortest open path through the items: nearest-neighbour tour improved by 2-opt. */
+	static tour(vectors) {
+		const n = vectors.length;
+		if (n < 3) return range(n);
+		const d = vectors.map((a) => vectors.map((b) => MatrixSeriation.distance(a, b)));
+		const left = new Set(range(1, n));
+		const path = [0];
+		while (left.size) {
+			const last = path[path.length - 1];
+			let best = -1;
+			for (const candidate of left) if (best < 0 || d[last][candidate] < d[last][best]) best = candidate;
+			left.delete(best);
+			path.push(best);
+		}
+		for (let improved = true, round = 0; improved && round < 20; round++) {
+			improved = false;
+			for (let i = 0; i < n - 2; i++) for (let j = i + 2; j < n - 1; j++) if (d[path[i]][path[j]] + d[path[i + 1]][path[j + 1]] < d[path[i]][path[i + 1]] + d[path[j]][path[j + 1]] - 1e-9) {
+				path.splice(i + 1, j - i, ...path.slice(i + 1, j + 1).reverse());
+				improved = true;
+			}
+		}
+		return path;
+	}
+	/** McCormick's bond energy: inserts each item where it best matches its new neighbours. */
+	static bondEnergy(vectors) {
+		if (vectors.length < 3) return range(vectors.length);
+		const bond = (a, b) => a === void 0 || b === void 0 ? 0 : sum(vectors[a], (value, i) => value * vectors[b][i]);
+		const order = [0, 1];
+		for (let item = 2; item < vectors.length; item++) {
+			let at = 0, best = -Infinity;
+			for (let slot = 0; slot <= order.length; slot++) {
+				const gain = 2 * (bond(order[slot - 1], item) + bond(item, order[slot]) - bond(order[slot - 1], order[slot]));
+				if (gain > best) {
+					best = gain;
+					at = slot;
+				}
+			}
+			order.splice(at, 0, item);
+		}
+		return order;
+	}
+};
+export { MatrixSeriation };

package/dist/charts/matrix/MatrixSurface.js

@@ -0,0 +1,43 @@
+import { Chart2D } from "../../core/Chart2D.js";
+import { LegendPosition } from "../../core/enums.js";
+import { rgb } from "d3";
+// src/charts/matrix/MatrixSurface.ts
+/** Estimated width of one character at 11px. */
+var CHAR = 6.2;
+/** Truncates to what fits in `width` px of 11px text. */
+function fitText(text, width, char = CHAR) {
+	const room = Math.floor(width / char);
+	return text.length <= room ? text : room < 2 ? "" : `${text.slice(0, room - 1)}…`;
+}
+/** Canvas shared by every chart in this module: a clean slate on shape changes, and legible ink on data-coloured fills. */
+var MatrixSurface = class extends Chart2D {
+	shape = "";
+	get legendPosition() {
+		return this.options.legend ?? LegendPosition.None;
+	}
+	plotMargin() {
+		return {
+			top: 6,
+			right: 16,
+			bottom: 10,
+			left: 16
+		};
+	}
+	draw(ctx) {
+		const { data: _, width: __, height: ___, ...rest } = this.options;
+		const shape = JSON.stringify(rest);
+		if (shape !== this.shape || this.blank) ctx.root.selectAll("*").remove();
+		this.shape = shape;
+		if (!this.blank) this.compose(ctx);
+	}
+	/** The theme ink or surface that contrasts best with `fill`, which may be any CSS colour. */
+	inkOn(ctx, fill) {
+		const luma = (value) => {
+			const { r, g, b } = rgb(value);
+			return .299 * r + .587 * g + .114 * b;
+		};
+		const base = luma(fill);
+		return Math.abs(base - luma(ctx.theme.ink)) > Math.abs(base - luma(ctx.theme.surface)) ? ctx.theme.ink : ctx.theme.surface;
+	}
+};
+export { CHAR, MatrixSurface, fitText };

package/dist/charts/matrix/MatrixTowers3D.js

@@ -0,0 +1,152 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MatrixOrder } from "./matrixEnums.js";
+import { MatrixModel } from "./MatrixModel.js";
+import { MatrixSeriation } from "./MatrixSeriation.js";
+import { scaleBand, scaleLinear } from "d3";
+import { BoxGeometry, ConeGeometry, CylinderGeometry, InstancedMesh, Mesh, MeshStandardMaterial, Object3D, PlaneGeometry, SphereGeometry } from "three";
+// src/charts/matrix/MatrixTowers3D.ts
+var TowerShape = /* @__PURE__ */ function(TowerShape) {
+	TowerShape["Box"] = "box";
+	TowerShape["Cylinder"] = "cylinder";
+	TowerShape["Hexagon"] = "hex-prism";
+	TowerShape["Cone"] = "cone";
+	TowerShape["Sphere"] = "sphere";
+	return TowerShape;
+}({});
+var TowerHeight = /* @__PURE__ */ function(TowerHeight) {
+	TowerHeight["Linear"] = "linear-height";
+	TowerHeight["Root"] = "root-height";
+	return TowerHeight;
+}({});
+var FLOOR = -.7;
+/** A heatmap raised into relief: height doubles the colour channel, for presenting the broad shape of a matrix. */
+var MatrixTowers3D = class extends Chart3D {
+	static meta = {
+		id: "matrix-towers-3d",
+		name: "3D matrix towers",
+		family: ChartFamily.Matrix,
+		dimension: Dimension.Three,
+		shape: DataShape.Matrix,
+		description: "Raises each matrix cell into a tower, with height and colour both showing the value, for an overview of its relief.",
+		tags: [
+			"3d heatmap",
+			"cityscape",
+			"relief"
+		],
+		sample: (seed) => SampleData.matrix(seed, 9, 11),
+		variants: {
+			shape: [
+				"box",
+				"cylinder",
+				"hex-prism",
+				"cone",
+				"sphere"
+			],
+			order: [
+				MatrixOrder.Input,
+				MatrixOrder.Total,
+				MatrixOrder.Cluster
+			],
+			heightScale: ["linear-height", "root-height"],
+			padding: [.18, .4]
+		}
+	};
+	defaults() {
+		return {
+			x: "series",
+			y: "category",
+			value: "value",
+			shape: "box",
+			order: MatrixOrder.Input,
+			heightScale: "linear-height",
+			padding: .18
+		};
+	}
+	arranged() {
+		const { data, order } = this.options;
+		const model = MatrixModel.from(data, this.options);
+		if (order === MatrixOrder.Total) {
+			const rows = model.rowTotals, columns = model.columnTotals;
+			return model.reorder(model.rows.map((_, i) => i).sort((a, b) => rows[b] - rows[a] || a - b), model.columns.map((_, i) => i).sort((a, b) => columns[b] - columns[a] || a - b));
+		}
+		return order === MatrixOrder.Cluster ? model.reorder(MatrixSeriation.clustered(model.rowVectors), MatrixSeriation.clustered(model.columnVectors)) : model;
+	}
+	geometry(width, depth) {
+		const radius = Math.min(width, depth) / 2;
+		switch (this.options.shape) {
+			case "cylinder": return new CylinderGeometry(radius, radius, 1, 20);
+			case "hex-prism": return new CylinderGeometry(radius, radius, 1, 6);
+			case "cone": return new ConeGeometry(radius, 1, 20);
+			case "sphere": return new SphereGeometry(radius, 18, 14);
+			default: return new BoxGeometry(width, 1, depth);
+		}
+	}
+	build(ctx) {
+		const model = this.arranged();
+		const floor = new Mesh(new PlaneGeometry(2.3, 2.3), new MeshStandardMaterial({ color: ctx.theme.grid }));
+		floor.rotation.x = -Math.PI / 2;
+		floor.position.y = FLOOR;
+		floor.receiveShadow = true;
+		ctx.root.add(floor);
+		const cells = model.cells.filter((cell) => cell.value !== null);
+		if (!cells.length) return;
+		const { padding, heightScale, shape } = this.options;
+		const bandX = scaleBand(model.columns.map((_, c) => c), [-1, 1]).padding(padding), bandZ = scaleBand(model.rows.map((_, r) => r), [-1, 1]).padding(padding);
+		const reach = model.reach, signed = model.domain[0] < 0;
+		const lift = scaleLinear([0, reach], [0, signed ? .68 : 1.36]);
+		const base = signed ? 0 : FLOOR;
+		const towers = new InstancedMesh(this.geometry(bandX.bandwidth(), bandZ.bandwidth()), new MeshStandardMaterial({ roughness: .5 }), cells.length);
+		towers.castShadow = true;
+		if (signed) {
+			const zero = new Mesh(new PlaneGeometry(2.1, 2.1), new MeshStandardMaterial({
+				color: ctx.theme.axis,
+				transparent: true,
+				opacity: .22
+			}));
+			zero.rotation.x = -Math.PI / 2;
+			ctx.root.add(zero);
+		}
+		const [low, high] = model.domain, dummy = new Object3D();
+		const size = (value) => {
+			const share = Math.abs(value) / reach;
+			return Math.max(.002, lift(heightScale === "root-height" ? Math.sqrt(share) * reach : share * reach));
+		};
+		const place = (progress) => {
+			cells.forEach((cell, i) => {
+				const h = size(cell.value) * progress, sign = Math.sign(cell.value) || 1;
+				dummy.position.set(bandX(cell.c) + bandX.bandwidth() / 2, shape === "sphere" ? base + sign * size(cell.value) : base + sign * h / 2, bandZ(cell.r) + bandZ.bandwidth() / 2);
+				if (shape === "sphere") dummy.scale.setScalar(Math.max(.05, Math.sqrt(Math.abs(cell.value) / reach)) * progress);
+				else dummy.scale.set(1, h, 1);
+				dummy.rotation.x = shape === "cone" && sign < 0 ? Math.PI : 0;
+				dummy.updateMatrix();
+				towers.setMatrixAt(i, dummy.matrix);
+			});
+			towers.instanceMatrix.needsUpdate = true;
+		};
+		cells.forEach((cell, i) => towers.setColorAt(i, ctx.color(signed ? ctx.palette.diverging(cell.value / reach) : ctx.palette.sequential(high > low ? (cell.value - low) / (high - low) : .6))));
+		ctx.reveal(place);
+		ctx.root.add(towers);
+		ctx.pick(towers, (i) => ({
+			title: `${cells[i].row} · ${cells[i].column}`,
+			rows: [["Value", +cells[i].value.toFixed(3)]]
+		}));
+		const every = (count) => Math.ceil(count / 6);
+		model.columns.forEach((name, c) => {
+			if (c % every(model.columns.length) === 0) ctx.label(name, [
+				bandX(c) + bandX.bandwidth() / 2,
+				-.75,
+				1.2
+			], "secondary", 10);
+		});
+		model.rows.forEach((name, r) => {
+			if (r % every(model.rows.length) === 0) ctx.label(name, [
+				-1.24,
+				-.75,
+				bandZ(r) + bandZ.bandwidth() / 2
+			], "secondary", 10);
+		});
+	}
+};
+export { MatrixTowers3D, TowerHeight, TowerShape };