@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/threesurfaces/Spectrogram3DChart.js

@@ -0,0 +1,92 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { GridSurfaceBase } from "./GridSurfaceBase.js";
+import { ShortTimeTransform, SpectrogramWindow } from "./ShortTimeTransform.js";
+import { SurfaceField } from "./SurfaceField.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { SurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { SpectrumAmplitude } from "./Waterfall3DSpectrum.js";
+// src/charts/threesurfaces/Spectrogram3DChart.ts
+var SpectrogramMark = /* @__PURE__ */ function(SpectrogramMark) {
+	SpectrogramMark["Surface"] = "surface";
+	SpectrogramMark["Ridges"] = "ridges";
+	SpectrogramMark["Columns"] = "columns";
+	return SpectrogramMark;
+}({});
+/** Runs a short-time Fourier transform on your signal: for when frequency content, not the waveform, is the story. */
+var Spectrogram3DChart = class extends GridSurfaceBase {
+	static meta = {
+		id: "spectrogram-3d",
+		name: "3D spectrogram",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Computes a short-time Fourier transform of a signal and raises its magnitude over the time and frequency plane.",
+		tags: [
+			"stft",
+			"fft",
+			"time frequency",
+			"audio",
+			"chirp"
+		],
+		sample: (seed) => ShortTimeTransform.sampleSignal(seed),
+		variants: {
+			window: Object.values(SpectrogramWindow),
+			size: [64, 32],
+			overlap: [.75, .5],
+			scale: [SpectrumAmplitude.Linear, SpectrumAmplitude.Decibel],
+			mark: [
+				"surface",
+				"ridges",
+				"columns"
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			value: "value",
+			window: SpectrogramWindow.Hann,
+			size: 64,
+			overlap: .75,
+			scale: SpectrumAmplitude.Linear,
+			mark: "surface",
+			xLabel: "cycles / sample",
+			yLabel: "sample"
+		};
+	}
+	field() {
+		const { data, value, size, overlap, window, scale } = this.options;
+		const signal = Array.isArray(data) ? data.map((row) => +(row[value] ?? 0)) : [];
+		if (!signal.length) return SurfaceField.empty();
+		const grid = ShortTimeTransform.spectrogram(signal, size, Math.max(1, Math.round(size * (1 - overlap))), window);
+		const field = SurfaceField.from(grid).capped(96);
+		if (scale !== SpectrumAmplitude.Decibel) return field;
+		const peak = Math.max(field.zMax, 1e-12);
+		return field.map((z) => Math.max(-48, 20 * Math.log10(Math.max(z / peak, 1e-6))));
+	}
+	build(ctx) {
+		const { mark } = this.options;
+		const field = this.field();
+		const space = new SurfaceSpace(field);
+		const [lo, hi] = field.zDomain;
+		const base = this.painter(ctx, [0, 1]);
+		const paint = (value) => base((value - lo) / (hi - lo));
+		this.box(ctx, this.axes(space));
+		const lift = this.rise(ctx);
+		if (mark === "surface") {
+			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));
+			return;
+		}
+		if (mark === "ridges") {
+			const batch = new TubeBatch(.0055);
+			for (let j = 0; j < field.ny; j += 2) batch.add(Array.from({ length: field.nx }, (_, i) => space.at(i, j)), (k) => paint(field.at(k, j)));
+			this.tubes(batch, lift);
+			return;
+		}
+		const stems = new TubeBatch(.0085, 4), stepX = Math.ceil(field.nx / 26), stepY = Math.ceil(field.ny / 26);
+		for (let j = 0; j < field.ny; j += stepY) for (let i = 0; i < field.nx; i += stepX) if (field.at(i, j) > lo + (hi - lo) * .02) stems.add([space.floor(i, j), space.at(i, j)], (k) => paint(k ? field.at(i, j) : lo));
+		this.tubes(stems, lift);
+	}
+};
+export { Spectrogram3DChart, SpectrogramMark, SpectrogramWindow };

package/dist/charts/threesurfaces/SurfaceBase.js

