@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/threevolume/Streamline3DChart.js

@@ -0,0 +1,106 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FieldDerivation, StrandStyle, StreamDirection, Streamline3DSeeding } from "./volumeEnums.js";
+import { VectorField3DChart } from "./VectorField3DChart.js";
+import { RIBBON_SECTION, ROUND_SECTION, THIN_SECTION, VolumeStrands } from "./VolumeStrands.js";
+import { Mesh } from "three";
+// src/charts/threevolume/Streamline3DChart.ts
+/** Curves tangent to a vector field: for seeing how flow connects regions, as in airflow or magnetic field lines. */
+var Streamline3DChart = class extends VectorField3DChart {
+	static meta = {
+		id: "streamline-3d",
+		name: "3D streamlines",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Volume,
+		description: "Integrates seed points through a vector field into tubes or ribbons tangent to the flow.",
+		tags: [
+			"streamtube",
+			"flow",
+			"field lines",
+			"cfd",
+			"stream ribbon"
+		],
+		sample: VectorField3DChart.sampleField,
+		variants: {
+			seeding: Object.values(Streamline3DSeeding),
+			direction: Object.values(StreamDirection),
+			style: Object.values(StrandStyle),
+			derivation: Object.values(FieldDerivation)
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			seeding: Streamline3DSeeding.Lattice,
+			direction: StreamDirection.Both,
+			style: StrandStyle.Tube,
+			lines: 48,
+			steps: 90
+		};
+	}
+	seeds([hx, hy, hz]) {
+		const { seeding, lines } = this.options;
+		const count = Math.max(1, Math.floor(lines));
+		const next = this.random();
+		const side = Math.ceil(Math.cbrt(count));
+		if (seeding === Streamline3DSeeding.Scatter) return Array.from({ length: count }, () => [
+			(next() * 2 - 1) * hx * .9,
+			(next() * 2 - 1) * hy * .9,
+			(next() * 2 - 1) * hz * .9
+		]);
+		if (seeding === Streamline3DSeeding.Sphere) return Array.from({ length: count }, (_, i) => {
+			const y = 1 - 2 * (i + .5) / count, ring = Math.sqrt(1 - y * y), angle = i * 2.39996;
+			return [
+				hx * .55 * ring * Math.cos(angle),
+				hy * .55 * y,
+				hz * .55 * ring * Math.sin(angle)
+			];
+		});
+		if (seeding === Streamline3DSeeding.Plane) {
+			const row = Math.ceil(Math.sqrt(count));
+			return Array.from({ length: row * row }, (_, i) => [
+				((i % row + .5) / row * 2 - 1) * hx * .9,
+				-hy * .7,
+				((Math.floor(i / row) + .5) / row * 2 - 1) * hz * .9
+			]);
+		}
+		return Array.from({ length: side ** 3 }, (_, i) => [
+			((i % side + .5) / side * 2 - 1) * hx * .8,
+			((Math.floor(i / side) % side + .5) / side * 2 - 1) * hy * .8,
+			((Math.floor(i / side / side) + .5) / side * 2 - 1) * hz * .8
+		]);
+	}
+	build(ctx) {
+		const { direction, style, steps } = this.options;
+		const field = this.field;
+		this.stage(ctx);
+		if (field.empty) return;
+		const tone = this.speedTone(ctx, field);
+		const strands = new VolumeStrands(style === StrandStyle.Ribbon ? RIBBON_SECTION : style === StrandStyle.Thread ? THIN_SECTION : ROUND_SECTION);
+		const width = style === StrandStyle.Ribbon ? .026 : style === StrandStyle.Thread ? .005 : .0105;
+		let drawn = 0;
+		for (const seed of this.seeds(field.half)) {
+			const path = field.trace(seed, steps, .022, direction);
+			if (path.length < 6) continue;
+			drawn++;
+			const speed = path.map((p) => field.speed(...p));
+			strands.add(path, {
+				radius: (i, f) => width * Math.min(1, Math.min(f, 1 - f) * 8 + .15) * (style === StrandStyle.Thread ? 1 : .65 + Math.sqrt(speed[i] / field.peak)),
+				color: (i) => tone(speed[i])
+			});
+		}
+		const geometry = strands.build();
+		const mesh = new Mesh(geometry, this.surface({
+			vertexColors: true,
+			roughness: .45
+		}));
+		mesh.castShadow = true;
+		ctx.root.add(mesh);
+		ctx.pick(mesh, () => ({
+			title: "Streamlines",
+			rows: [["Lines", drawn], ["Peak speed", +field.peak.toFixed(3)]]
+		}));
+		this.drawOn(ctx, geometry);
+	}
+};
+export { Streamline3DChart };