@@ -0,0 +1,333 @@
+import { Chart3D } from "../../core/Chart3D.js";
+import { ColorScale } from "../../core/enums.js";
+import { Scales } from "../../core/Scales.js";
+import { ColorRamp } from "./ColorRamp.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { SurfaceMesh } from "./SurfaceMesh.js";
+import { CEIL, FLOOR } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { scaleLinear } from "d3";
+import { BufferGeometry, DoubleSide, Float32BufferAttribute, Group, InstancedMesh, LineBasicMaterial, LineSegments, Mesh, MeshStandardMaterial, Object3D, PlaneGeometry, ShadowMaterial, SphereGeometry } from "three";
+// src/charts/threesurfaces/SurfaceBase.ts
+/** Marks drawn on top of a surface. */
+var SurfaceOverlay = /* @__PURE__ */ function(SurfaceOverlay) {
+	SurfaceOverlay["None"] = "bare";
+	SurfaceOverlay["Mesh"] = "mesh-lines";
+	SurfaceOverlay["Contours"] = "contour-lines";
+	return SurfaceOverlay;
+}({});
+/** Shadows of the surface cast onto the box around it. */
+var SurfaceProjection = /* @__PURE__ */ function(SurfaceProjection) {
+	SurfaceProjection["None"] = "unprojected";
+	SurfaceProjection["FloorContours"] = "floor-contours";
+	SurfaceProjection["FloorHeatmap"] = "floor-heatmap";
+	SurfaceProjection["Walls"] = "wall-profiles";
+	return SurfaceProjection;
+}({});
+var LINE = .0065;
+/** Stage and shared marks of every surface chart: a matplotlib-style box whose walls stay behind the data, tubes, dots and overlays. */
+var SurfaceBase = class extends Chart3D {
+	defaults() {
+		return {
+			azimuth: 38,
+			elevation: 26,
+			distance: 5.2
+		};
+	}
+	ticks(domain, map, count = 4) {
+		const reach = Math.abs(domain[1] - domain[0]);
+		return scaleLinear(domain, [0, 1]).ticks(count).map((value) => [map(value), Scales.format(value, reach)]);
+	}
+	/** Back walls and floor with gridlines at the ticks. The walls swap sides as the camera orbits, so they never block the data. */
+	box(ctx, { x, y, z }, { walls = true, bottom = FLOOR, outline = true } = {}) {
+		const stage = new Group();
+		const grid = new LineBasicMaterial({ color: ctx.theme.grid }), edge = new LineBasicMaterial({ color: ctx.theme.axis });
+		const lines = (points, material) => {
+			const geometry = new BufferGeometry();
+			geometry.setAttribute("position", new Float32BufferAttribute(points, 3));
+			return new LineSegments(geometry, material);
+		};
+		const top = walls ? Math.max(CEIL, bottom) : bottom;
+		stage.add(lines([...x.flatMap(([at]) => [
+			at,
+			bottom,
+			-1,
+			at,
+			bottom,
+			1
+		]), ...y.flatMap(([at]) => [
+			-1,
+			bottom,
+			at,
+			1,
+			bottom,
+			at
+		])], grid));
+		if (outline) stage.add(lines([
+			-1,
+			bottom,
+			-1,
+			1,
+			bottom,
+			-1,
+			1,
+			bottom,
+			-1,
+			1,
+			bottom,
+			1,
+			1,
+			bottom,
+			1,
+			-1,
+			bottom,
+			1,
+			-1,
+			bottom,
+			1,
+			-1,
+			bottom,
+			-1
+		], edge));
+		const catcher = new Mesh(new PlaneGeometry(2, 2), new ShadowMaterial({ opacity: .16 }));
+		catcher.rotation.x = -Math.PI / 2;
+		catcher.position.y = bottom - .002;
+		catcher.receiveShadow = true;
+		stage.add(catcher);
+		if (walls) {
+			const across = lines([...x.flatMap(([at]) => [
+				at,
+				bottom,
+				-1,
+				at,
+				top,
+				-1
+			]), ...z.flatMap(([at]) => [
+				-1,
+				at,
+				-1,
+				1,
+				at,
+				-1
+			])], grid);
+			const along = lines([...y.flatMap(([at]) => [
+				-1,
+				bottom,
+				at,
+				-1,
+				top,
+				at
+			]), ...z.flatMap(([at]) => [
+				-1,
+				at,
+				-1,
+				-1,
+				at,
+				1
+			])], grid);
+			stage.add(across, along);
+			catcher.onBeforeRender = (_renderer, _scene, camera) => {
+				across.position.z = camera.position.z >= 0 ? 0 : 2;
+				along.position.x = camera.position.x >= 0 ? 0 : 2;
+				across.updateMatrixWorld();
+				along.updateMatrixWorld();
+			};
+		}
+		ctx.root.add(stage);
+		const { xLabel, yLabel, zLabel } = this.options;
+		for (const [at, text] of x) ctx.label(text, [
+			at,
+			bottom - .03,
+			1.12
+		], "muted", 10);
+		for (const [at, text] of y) ctx.label(text, [
+			1.13,
+			bottom - .03,
+			at
+		], "muted", 10);
+		if (walls) for (const [at, text] of z) ctx.label(text, [
+			-1.1,
+			at,
+			1.02
+		], "muted", 10);
+		const longest = Math.max(0, ...y.map(([, text]) => text.length));
+		if (xLabel && x.some(([, text]) => text)) ctx.label(xLabel, [
+			0,
+			bottom - .03,
+			1.5
+		], "secondary", 11);
+		if (yLabel && y.some(([, text]) => text)) ctx.label(yLabel, [
+			1.4 + longest * .04,
+			bottom - .03,
+			0
+		], "secondary", 11);
+		if (zLabel && walls) ctx.label(zLabel, [
+			-1.1,
+			CEIL + .12,
+			1.02
+		], "secondary", 11);
+	}
+	/** Group that grows out of the floor on entry. */
+	rise(ctx, floor = FLOOR) {
+		const group = new Group();
+		ctx.reveal((progress) => {
+			group.scale.y = Math.max(.001, progress);
+			group.position.y = floor * (1 - group.scale.y);
+		}, 1.1);
+		ctx.root.add(group);
+		return group;
+	}
+	/** Group that scales and turns into place, for free-standing shapes. */
+	bloom(ctx) {
+		const group = new Group();
+		ctx.reveal((progress) => {
+			group.scale.setScalar(Math.max(.001, progress));
+			group.rotation.y = (progress - 1) * 1.2;
+		}, 1.3);
+		ctx.root.add(group);
+		return group;
+	}
+	/** Height colour: polarity when the data crosses zero, magnitude otherwise. */
+	painter(ctx, [lo, hi]) {
+		if ((this.options.color ?? (lo < 0 && hi > 0 ? ColorScale.Diverging : ColorScale.Sequential)) === ColorScale.Diverging) {
+			const ramp = new ColorRamp(ctx.palette.diverging, -1, 1), reach = Math.max(Math.abs(lo), Math.abs(hi)) || 1;
+			return (value) => ramp.at(value / reach);
+		}
+		const ramp = new ColorRamp(ctx.palette.sequential);
+		return (value) => ramp.at(.05 + .95 * (value - lo) / (hi - lo || 1));
+	}
+	material(overrides = {}) {
+		return new MeshStandardMaterial({
+			vertexColors: true,
+			side: DoubleSide,
+			roughness: .62,
+			metalness: 0,
+			...overrides
+		});
+	}
+	/** Painted, shadow-casting surface. `pick` receives the nearest vertex. */
+	solid(ctx, geometry, parent, pick, overrides) {
+		const mesh = new SurfaceMesh(geometry, this.material(overrides));
+		mesh.castShadow = true;
+		parent.add(mesh);
+		if (pick) ctx.pick(mesh, pick);
+		return mesh;
+	}
+	/** Draw a tube batch. Pass `color` for a single tone; otherwise the batch's own colours are used. */
+	tubes(batch, parent, color, opacity = 1) {
+		if (batch.empty) return null;
+		const mesh = new Mesh(batch.geometry(), this.material({
+			vertexColors: !color,
+			side: 0,
+			roughness: .5,
+			...color ? { color } : {},
+			transparent: opacity < 1,
+			opacity
+		}));
+		parent.add(mesh);
+		return mesh;
+	}
+	/** Round markers on one instanced mesh; sizes in world units. */
+	dots(ctx, points, radius, paint, parent, pick) {
+		if (!points.length) return null;
+		const mesh = new InstancedMesh(new SphereGeometry(1, 12, 10), new MeshStandardMaterial({ roughness: .45 }), points.length);
+		const dummy = new Object3D();
+		points.forEach((point, k) => {
+			dummy.position.set(...point);
+			dummy.scale.setScalar(typeof radius === "number" ? radius : radius(k));
+			dummy.updateMatrix();
+			mesh.setMatrixAt(k, dummy.matrix);
+			mesh.setColorAt(k, paint(k));
+		});
+		mesh.castShadow = true;
+		parent.add(mesh);
+		if (pick) ctx.pick(mesh, pick);
+		return mesh;
+	}
+	/** Thin surface-coloured lattice that reveals the shape of the mesh without adding a new hue. */
+	meshLines(ctx, space, parent, cells = 12) {
+		const { nx, ny } = space.field;
+		const batch = new TubeBatch(LINE * .7), stepX = Math.max(1, Math.round((nx - 1) / cells)), stepY = Math.max(1, Math.round((ny - 1) / cells));
+		const columns = Array.from({ length: Math.ceil(nx / stepX) }, (_, k) => k * stepX), rows = Array.from({ length: Math.ceil(ny / stepY) }, (_, k) => k * stepY);
+		for (const i of columns) batch.add(Array.from({ length: ny }, (_, j) => space.at(i, j, .003)));
+		for (const j of rows) batch.add(Array.from({ length: nx }, (_, i) => space.at(i, j, .003)));
+		this.tubes(batch, parent, ctx.theme.surface, .8);
+	}
+	thresholds({ zMin, zMax, zDomain }, levels) {
+		if (zMax === zMin) return [zDomain[0]];
+		return Array.from({ length: levels }, (_, k) => zMin + (k + 1) * (zMax - zMin) / (levels + 1));
+	}
+	contourLines(ctx, space, parent, levels = 8) {
+		const batch = new TubeBatch(LINE * .6);
+		for (const { paths } of space.field.lines(this.thresholds(space.field, levels))) for (const path of paths) batch.add(path.map(([i, j]) => space.at(i, j, .004)));
+		this.tubes(batch, parent, ctx.theme.ink, .55);
+	}
+	floorContours(ctx, space, paint, levels = 8) {
+		const batch = new TubeBatch(LINE * .7);
+		for (const { value, paths } of space.field.lines(this.thresholds(space.field, levels))) {
+			const color = paint(value);
+			for (const path of paths) batch.add(path.map(([i, j]) => space.floor(i, j, .006)), color);
+		}
+		this.tubes(batch, ctx.root);
+	}
+	floorHeatmap(ctx, space, paint) {
+		const { field } = space;
+		this.solid(ctx, SurfaceGeometry.grid(field.nx, field.ny, (i, j) => Number.isNaN(field.at(i, j)) ? [
+			NaN,
+			NaN,
+			NaN
+		] : space.floor(i, j, .004), (i, j) => paint(field.at(i, j))), ctx.root).castShadow = false;
+	}
+	/** The surface's upper envelope along each axis, drawn as a silhouette on the back walls. */
+	wallProfiles(ctx, space, paint) {
+		const { field } = space;
+		const envelope = (count, across, read) => Array.from({ length: count }, (_, k) => {
+			let top = -Infinity;
+			for (let c = 0; c < across; c++) {
+				const value = read(k, c);
+				if (value > top) top = value;
+			}
+			return top;
+		});
+		const low = paint(field.zDomain[0]);
+		const wall = (peaks, place) => {
+			const top = peaks.map((peak, k) => place(k, Number.isFinite(peak) ? space.level(peak) : NaN));
+			const batch = new TubeBatch(LINE).add(top, (k) => paint(peaks[k]));
+			this.solid(ctx, SurfaceGeometry.curtain(top, FLOOR, (k) => paint(peaks[k]), () => low), ctx.root, void 0, {
+				transparent: true,
+				opacity: .4,
+				depthWrite: false
+			}).castShadow = false;
+			this.tubes(batch, ctx.root);
+		};
+		wall(envelope(field.nx, field.ny, (i, j) => field.at(i, j)), (i, h) => [
+			space.ground(i, 0)[0],
+			h,
+			-.995
+		]);
+		wall(envelope(field.ny, field.nx, (j, i) => field.at(i, j)), (j, h) => [
+			-.995,
+			h,
+			space.ground(0, j)[1]
+		]);
+	}
+	/** Vertical wall from the surface's boundary to the floor, turning the sheet into a solid. */
+	skirt(ctx, space, paint, parent, sides = [
+		0,
+		1,
+		2,
+		3
+	], closed = false) {
+		const { nx, ny } = space.field;
+		const edges = [
+			Array.from({ length: nx }, (_, i) => [i, 0]),
+			Array.from({ length: ny }, (_, j) => [nx - 1, j]),
+			Array.from({ length: nx }, (_, i) => [i, ny - 1]),
+			Array.from({ length: ny }, (_, j) => [0, j])
+		];
+		const low = paint(space.field.zDomain[0]);
+		const parts = sides.map((side) => closed ? [...edges[side], edges[side][0]] : edges[side]).map((edge) => SurfaceGeometry.curtain(edge.map(([i, j]) => space.at(i, j)), FLOOR, (k) => paint(space.field.at(...edge[k])), () => low));
+		this.solid(ctx, SurfaceGeometry.merge(parts), parent);
+	}
+};
+export { SurfaceBase, SurfaceOverlay, SurfaceProjection };