package/dist/charts/threevolume/TubeTrajectoryChart.js

@@ -0,0 +1,156 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { PointRowsChart, numeric } from "./PointRowsChart.js";
+import { TubeCurve, TubeMarkers, TubeWidth } from "./volumeEnums.js";
+import { RIBBON_SECTION, ROUND_SECTION, VolumeStrands } from "./VolumeStrands.js";
+import { group } from "d3";
+import { CatmullRomCurve3, IcosahedronGeometry, InstancedMesh, Mesh, Vector3 } from "three";
+// src/charts/threevolume/TubeTrajectoryChart.ts
+var FLOOR = -.992;
+/** Ordered 3D paths: for routes and state-space trajectories where the sequence of positions is the story. */
+var TubeTrajectoryChart = class extends PointRowsChart {
+	static meta = {
+		id: "tube-trajectory",
+		name: "Tube trajectory",
+		family: ChartFamily.Temporal,
+		dimension: Dimension.Three,
+		shape: DataShape.Table,
+		description: "Sweeps ordered rows into 3D tubes, one per group, so paths through space can be followed and compared.",
+		tags: [
+			"path",
+			"route",
+			"phase portrait",
+			"tube",
+			"flight path"
+		],
+		sample: (seed) => {
+			const walk = (shift) => SampleData.timeSeries(seed + shift, 180, 3).map((row, i, all) => {
+				const near = all.slice(Math.max(0, i - 9), i + 10).filter((other) => other.series === row.series);
+				return {
+					...row,
+					value: near.reduce((sum, other) => sum + +other.value, 0) / near.length
+				};
+			}).filter((_, i) => i % 3 === 0);
+			const [ys, zs] = [walk(5), walk(9)];
+			return walk(0).map((row, i) => ({
+				date: row.date,
+				group: row.series,
+				x: row.value,
+				y: ys[i].value,
+				z: zs[i].value
+			}));
+		},
+		variants: {
+			curve: Object.values(TubeCurve),
+			sizing: Object.values(TubeWidth),
+			ribbon: [false, true],
+			markers: Object.values(TubeMarkers),
+			shadow: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			curve: TubeCurve.CatmullRom,
+			sizing: TubeWidth.Constant,
+			ribbon: false,
+			markers: TubeMarkers.Ends,
+			shadow: true,
+			radius: .017
+		};
+	}
+	sorted(rows) {
+		const { order } = this.options;
+		if (!order) return rows;
+		const key = (cell) => numeric(cell);
+		return [...rows].sort((a, b) => key(a[order]) - key(b[order]));
+	}
+	smooth(points) {
+		const { curve } = this.options;
+		if (curve === TubeCurve.Polyline || points.length < 3) return points;
+		const type = curve === TubeCurve.Centripetal ? "centripetal" : "catmullrom";
+		return new CatmullRomCurve3(points, false, type, .5).getPoints(points.length * 5);
+	}
+	build(ctx) {
+		const { group: group$1, sizing, ribbon, markers, shadow, radius, x, y, z } = this.options;
+		const clean = this.rows();
+		this.rowStage(ctx, clean);
+		if (!clean.length) return;
+		const ux = this.unit(clean.map((row) => row.x)), uy = this.unit(clean.map((row) => row.y)), uz = this.unit(clean.map((row) => row.z));
+		const fit = (row) => new Vector3(ux(numeric(row[x])) * 1.8 - .9, uy(numeric(row[y])) * 1.8 - .9, uz(numeric(row[z])) * 1.8 - .9);
+		const paths = [...group(clean.map((point) => point.row), (row) => String(row[group$1] ?? "All"))];
+		const beads = [];
+		paths.forEach(([name, rows]) => {
+			const points = this.sorted(rows).map(fit);
+			const curve = this.smooth(points);
+			const color = ctx.color(ctx.palette.color(name));
+			const speeds = curve.map((point, i) => point.distanceTo(curve[Math.min(curve.length - 1, i + 1)]));
+			const peak = Math.max(...speeds, 1e-6);
+			const eased = speeds.map((_, i) => {
+				const near = speeds.slice(Math.max(0, i - 6), i + 7);
+				return near.reduce((a, b) => a + b, 0) / near.length;
+			});
+			const geometry = new VolumeStrands(ribbon ? RIBBON_SECTION : ROUND_SECTION).add(curve.map((p) => p.toArray()), {
+				radius: (i, f) => radius * (ribbon ? 2.6 : 1) * (sizing === TubeWidth.Speed ? .3 + 1.1 * eased[i] / peak : sizing === TubeWidth.Taper ? .2 + 1.1 * f : 1),
+				color: () => color
+			}).build();
+			const mesh = new Mesh(geometry, this.surface({
+				vertexColors: true,
+				roughness: .38
+			}));
+			mesh.castShadow = true;
+			ctx.root.add(mesh);
+			ctx.pick(mesh, () => ({
+				title: name,
+				color: ctx.palette.color(name),
+				rows: [["Points", points.length]]
+			}));
+			this.drawOn(ctx, geometry);
+			if (shadow) {
+				const floor = new VolumeStrands(RIBBON_SECTION).add(curve.map((p) => [
+					p.x,
+					FLOOR,
+					p.z
+				]), {
+					radius: () => radius * .5,
+					color: () => ctx.color(ctx.theme.axis)
+				}).build();
+				ctx.root.add(new Mesh(floor, this.surface({
+					vertexColors: true,
+					roughness: 1
+				})));
+				this.drawOn(ctx, floor);
+			}
+			if (markers === TubeMarkers.Ends && points.length > 1) beads.push({
+				point: points[0],
+				name,
+				size: .8
+			}, {
+				point: points.at(-1),
+				name,
+				size: 1.5
+			});
+			if (markers === TubeMarkers.Beads) points.forEach((point, i) => {
+				if (i % 5 === 0) beads.push({
+					point,
+					name,
+					size: 1
+				});
+			});
+		});
+		if (!beads.length) return;
+		const dots = new InstancedMesh(new IcosahedronGeometry(1, 2), this.surface({ roughness: .3 }), beads.length);
+		dots.castShadow = true;
+		beads.forEach((bead, i) => dots.setColorAt(i, ctx.color(ctx.palette.color(bead.name))));
+		this.populate(ctx, dots, (i, dummy) => {
+			dummy.position.copy(beads[i].point);
+			dummy.scale.setScalar(radius * 1.5 * beads[i].size);
+		}, (i) => i / beads.length);
+		ctx.root.add(dots);
+		ctx.pick(dots, (i) => ({
+			title: beads[i].name,
+			color: ctx.palette.color(beads[i].name)
+		}));
+	}
+};
+export { TubeTrajectoryChart };