package/dist/charts/threesurfaces/SurfaceChart.js

@@ -0,0 +1,75 @@
+import { ChartFamily, DataShape, Dimension, ScaleKind } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GridSurfaceBase } from "./GridSurfaceBase.js";
+import { SurfaceOverlay, SurfaceProjection } from "./SurfaceBase.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { SurfaceSpace } from "./SurfaceSpace.js";
+// src/charts/threesurfaces/SurfaceChart.ts
+var SurfaceShading = /* @__PURE__ */ function(SurfaceShading) {
+	SurfaceShading["Smooth"] = "smooth";
+	SurfaceShading["Faceted"] = "faceted";
+	return SurfaceShading;
+}({});
+/** Continuous height field: for reading the overall shape of `z = f(x, y)`, peaks and valleys first. */
+var SurfaceChart = class extends GridSurfaceBase {
+	static meta = {
+		id: "surface-3d",
+		name: "3D surface",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Grid,
+		description: "Draws a shaded height field over an x and y grid, with optional contour, mesh and floor projections.",
+		tags: [
+			"surface",
+			"height field",
+			"plot3d"
+		],
+		sample: (seed) => SampleData.surface(seed, 48),
+		variants: {
+			overlay: [
+				SurfaceOverlay.Mesh,
+				SurfaceOverlay.Contours,
+				SurfaceOverlay.None
+			],
+			projection: [
+				SurfaceProjection.FloorContours,
+				SurfaceProjection.None,
+				SurfaceProjection.FloorHeatmap,
+				SurfaceProjection.Walls
+			],
+			scale: [
+				ScaleKind.Linear,
+				ScaleKind.Sqrt,
+				ScaleKind.Symlog
+			],
+			shading: ["smooth", "faceted"],
+			solidBase: [false, true]
+		},
+		valid: ({ projection, solidBase }) => !(solidBase && projection === SurfaceProjection.FloorHeatmap)
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			overlay: SurfaceOverlay.Mesh,
+			projection: SurfaceProjection.FloorContours,
+			scale: ScaleKind.Linear,
+			shading: "smooth",
+			solidBase: false
+		};
+	}
+	build(ctx) {
+		const { overlay, projection, scale, shading, solidBase } = this.options;
+		const field = this.field();
+		const space = new SurfaceSpace(field, scale);
+		const paint = this.painter(ctx, field.zDomain);
+		this.box(ctx, this.axes(space));
+		const lift = this.rise(ctx);
+		const sheet = SurfaceGeometry.grid(field.nx, field.ny, (i, j) => space.at(i, j), (i, j) => paint(field.at(i, j)));
+		this.solid(ctx, shading === "faceted" ? SurfaceGeometry.faceted(sheet) : sheet, lift, this.gridTip(space));
+		if (solidBase) this.skirt(ctx, space, paint, lift);
+		if (overlay === SurfaceOverlay.Mesh) this.meshLines(ctx, space, lift);
+		if (overlay === SurfaceOverlay.Contours) this.contourLines(ctx, space, lift);
+		this.project(ctx, space, projection, paint);
+	}
+};
+export { SurfaceChart, SurfaceShading };