package/dist/charts/threevolume/Vector3DField.js

@@ -0,0 +1,109 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { FieldDerivation, Vector3DGlyph, Vector3DLattice, Vector3DLength } from "./volumeEnums.js";
+import { VectorField3DChart } from "./VectorField3DChart.js";
+import { CircleGeometry, ConeGeometry, CylinderGeometry, InstancedMesh, Quaternion, Vector3 } from "three";
+import { mergeGeometries } from "three/addons/utils/BufferGeometryUtils.js";
+// src/charts/threevolume/Vector3DField.ts
+var UP = new Vector3(0, 1, 0);
+/** A glyph at every lattice point: for reading direction and strength of a 3D field at a glance, as in wind or magnetic data. */
+var Vector3DField = class extends VectorField3DChart {
+	static meta = {
+		id: "vector-field-3d",
+		name: "3D vector field",
+		family: ChartFamily.Scientific,
+		dimension: Dimension.Three,
+		shape: DataShape.Volume,
+		description: "Places oriented glyphs through a volume to show the direction and strength of a vector field.",
+		tags: [
+			"quiver",
+			"cone plot",
+			"wind",
+			"gradient",
+			"hedgehog"
+		],
+		sample: VectorField3DChart.sampleField,
+		variants: {
+			glyph: Object.values(Vector3DGlyph),
+			lattice: Object.values(Vector3DLattice),
+			length: Object.values(Vector3DLength),
+			derivation: Object.values(FieldDerivation)
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			glyph: Vector3DGlyph.Arrow,
+			lattice: Vector3DLattice.Cube,
+			length: Vector3DLength.Magnitude,
+			density: 9
+		};
+	}
+	shape() {
+		const { glyph } = this.options;
+		if (glyph === Vector3DGlyph.Cone) return new ConeGeometry(.3, 1, 10);
+		if (glyph === Vector3DGlyph.Plate) return new CircleGeometry(.42, 18).rotateX(-Math.PI / 2);
+		return mergeGeometries([new CylinderGeometry(.07, .07, .62, 8).translate(0, -.19, 0), new ConeGeometry(.2, .38, 12).translate(0, .31, 0)]);
+	}
+	anchors([hx, hy, hz]) {
+		const { lattice, density } = this.options;
+		const n = Math.max(2, Math.floor(density));
+		const line = (half, count, shift = 0) => Array.from({ length: count }, (_, i) => ((i + shift) / (count - 1 || 1) * 2 - 1) * half);
+		const grid = (shift, count = n) => line(hx, count, shift).flatMap((x) => line(hy, count, shift).flatMap((y) => line(hz, count, shift).map((z) => [
+			x,
+			y,
+			z
+		])));
+		if (lattice === Vector3DLattice.Staggered) return [...grid(0, n - 2), ...grid(.5, n - 2).filter(([x, y, z]) => Math.abs(x) <= hx && Math.abs(y) <= hy && Math.abs(z) <= hz)];
+		if (lattice === Vector3DLattice.Plane) return line(hx, n * 3).flatMap((x) => line(hz, n * 3).map((z) => [
+			x,
+			0,
+			z
+		]));
+		if (lattice === Vector3DLattice.Shell) {
+			const count = n * n * 6;
+			return Array.from({ length: count }, (_, i) => {
+				const y = 1 - 2 * (i + .5) / count, ring = Math.sqrt(1 - y * y), angle = i * 2.39996;
+				return [
+					hx * .8 * ring * Math.cos(angle),
+					hy * .8 * y,
+					hz * .8 * ring * Math.sin(angle)
+				];
+			});
+		}
+		return grid(0);
+	}
+	build(ctx) {
+		const { length, density } = this.options;
+		const field = this.field;
+		this.stage(ctx);
+		if (field.empty) return;
+		const glyphs = this.anchors(field.half).flatMap((point) => {
+			const vector = field.at(...point);
+			const speed = vector ? Math.hypot(...vector) : 0;
+			return vector && speed > field.peak * .015 ? [{
+				point,
+				vector,
+				speed
+			}] : [];
+		});
+		const mesh = new InstancedMesh(this.shape(), this.surface({ roughness: .5 }), glyphs.length);
+		mesh.castShadow = true;
+		const tone = this.speedTone(ctx, field);
+		glyphs.forEach((glyph, i) => mesh.setColorAt(i, tone(glyph.speed)));
+		const unit = 1.5 / Math.max(2, Math.floor(density));
+		const spin = new Quaternion(), heading = new Vector3();
+		this.populate(ctx, mesh, (i, dummy) => {
+			const { point, vector, speed } = glyphs[i];
+			dummy.position.set(...point);
+			dummy.quaternion.copy(spin.setFromUnitVectors(UP, heading.set(...vector).normalize()));
+			const size = length === Vector3DLength.Magnitude ? Math.max(.12, speed / field.peak) : .65;
+			dummy.scale.set(unit * .8, unit * size * 1.1, unit * .8);
+		}, (i) => i / glyphs.length);
+		ctx.root.add(mesh);
+		ctx.pick(mesh, (i) => ({
+			title: "Vector",
+			rows: [["Speed", +glyphs[i].speed.toFixed(3)], ["At", glyphs[i].point.map((v) => v.toFixed(2)).join(", ")]]
+		}));
+	}
+};
+export { Vector3DField };

package/dist/charts/threevolume/VectorField3D.js

@@ -0,0 +1,117 @@
+import { FieldDerivation, StreamDirection } from "./volumeEnums.js";
+import { VolumeGrid } from "./VolumeGrid.js";
+// src/charts/threevolume/VectorField3D.ts
+var isVector = (data) => !!data && "u" in data;
+/** Sampled 3D vector field with trilinear lookup and fixed-arc RK4 streamline tracing. */
+var VectorField3D = class VectorField3D {
+	u;
+	v;
+	w;
+	/** Largest speed in the field. */
+	peak;
+	constructor(u, v, w) {
+		this.u = u;
+		this.v = v;
+		this.w = w;
+		let peak = 0;
+		u.values.forEach((value, i) => {
+			peak = Math.max(peak, Math.hypot(value, v.values[i], w.values[i]));
+		});
+		this.peak = peak || 1;
+	}
+	get half() {
+		return this.u.half;
+	}
+	get empty() {
+		return this.u.empty;
+	}
+	/** Real vectors are used as given; a scalar volume is treated as a potential and differentiated with `derivation`. */
+	static from(data, derivation) {
+		if (isVector(data)) return new VectorField3D(new VolumeGrid(data.size, data.u), new VolumeGrid(data.size, data.v), new VolumeGrid(data.size, data.w));
+		const grid = VolumeGrid.from(data);
+		const { nx, ny, nz } = grid, cells = nx * ny * nz;
+		const u = new Float32Array(cells), v = new Float32Array(cells), w = new Float32Array(cells);
+		for (let k = 0; k < nz; k++) for (let j = 0; j < ny; j++) for (let i = 0; i < nx; i++) {
+			const dx = grid.at(i + 1, j, k) - grid.at(i - 1, j, k), dy = grid.at(i, j + 1, k) - grid.at(i, j - 1, k), dz = grid.at(i, j, k + 1) - grid.at(i, j, k - 1);
+			const cell = grid.index(i, j, k), rx = grid.worldAxis(0, i), ry = grid.worldAxis(1, j), rz = grid.worldAxis(2, k);
+			if (derivation === FieldDerivation.Gradient) {
+				u[cell] = dx;
+				v[cell] = dy;
+				w[cell] = dz;
+			} else if (derivation === FieldDerivation.Curl) {
+				u[cell] = -dz;
+				v[cell] = .25 * dx * dz;
+				w[cell] = dx;
+			} else {
+				u[cell] = -dz + .5 * dx - .06 * rz;
+				v[cell] = .5 * dy + .05 * (1 - ry * ry);
+				w[cell] = dx + .5 * dz + .06 * rx;
+			}
+		}
+		const size = [
+			nx,
+			ny,
+			nz
+		];
+		return new VectorField3D(new VolumeGrid(size, u), new VolumeGrid(size, v), new VolumeGrid(size, w));
+	}
+	/** Vector at a world position; `null` outside the volume. */
+	at(x, y, z) {
+		const a = this.u.sample(x, y, z);
+		return a === null ? null : [
+			a,
+			this.v.sample(x, y, z),
+			this.w.sample(x, y, z)
+		];
+	}
+	speed(x, y, z) {
+		const vector = this.at(x, y, z);
+		return vector ? Math.hypot(...vector) : 0;
+	}
+	step(from, h) {
+		const direction = (p) => {
+			const vector = this.at(...p);
+			if (!vector) return null;
+			const speed = Math.hypot(...vector);
+			return speed < this.peak * .001 ? null : [
+				vector[0] / speed,
+				vector[1] / speed,
+				vector[2] / speed
+			];
+		};
+		const shift = (d, scale) => [
+			from[0] + d[0] * scale,
+			from[1] + d[1] * scale,
+			from[2] + d[2] * scale
+		];
+		const a = direction(from);
+		const b = a && direction(shift(a, h / 2));
+		const c = b && direction(shift(b, h / 2));
+		const d = c && direction(shift(c, h));
+		if (!a || !b || !c || !d) return null;
+		return [
+			from[0] + h / 6 * (a[0] + 2 * b[0] + 2 * c[0] + d[0]),
+			from[1] + h / 6 * (a[1] + 2 * b[1] + 2 * c[1] + d[1]),
+			from[2] + h / 6 * (a[2] + 2 * b[2] + 2 * c[2] + d[2])
+		];
+	}
+	/** Follows the field from `seed` for up to `steps` equal-length steps, stopping at stagnation or the boundary. */
+	trace(seed, steps, h, direction = StreamDirection.Forward) {
+		const walk = (sign) => {
+			const path = [];
+			let point = seed;
+			for (let i = 0; i < steps; i++) {
+				point = this.step(point, h * sign);
+				if (!point) break;
+				path.push(point);
+			}
+			return path;
+		};
+		return direction === StreamDirection.Both ? [
+			...walk(-1).reverse(),
+			seed,
+			...walk(1)
+		] : [seed, ...walk(1)];
+	}
+};
+export { VectorField3D };