package/dist/charts/threesurfaces/SurfaceField.js

@@ -0,0 +1,158 @@
+import { contours, extent } from "d3";
+// src/charts/threesurfaces/SurfaceField.ts
+var numeric = (cell) => {
+	if (cell === null || cell === void 0 || cell === "") return NaN;
+	const value = +cell;
+	return Number.isFinite(value) ? value : NaN;
+};
+var catmullRom = (a, b, c, d, t) => b + .5 * t * (c - a + t * (2 * a - 5 * b + 4 * c - d + t * (3 * (b - c) + d - a)));
+/** Scalar field on a rectilinear grid. `NaN` marks a hole. All surface charts read their data through this. */
+var SurfaceField = class SurfaceField {
+	x;
+	y;
+	z;
+	nx;
+	ny;
+	zMin;
+	zMax;
+	constructor(x, y, z) {
+		this.x = x;
+		this.y = y;
+		this.z = z;
+		this.nx = x.length;
+		this.ny = y.length;
+		const [lo, hi] = extent(z);
+		this.zMin = lo ?? 0;
+		this.zMax = hi ?? 1;
+	}
+	static empty() {
+		return new SurfaceField([0, 1], [0, 1], (/* @__PURE__ */ new Float64Array(4)).fill(NaN));
+	}
+	static from(data, columns = {}) {
+		if (Array.isArray(data)) return SurfaceField.pivot(data, columns);
+		if (!data?.x?.length || !data.y?.length || !data.z?.length) return SurfaceField.empty();
+		const z = new Float64Array(data.x.length * data.y.length);
+		data.y.forEach((_, j) => data.x.forEach((_, i) => {
+			z[i + j * data.x.length] = numeric(data.z[j]?.[i]);
+		}));
+		return SurfaceField.widened(data.x.map(Number), data.y.map(Number), z);
+	}
+	/** Long rows to grid: duplicate cells average, missing cells become holes, text axes index by first appearance. */
+	static pivot(rows, { x = "x", y = "y", z = "z" }) {
+		if (!rows.length) return SurfaceField.empty();
+		const axis = (column) => {
+			const seen = [...new Set(rows.map((row) => row[column]))].filter((cell) => cell !== null && cell !== void 0);
+			if (seen.every((cell) => Number.isFinite(numeric(cell)))) return new Map([...new Set(seen.map(numeric))].sort((a, b) => a - b).map((value, i) => [value, i]));
+			return new Map(seen.map((cell, i) => [cell, i]));
+		};
+		const lookup = (map, cell) => map.get(cell) ?? map.get(numeric(cell));
+		const xs = axis(x), ys = axis(y);
+		if (!xs.size || !ys.size) return SurfaceField.empty();
+		const totals = new Float64Array(xs.size * ys.size), counts = new Uint32Array(xs.size * ys.size);
+		for (const row of rows) {
+			const i = lookup(xs, row[x]), j = lookup(ys, row[y]), value = numeric(row[z]);
+			if (i === void 0 || j === void 0 || Number.isNaN(value)) continue;
+			totals[i + j * xs.size] += value;
+			counts[i + j * xs.size]++;
+		}
+		const values = totals.map((total, k) => counts[k] ? total / counts[k] : NaN);
+		const labels = (map) => [...map.keys()].map((key, i) => typeof key === "number" ? key : i);
+		return SurfaceField.widened(labels(xs), labels(ys), values);
+	}
+	/** A single row or column still needs width to make a surface. */
+	static widened(x, y, z) {
+		if (x.length > 1 && y.length > 1) return new SurfaceField(x, y, z);
+		const gx = x.length > 1 ? x : [x[0], x[0] + 1], gy = y.length > 1 ? y : [y[0], y[0] + 1];
+		const out = new Float64Array(gx.length * gy.length);
+		gy.forEach((_, j) => gx.forEach((_, i) => {
+			out[i + j * gx.length] = z[Math.min(i, x.length - 1) + Math.min(j, y.length - 1) * x.length];
+		}));
+		return new SurfaceField(gx, gy, out);
+	}
+	static compute(x, y, fn) {
+		const z = new Float64Array(x.length * y.length);
+		y.forEach((v, j) => x.forEach((u, i) => {
+			const value = fn(u, v);
+			z[i + j * x.length] = Number.isFinite(value) ? value : NaN;
+		}));
+		return new SurfaceField(x, y, z);
+	}
+	get xDomain() {
+		return [this.x[0], this.x[this.nx - 1]];
+	}
+	get yDomain() {
+		return [this.y[0], this.y[this.ny - 1]];
+	}
+	get zDomain() {
+		return this.zMax > this.zMin ? [this.zMin, this.zMax] : [this.zMin - 1, this.zMin + 1];
+	}
+	get hasData() {
+		return this.z.some((value) => !Number.isNaN(value));
+	}
+	at(i, j) {
+		return this.z[Math.max(0, Math.min(this.nx - 1, i)) + Math.max(0, Math.min(this.ny - 1, j)) * this.nx];
+	}
+	/** Bilinear read at fractional indices. A hole with any weight makes the read a hole. */
+	sample(fi, fj) {
+		const i = Math.max(0, Math.min(this.nx - 2, Math.floor(fi))), j = Math.max(0, Math.min(this.ny - 2, Math.floor(fj)));
+		const a = fi - i, b = fj - j;
+		const part = (weight, value) => weight > 0 ? weight * value : 0;
+		return part((1 - a) * (1 - b), this.at(i, j)) + part(a * (1 - b), this.at(i + 1, j)) + part((1 - a) * b, this.at(i, j + 1)) + part(a * b, this.at(i + 1, j + 1));
+	}
+	/** Catmull-Rom read at fractional indices. */
+	cubic(fi, fj) {
+		const i = Math.floor(fi), j = Math.floor(fj);
+		const row = (r) => catmullRom(this.at(i - 1, r), this.at(i, r), this.at(i + 1, r), this.at(i + 2, r), fi - i);
+		return catmullRom(row(j - 1), row(j), row(j + 1), row(j + 2), fj - j);
+	}
+	resample(nx, ny, smooth = false) {
+		const lerp = (axis, t) => {
+			const i = Math.min(axis.length - 2, Math.floor(t));
+			return axis[i] + (axis[i + 1] - axis[i]) * (t - i);
+		};
+		const xs = Array.from({ length: nx }, (_, i) => i * (this.nx - 1) / (nx - 1)), ys = Array.from({ length: ny }, (_, j) => j * (this.ny - 1) / (ny - 1));
+		const z = new Float64Array(nx * ny);
+		ys.forEach((fj, j) => xs.forEach((fi, i) => {
+			z[i + j * nx] = smooth ? this.cubic(fi, fj) : this.sample(fi, fj);
+		}));
+		return new SurfaceField(xs.map((t) => lerp(this.x, t)), ys.map((t) => lerp(this.y, t)), z);
+	}
+	/** Keep vertex counts sane when a user hands in a huge grid. */
+	capped(limit) {
+		return this.nx <= limit && this.ny <= limit ? this : this.resample(Math.min(this.nx, limit), Math.min(this.ny, limit));
+	}
+	map(fn) {
+		const z = this.z.map((value, k) => {
+			const out = fn(value, k % this.nx, Math.floor(k / this.nx));
+			return Number.isFinite(out) ? out : NaN;
+		});
+		return new SurfaceField(this.x, this.y, z);
+	}
+	raw(thresholds) {
+		const clean = this.z.map((value) => Number.isNaN(value) ? -Infinity : value);
+		return contours().size([this.nx, this.ny]).thresholds(thresholds)(Array.from(clean));
+	}
+	toGrid = ([x, y]) => [Math.max(0, Math.min(this.nx - 1, x - .5)), Math.max(0, Math.min(this.ny - 1, y - .5))];
+	/** Filled iso-bands: each polygon is an outer ring followed by its holes. */
+	bands(thresholds) {
+		return this.raw(thresholds).map(({ value, coordinates }) => ({
+			value,
+			polygons: coordinates.map((polygon) => polygon.map((ring) => ring.map(this.toGrid)))
+		}));
+	}
+	/** Iso-lines with the grid border removed, so a contour ends at the edge rather than running along it. */
+	lines(thresholds) {
+		const edge = ([x, y]) => x <= 0 || y <= 0 || x >= this.nx || y >= this.ny;
+		return this.raw(thresholds).map(({ value, coordinates }) => ({
+			value,
+			paths: coordinates.flat().flatMap((ring) => {
+				const paths = [[]];
+				for (const point of ring) if (edge(point)) {
+					if (paths.at(-1).length) paths.push([]);
+				} else paths.at(-1).push(this.toGrid(point));
+				return paths.filter((path) => path.length > 1);
+			})
+		}));
+	}
+};
+export { SurfaceField };