package/dist/charts/threevolume/VectorField3DChart.js

@@ -0,0 +1,27 @@
+import { SampleData } from "../../data/SampleData.js";
+import { FieldDerivation } from "./volumeEnums.js";
+import { VectorField3D } from "./VectorField3D.js";
+import { VolumeScene } from "./VolumeScene.js";
+import { randomLcg } from "d3";
+// src/charts/threevolume/VectorField3DChart.ts
+/** Base for charts of a 3D vector field: accepts `{ size, u, v, w }`, or a scalar potential to differentiate. */
+var VectorField3DChart = class extends VolumeScene {
+	static sampleField(seed) {
+		return SampleData.volume(seed, 20);
+	}
+	defaults() {
+		return { derivation: FieldDerivation.Swirl };
+	}
+	get field() {
+		return VectorField3D.from(this.options.data, this.options.derivation);
+	}
+	speedTone(ctx, field) {
+		const tone = this.sequential(ctx);
+		return (speed) => tone((speed / field.peak) ** .8);
+	}
+	/** Repeatable uniform numbers, so the same data always draws the same picture. */
+	random(seed = .37) {
+		return randomLcg(seed);
+	}
+};
+export { VectorField3DChart };

package/dist/charts/threevolume/VolumeGrid.js

@@ -0,0 +1,176 @@
+import { IsoThreshold, VolumeAggregate, VolumeCut } from "./volumeEnums.js";
+// src/charts/threevolume/VolumeGrid.ts
+/** Clean scalar volume: non-finite cells become the minimum, world coordinates preserve the aspect ratio inside ±0.9. */
+var VolumeGrid = class VolumeGrid {
+	nx;
+	ny;
+	nz;
+	values;
+	min;
+	max;
+	/** World half-extent on each axis. */
+	half;
+	constructor(size, values) {
+		const [nx, ny, nz] = size.map((n) => Math.max(0, Math.floor(n) || 0));
+		this.nx = nx;
+		this.ny = ny;
+		this.nz = nz;
+		const cells = new Float32Array(nx * ny * nz);
+		let min = Infinity, max = -Infinity;
+		for (let i = 0; i < cells.length; i++) {
+			const value = i < values.length && values[i] != null ? Number(values[i]) : NaN;
+			cells[i] = value;
+			if (value < min) min = value;
+			if (value > max) max = value;
+		}
+		if (min > max) min = max = 0;
+		for (let i = 0; i < cells.length; i++) if (!Number.isFinite(cells[i])) cells[i] = min;
+		this.values = cells;
+		this.min = min;
+		this.max = max;
+		const longest = Math.max(nx, ny, nz, 1);
+		this.half = [
+			.9 * nx / longest,
+			.9 * ny / longest,
+			.9 * nz / longest
+		];
+	}
+	static from(data) {
+		return new VolumeGrid(data?.size ?? [
+			0,
+			0,
+			0
+		], data?.values ?? []);
+	}
+	get empty() {
+		return this.values.length === 0;
+	}
+	get span() {
+		return this.max - this.min || 1;
+	}
+	/** Magnitude in 0..1. */
+	unit(value) {
+		return (value - this.min) / this.span;
+	}
+	index(i, j, k) {
+		return i + j * this.nx + k * this.nx * this.ny;
+	}
+	at(i, j, k) {
+		return this.values[this.index(Math.max(0, Math.min(this.nx - 1, i)), Math.max(0, Math.min(this.ny - 1, j)), Math.max(0, Math.min(this.nz - 1, k)))] ?? this.min;
+	}
+	/** Grid coordinate on one axis to world. */
+	worldAxis(axis, value) {
+		const n = [
+			this.nx,
+			this.ny,
+			this.nz
+		][axis];
+		return n > 1 ? (value / (n - 1) * 2 - 1) * this.half[axis] : 0;
+	}
+	/** World coordinate on one axis to grid. */
+	gridAxis(axis, value) {
+		const n = [
+			this.nx,
+			this.ny,
+			this.nz
+		][axis];
+		return n > 1 ? (value / (this.half[axis] || 1) + 1) / 2 * (n - 1) : 0;
+	}
+	/** Trilinear lookup in grid coordinates, clamped to the volume. */
+	lerp(x, y, z) {
+		const fx = Math.max(0, Math.min(this.nx - 1, x)), fy = Math.max(0, Math.min(this.ny - 1, y)), fz = Math.max(0, Math.min(this.nz - 1, z));
+		const i = Math.floor(fx), j = Math.floor(fy), k = Math.floor(fz);
+		const a = fx - i, b = fy - j, c = fz - k;
+		const edge = (jj, kk) => this.at(i, jj, kk) * (1 - a) + this.at(i + 1, jj, kk) * a;
+		const face = (kk) => edge(j, kk) * (1 - b) + edge(j + 1, kk) * b;
+		return face(k) * (1 - c) + face(k + 1) * c;
+	}
+	/** Trilinear lookup in world coordinates; `null` outside the volume. */
+	sample(x, y, z) {
+		if (this.empty || Math.abs(x) > this.half[0] + 1e-6 || Math.abs(y) > this.half[1] + 1e-6 || Math.abs(z) > this.half[2] + 1e-6) return null;
+		return this.lerp(this.gridAxis(0, x), this.gridAxis(1, y), this.gridAxis(2, z));
+	}
+	/** Grid index of the largest value. */
+	peak() {
+		let best = 0;
+		this.values.forEach((value, i) => {
+			if (value > this.values[best]) best = i;
+		});
+		return [
+			best % this.nx || 0,
+			Math.floor(best / this.nx) % this.ny || 0,
+			Math.floor(best / (this.nx * this.ny)) || 0
+		];
+	}
+	/** Same volume with every cell in the removed region set to the minimum. */
+	masked(cut) {
+		if (cut === VolumeCut.None) return this;
+		const values = this.values.slice();
+		const removed = (i, j, k) => {
+			const xCut = i >= this.nx / 2, zCut = k >= this.nz / 2;
+			return cut === VolumeCut.HalfX ? xCut : cut === VolumeCut.HalfZ ? zCut : xCut && zCut && j >= this.ny / 2;
+		};
+		for (let k = 0; k < this.nz; k++) for (let j = 0; j < this.ny; j++) for (let i = 0; i < this.nx; i++) if (removed(i, j, k)) values[this.index(i, j, k)] = this.min;
+		return new VolumeGrid([
+			this.nx,
+			this.ny,
+			this.nz
+		], values);
+	}
+	/** Smaller volume in which each `bin³` block is aggregated into one cell. */
+	coarsen(bin, aggregate) {
+		if (bin <= 1) return this;
+		const size = [
+			Math.ceil(this.nx / bin),
+			Math.ceil(this.ny / bin),
+			Math.ceil(this.nz / bin)
+		];
+		const out = new Float32Array(size[0] * size[1] * size[2]);
+		const count = new Uint32Array(out.length);
+		const merge = aggregate === VolumeAggregate.Max ? Math.max : aggregate === VolumeAggregate.Min ? Math.min : (a, b) => a + b;
+		for (let k = 0; k < this.nz; k++) for (let j = 0; j < this.ny; j++) for (let i = 0; i < this.nx; i++) {
+			const cell = (i / bin | 0) + (j / bin | 0) * size[0] + (k / bin | 0) * size[0] * size[1];
+			const value = this.values[this.index(i, j, k)];
+			out[cell] = count[cell]++ ? merge(out[cell], value) : value;
+		}
+		if (aggregate === VolumeAggregate.Mean) out.forEach((value, i) => {
+			out[i] = value / (count[i] || 1);
+		});
+		return new VolumeGrid(size, out);
+	}
+	/** Automatic level between the minimum and maximum. */
+	threshold(method) {
+		if (this.empty) return 0;
+		if (method === IsoThreshold.Midrange) return (this.min + this.max) / 2;
+		let sum = 0, square = 0;
+		for (const value of this.values) {
+			sum += value;
+			square += value * value;
+		}
+		const n = this.values.length, mean = sum / n;
+		if (method === IsoThreshold.MeanSigma) return Math.min(this.max - .02 * this.span, mean + Math.sqrt(Math.max(0, square / n - mean * mean)));
+		return this.otsu();
+	}
+	/** Level maximising between-class variance of a 64-bin histogram. */
+	otsu() {
+		const bins = 64, histogram = new Float64Array(bins);
+		for (const value of this.values) histogram[Math.min(63, Math.floor(this.unit(value) * bins))]++;
+		const total = this.values.length;
+		const sum = histogram.reduce((all, count, i) => all + count * i, 0);
+		let below = 0, belowSum = 0, best = 0, level = bins / 2;
+		for (let i = 0; i < bins; i++) {
+			below += histogram[i];
+			belowSum += histogram[i] * i;
+			const above = total - below;
+			if (!below || !above) continue;
+			const gap = belowSum / below - (sum - belowSum) / above;
+			const score = below * above * gap * gap;
+			if (score > best) {
+				best = score;
+				level = i + 1;
+			}
+		}
+		return this.min + level / bins * this.span;
+	}
+};
+export { VolumeGrid };