@mstone6969/graph 0.0.0-stage → 0.1.0

package/dist/charts/threesurfaces/ParametricForms.js

@@ -0,0 +1,173 @@
+// src/charts/threesurfaces/ParametricForms.ts
+var ParametricSurfaceForm = /* @__PURE__ */ function(ParametricSurfaceForm) {
+	ParametricSurfaceForm["Torus"] = "torus";
+	ParametricSurfaceForm["Mobius"] = "mobius";
+	ParametricSurfaceForm["Klein"] = "klein-bottle";
+	ParametricSurfaceForm["KleinFigureEight"] = "klein-figure-eight";
+	ParametricSurfaceForm["Sphere"] = "sphere";
+	ParametricSurfaceForm["Trefoil"] = "trefoil-knot";
+	ParametricSurfaceForm["Seashell"] = "seashell";
+	ParametricSurfaceForm["Boy"] = "boy-surface";
+	ParametricSurfaceForm["Enneper"] = "enneper";
+	ParametricSurfaceForm["Helicoid"] = "helicoid";
+	ParametricSurfaceForm["Catenoid"] = "catenoid";
+	ParametricSurfaceForm["Dini"] = "dini";
+	return ParametricSurfaceForm;
+}({});
+var { sin, cos, cosh, tan, log, PI, sqrt } = Math;
+var TAU = PI * 2;
+var unit = (v) => {
+	const length = Math.hypot(...v) || 1;
+	return [
+		v[0] / length,
+		v[1] / length,
+		v[2] / length
+	];
+};
+/** Closed-form parametrisations, y up. `ParametricSurface` rescales each to fit the stage. */
+var PARAMETRIC_FORMS = {
+	["torus"]: {
+		u: [0, TAU],
+		v: [0, TAU],
+		point: (u, v) => [
+			(1 + .42 * cos(v)) * cos(u),
+			.42 * sin(v),
+			(1 + .42 * cos(v)) * sin(u)
+		]
+	},
+	["mobius"]: {
+		u: [0, TAU],
+		v: [-.5, .5],
+		point: (u, v) => [
+			(1 + v * cos(u / 2)) * cos(u),
+			v * sin(u / 2),
+			(1 + v * cos(u / 2)) * sin(u)
+		]
+	},
+	["klein-bottle"]: {
+		u: [0, PI * 2],
+		v: [0, TAU],
+		point: (u, v) => {
+			const r = 4 * (1 - cos(u) / 2);
+			return [
+				u < PI ? 6 * cos(u) * (1 + sin(u)) + r * cos(u) * cos(v) : 6 * cos(u) * (1 + sin(u)) + r * cos(v + PI),
+				-(u < PI ? 16 * sin(u) + r * sin(u) * cos(v) : 16 * sin(u)),
+				r * sin(v)
+			];
+		}
+	},
+	["klein-figure-eight"]: {
+		u: [0, TAU],
+		v: [0, TAU],
+		point: (u, v) => {
+			const r = 1.6 + cos(u / 2) * sin(v) - sin(u / 2) * sin(2 * v);
+			return [
+				r * cos(u),
+				sin(u / 2) * sin(v) + cos(u / 2) * sin(2 * v),
+				r * sin(u)
+			];
+		}
+	},
+	["sphere"]: {
+		u: [0, TAU],
+		v: [.001, PI - .001],
+		point: (u, v) => [
+			sin(v) * cos(u),
+			cos(v),
+			sin(v) * sin(u)
+		]
+	},
+	["trefoil-knot"]: {
+		u: [0, TAU],
+		v: [0, TAU],
+		point: (u, v) => {
+			const curve = (t) => [
+				sin(t) + 2 * sin(2 * t),
+				-sin(3 * t),
+				cos(t) - 2 * cos(2 * t)
+			];
+			const c = curve(u), ahead = curve(u + .001);
+			const t = unit([
+				ahead[0] - c[0],
+				ahead[1] - c[1],
+				ahead[2] - c[2]
+			]);
+			const n = unit([
+				-t[2],
+				0,
+				t[0]
+			]);
+			const b = [
+				t[1] * n[2],
+				t[2] * n[0] - t[0] * n[2],
+				-t[1] * n[0]
+			];
+			return [
+				0,
+				1,
+				2
+			].map((k) => c[k] + .42 * (cos(v) * n[k] + sin(v) * b[k]));
+		}
+	},
+	["seashell"]: {
+		u: [0, 6 * PI],
+		v: [0, TAU],
+		point: (u, v) => {
+			const growth = 2 ** (u / TAU) * .15, r = growth * (1 + cos(v));
+			return [
+				r * cos(u),
+				growth * (sin(v) + 1) * 1.1 - 2 ** (u / TAU) * .9,
+				r * sin(u)
+			];
+		}
+	},
+	["boy-surface"]: {
+		u: [0, PI],
+		v: [0, PI],
+		point: (u, v) => {
+			const d = 2 - sqrt(2) * sin(3 * u) * sin(2 * v), c2 = cos(v) ** 2;
+			return [
+				(sqrt(2) * c2 * cos(2 * u) + cos(u) * sin(2 * v)) / d,
+				3 * c2 / d,
+				(sqrt(2) * c2 * sin(2 * u) - sin(u) * sin(2 * v)) / d
+			];
+		}
+	},
+	["enneper"]: {
+		u: [-1.5, 1.5],
+		v: [-1.5, 1.5],
+		point: (u, v) => [
+			u - u ** 3 / 3 + u * v * v,
+			u * u - v * v,
+			v - v ** 3 / 3 + v * u * u
+		]
+	},
+	["helicoid"]: {
+		u: [-PI * 1.5, PI * 1.5],
+		v: [-1, 1],
+		point: (u, v) => [
+			v * cos(u),
+			u / 3.4,
+			v * sin(u)
+		]
+	},
+	["catenoid"]: {
+		u: [0, TAU],
+		v: [-1.2, 1.2],
+		point: (u, v) => [
+			cosh(v) * cos(u),
+			v,
+			cosh(v) * sin(u)
+		]
+	},
+	["dini"]: {
+		u: [0, 4 * PI],
+		v: [.22, 1.9],
+		point: (u, v) => [
+			cos(u) * sin(v),
+			cos(v) + log(tan(v / 2)) + .12 * u,
+			sin(u) * sin(v)
+		]
+	}
+};
+export { PARAMETRIC_FORMS, ParametricSurfaceForm };

package/dist/charts/threesurfaces/ParametricSurface.js

@@ -0,0 +1,178 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { short } from "./GridSurfaceBase.js";
+import { PARAMETRIC_FORMS, ParametricSurfaceForm } from "./ParametricForms.js";
+import { SurfaceBase } from "./SurfaceBase.js";
+import { SurfaceField } from "./SurfaceField.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { Box3, BufferGeometry, Float32BufferAttribute, Vector3 } from "three";
+// src/charts/threesurfaces/ParametricSurface.ts
+var ParametricCut = /* @__PURE__ */ function(ParametricCut) {
+	ParametricCut["Whole"] = "whole";
+	ParametricCut["Bands"] = "bands";
+	ParametricCut["Half"] = "half";
+	return ParametricCut;
+}({});
+var STAGE = 1.02;
+/** Grid data wrapped onto a closed form: for periodic data like hour-by-weekday on a torus, or a pure mathematical solid. */
+var ParametricSurface = class extends SurfaceBase {
+	static meta = {
+		id: "parametric-surface",
+		name: "Parametric surface",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Three,
+		shape: DataShape.Function,
+		description: "Maps a grid onto a parametric solid such as a torus, Möbius strip, Klein bottle or sphere, colouring or displacing the skin by value.",
+		tags: [
+			"torus",
+			"mobius",
+			"klein",
+			"sphere",
+			"knot",
+			"minimal surface",
+			"periodic"
+		],
+		sample: (seed) => SampleData.surface(seed, 36),
+		variants: {
+			form: Object.values(ParametricSurfaceForm),
+			displace: [false, true],
+			cut: [
+				"whole",
+				"bands",
+				"half"
+			],
+			lines: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			form: ParametricSurfaceForm.Torus,
+			displace: false,
+			cut: "whole",
+			lines: true,
+			x: "x",
+			y: "y",
+			z: "z",
+			elevation: 22,
+			distance: 5.7
+		};
+	}
+	/** Fit the raw form into the stage cube around the origin. */
+	fit({ u: [u0, u1], v: [v0, v1], point }) {
+		const box = new Box3();
+		for (let j = 0; j <= 40; j++) for (let i = 0; i <= 40; i++) {
+			const p = point(u0 + (u1 - u0) * i / 40, v0 + (v1 - v0) * j / 40);
+			if (p.every(Number.isFinite)) box.expandByPoint(new Vector3(...p));
+		}
+		const size = box.getSize(new Vector3()), centre = box.getCenter(new Vector3()), scale = 2 * STAGE / Math.max(size.x, size.y, size.z, 1e-6);
+		return ([x, y, z]) => [
+			(x - centre.x) * scale,
+			(y - centre.y) * scale,
+			(z - centre.z) * scale
+		];
+	}
+	build(ctx) {
+		const { form, definition, displace, cut, lines, data, x, y, z } = this.options;
+		const shape = definition ?? PARAMETRIC_FORMS[form];
+		const fit = this.fit(shape);
+		const field = SurfaceField.from(data, {
+			x,
+			y,
+			z
+		}).capped(80);
+		const paint = this.painter(ctx, field.zDomain);
+		const nu = 180, nv = 72;
+		const [u0, u1] = shape.u, [v0, v1] = shape.v;
+		const uAt = (i) => u0 + (u1 - u0) * i / 179, vAt = (j) => v0 + (v1 - v0) * j / 71;
+		const read = (i, j) => {
+			const value = field.sample(i / 179 * (field.nx - 1), j / 71 * (field.ny - 1));
+			return Number.isNaN(value) ? 0 : value;
+		};
+		const raw = (u, v) => fit(shape.point(u, v));
+		const normalAt = (u, v) => {
+			const du = (u1 - u0) * .001, dv = (v1 - v0) * .001;
+			const a = new Vector3(...raw(u + du, v)).sub(new Vector3(...raw(u - du, v)));
+			const b = new Vector3(...raw(u, v + dv)).sub(new Vector3(...raw(u, v - dv)));
+			const n = a.cross(b);
+			return n.lengthSq() > 1e-16 ? n.normalize() : new Vector3(0, 1, 0);
+		};
+		const [lo, hi] = field.zDomain, reach = Math.max(Math.abs(lo), Math.abs(hi)) || 1;
+		const vertex = (i, j) => {
+			const u = uAt(i), v = vAt(j), p = raw(u, v);
+			if (!displace) return p;
+			const n = normalAt(u, v), push = read(i, j) / reach * .13;
+			return [
+				p[0] + n.x * push,
+				p[1] + n.y * push,
+				p[2] + n.z * push
+			];
+		};
+		const positions = /* @__PURE__ */ new Float32Array(38880), normals = /* @__PURE__ */ new Float32Array(38880), colors = /* @__PURE__ */ new Float32Array(38880);
+		for (let j = 0; j < nv; j++) for (let i = 0; i < nu; i++) {
+			const k = (i + j * nu) * 3, color = paint(read(i, j)), n = normalAt(uAt(i), vAt(j));
+			positions.set(vertex(i, j), k);
+			normals.set([
+				n.x,
+				n.y,
+				n.z
+			], k);
+			colors.set([
+				color.r,
+				color.g,
+				color.b
+			], k);
+		}
+		const keep = (i) => cut === "whole" || (cut === "half" ? i < 179 / 2 : Math.floor(i / 9) % 2 === 0);
+		const indices = [];
+		for (let j = 0; j < 71; j++) for (let i = 0; i < 179; i++) {
+			if (!keep(i)) continue;
+			const a = i + j * nu, b = a + 1, c = a + nu, d = c + 1;
+			indices.push(a, b, d, a, d, c);
+		}
+		const geometry = new BufferGeometry();
+		geometry.setAttribute("position", new Float32BufferAttribute(positions, 3));
+		geometry.setAttribute("normal", new Float32BufferAttribute(normals, 3));
+		geometry.setAttribute("color", new Float32BufferAttribute(colors, 3));
+		geometry.setIndex(indices);
+		const tick = [
+			[-1, ""],
+			[-.5, ""],
+			[0, ""],
+			[.5, ""],
+			[1, ""]
+		];
+		this.box(ctx, {
+			x: tick,
+			y: tick,
+			z: []
+		}, {
+			walls: false,
+			bottom: -1.05
+		});
+		const group = this.bloom(ctx);
+		this.solid(ctx, SurfaceGeometry.compact(geometry), group, (k) => {
+			const i = k % nu, j = Math.floor(k / nu);
+			return { rows: [
+				["u", short(uAt(i))],
+				["v", short(vAt(j))],
+				["value", short(read(i, j))]
+			] };
+		});
+		if (lines) {
+			const batch = new TubeBatch(.0042);
+			for (let i = 0; i < nu; i += 15) if (keep(Math.min(i, 178))) batch.add(Array.from({ length: nv }, (_, j) => vertex(i, j)));
+			for (let j = 0; j < nv; j += 12) {
+				const path = Array.from({ length: nu }, (_, i) => keep(Math.min(i, 178)) ? vertex(i, j) : [
+					NaN,
+					NaN,
+					NaN
+				]);
+				batch.add(path);
+			}
+			this.tubes(batch, group, ctx.theme.surface, .75);
+		}
+	}
+};
+export { ParametricCut, ParametricSurface, ParametricSurfaceForm };

package/dist/charts/threesurfaces/PhaseSurface.js

@@ -0,0 +1,206 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GridSurfaceBase, short } from "./GridSurfaceBase.js";
+import { SurfaceField } from "./SurfaceField.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { SurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+import { ConeGeometry, InstancedMesh, MeshStandardMaterial, Object3D, Vector3 } from "three";
+// src/charts/threesurfaces/PhaseSurface.ts
+var PhaseSurfaceSystem = /* @__PURE__ */ function(PhaseSurfaceSystem) {
+	PhaseSurfaceSystem["Data"] = "data-potential";
+	PhaseSurfaceSystem["Pendulum"] = "pendulum";
+	PhaseSurfaceSystem["DoubleWell"] = "double-well";
+	PhaseSurfaceSystem["VanDerPol"] = "van-der-pol";
+	PhaseSurfaceSystem["LotkaVolterra"] = "lotka-volterra";
+	PhaseSurfaceSystem["Damped"] = "damped-oscillator";
+	return PhaseSurfaceSystem;
+}({});
+var PhaseMarks = /* @__PURE__ */ function(PhaseMarks) {
+	PhaseMarks["Trajectories"] = "trajectories";
+	PhaseMarks["Arrows"] = "arrows";
+	PhaseMarks["Both"] = "trajectories-and-arrows";
+	return PhaseMarks;
+}({});
+var PhaseSeeding = /* @__PURE__ */ function(PhaseSeeding) {
+	PhaseSeeding["Lattice"] = "lattice";
+	PhaseSeeding["Ring"] = "ring";
+	return PhaseSeeding;
+}({});
+var SYSTEMS = {
+	["pendulum"]: {
+		x: [-6.3, 6.3],
+		y: [-3, 3],
+		flow: (q, p) => [p, -Math.sin(q)],
+		height: (q, p) => p * p / 2 - Math.cos(q)
+	},
+	["double-well"]: {
+		x: [-1.8, 1.8],
+		y: [-1.5, 1.5],
+		flow: (q, p) => [p, q - q ** 3],
+		height: (q, p) => p * p / 2 - q * q / 2 + q ** 4 / 4
+	},
+	["van-der-pol"]: {
+		x: [-3, 3],
+		y: [-4, 4],
+		flow: (q, p) => [p, 1.2 * (1 - q * q) * p - q],
+		height: (q, p) => Math.log1p(Math.hypot(p, 1.2 * (1 - q * q) * p - q))
+	},
+	["lotka-volterra"]: {
+		x: [.15, 3.4],
+		y: [.15, 3.4],
+		flow: (a, b) => [a * (1.1 - .7 * b), b * (.8 * a - .9)],
+		height: (a, b) => .8 * a - .9 * Math.log(a) + .7 * b - 1.1 * Math.log(b)
+	},
+	["damped-oscillator"]: {
+		x: [-2.4, 2.4],
+		y: [-2.4, 2.4],
+		flow: (q, p) => [p, -q - .28 * p],
+		height: (q, p) => (p * p + q * q) / 2
+	}
+};
+/** State-space flow draped on its energy surface: for reading stability, separatrices and limit cycles of a dynamical system. */
+var PhaseSurface = class extends GridSurfaceBase {
+	static meta = {
+		id: "phase-surface",
+		name: "Phase surface",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Three,
+		shape: DataShape.Function,
+		description: "Lifts a two-dimensional dynamical system onto its energy surface and traces trajectories across it, or runs downhill on your own potential.",
+		tags: [
+			"phase portrait",
+			"dynamical system",
+			"energy",
+			"potential",
+			"streamlines",
+			"limit cycle"
+		],
+		sample: (seed) => SampleData.surface(seed, 48),
+		variants: {
+			system: Object.values(PhaseSurfaceSystem),
+			marks: [
+				"trajectories",
+				"arrows",
+				"trajectories-and-arrows"
+			],
+			seeding: ["lattice", "ring"]
+		},
+		valid: ({ marks, seeding }) => marks !== "arrows" || seeding === "lattice"
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			system: "data-potential",
+			marks: "trajectories",
+			seeding: "lattice"
+		};
+	}
+	/** The chosen system; `data-potential` runs gradient descent on the user's grid. */
+	dynamics() {
+		const { system } = this.options;
+		if (system !== "data-potential") return SYSTEMS[system];
+		const field = this.field(72);
+		const [x0, x1] = field.xDomain, [y0, y1] = field.yDomain;
+		const fi = (x) => (x - x0) / (x1 - x0 || 1) * (field.nx - 1), fj = (y) => (y - y0) / (y1 - y0 || 1) * (field.ny - 1);
+		const value = (x, y) => field.sample(Math.max(0, Math.min(field.nx - 1, fi(x))), Math.max(0, Math.min(field.ny - 1, fj(y))));
+		const dx = (x1 - x0 || 1) / (field.nx - 1), dy = (y1 - y0 || 1) / (field.ny - 1);
+		return {
+			x: field.xDomain,
+			y: field.yDomain,
+			height: value,
+			flow: (x, y) => [-(value(x + dx, y) - value(x - dx, y)) / (2 * dx), -(value(x, y + dy) - value(x, y - dy)) / (2 * dy)]
+		};
+	}
+	seeds({ x: [x0, x1], y: [y0, y1] }) {
+		if (this.options.seeding === "ring") return Array.from({ length: 20 }, (_, k) => {
+			const angle = k / 20 * Math.PI * 2, radius = k % 2 ? .42 : .72;
+			return [(x0 + x1) / 2 + (x1 - x0) / 2 * radius * Math.cos(angle), (y0 + y1) / 2 + (y1 - y0) / 2 * radius * Math.sin(angle)];
+		});
+		return Array.from({ length: 36 }, (_, k) => [x0 + (x1 - x0) * (k % 6 + .5) / 6, y0 + (y1 - y0) * (Math.floor(k / 6) + .5) / 6]);
+	}
+	/** RK4 with step normalised by speed, so slow regions still get a visible curve. */
+	trace(system, seed) {
+		const { x: [x0, x1], y: [y0, y1], flow } = system;
+		const scale = Math.hypot(x1 - x0, y1 - y0);
+		const step = (x, y) => {
+			const [u, v] = flow(x, y), speed = Math.hypot(u, v);
+			return speed > 1e-9 ? [u / speed, v / speed] : [0, 0];
+		};
+		const path = [seed], h = scale * .006;
+		let [x, y] = seed;
+		for (let k = 0; k < 170; k++) {
+			const [a, b] = step(x, y), [c, d] = step(x + h / 2 * a, y + h / 2 * b), [e, f] = step(x + h / 2 * c, y + h / 2 * d), [g, m] = step(x + h * e, y + h * f);
+			x += h / 6 * (a + 2 * c + 2 * e + g);
+			y += h / 6 * (b + 2 * d + 2 * f + m);
+			if (x < x0 || x > x1 || y < y0 || y > y1 || !Number.isFinite(x + y) || a === 0 && b === 0) break;
+			path.push([x, y]);
+		}
+		return path;
+	}
+	build(ctx) {
+		const { marks } = this.options;
+		const system = this.dynamics();
+		const { x: [x0, x1], y: [y0, y1] } = system;
+		const n = 72;
+		const axisX = Array.from({ length: n }, (_, k) => x0 + (x1 - x0) * k / 71), axisY = Array.from({ length: n }, (_, k) => y0 + (y1 - y0) * k / 71);
+		const field = SurfaceField.compute(axisX, axisY, system.height);
+		const space = new SurfaceSpace(field);
+		const paint = this.painter(ctx, field.zDomain);
+		this.box(ctx, this.axes(space));
+		const lift = this.rise(ctx);
+		this.solid(ctx, SurfaceGeometry.grid(n, n, (i, j) => space.at(i, j), (i, j) => paint(field.at(i, j))), lift, this.gridTip(space));
+		if (!field.hasData) return;
+		const toWorld = ([x, y], rise = .012) => space.at((x - x0) / (x1 - x0 || 1) * 71, (y - y0) / (y1 - y0 || 1) * 71, rise);
+		const paths = this.seeds(system).map((seed) => this.trace(system, seed).map((point) => toWorld(point)));
+		if (marks !== "arrows") {
+			const batch = new TubeBatch(.0065);
+			for (const path of paths) batch.add(path);
+			this.tubes(batch, lift, ctx.theme.ink, .85);
+			this.runners(ctx, paths, lift);
+		}
+		if (marks !== "trajectories") this.arrows(ctx, system, toWorld, lift);
+	}
+	/** Beads that ride the trajectories, so the direction of the flow is obvious in motion. */
+	runners(ctx, paths, parent) {
+		const used = paths.filter((path) => path.length > 8);
+		const mesh = this.dots(ctx, used.map((path) => path[0]), .018, () => ctx.color(ctx.theme.ink), parent);
+		if (!mesh) return;
+		const dummy = new Object3D();
+		ctx.onFrame((t) => {
+			used.forEach((path, k) => {
+				dummy.position.set(...path[Math.floor((t * 34 + k * 11) % path.length)]);
+				dummy.scale.setScalar(.018);
+				dummy.updateMatrix();
+				mesh.setMatrixAt(k, dummy.matrix);
+			});
+			mesh.instanceMatrix.needsUpdate = true;
+		});
+	}
+	arrows(ctx, system, toWorld, parent) {
+		const { x: [x0, x1], y: [y0, y1], flow } = system;
+		const count = 15, spots = Array.from({ length: 225 }, (_, k) => [x0 + (x1 - x0) * (k % count + .5) / count, y0 + (y1 - y0) * (Math.floor(k / count) + .5) / count]);
+		const mesh = new InstancedMesh(new ConeGeometry(.019, .075, 7).translate(0, .0375, 0), new MeshStandardMaterial({
+			color: ctx.theme.ink,
+			roughness: .5
+		}), spots.length);
+		const dummy = new Object3D(), axis = new Vector3(0, 1, 0), heading = new Vector3();
+		spots.forEach((spot, k) => {
+			const [u, v] = flow(...spot), speed = Math.hypot(u, v), e = .001 * (x1 - x0);
+			const from = new Vector3(...toWorld(spot, .018));
+			const to = new Vector3(...toWorld([Math.min(x1, Math.max(x0, spot[0] + u / (speed || 1) * e)), Math.min(y1, Math.max(y0, spot[1] + v / (speed || 1) * e))], .018));
+			heading.subVectors(to, from);
+			dummy.position.copy(from);
+			dummy.quaternion.setFromUnitVectors(axis, heading.lengthSq() > 1e-12 ? heading.normalize() : axis);
+			dummy.scale.setScalar(speed > 1e-6 ? 1 : .001);
+			dummy.updateMatrix();
+			mesh.setMatrixAt(k, dummy.matrix);
+		});
+		parent.add(mesh);
+		ctx.pick(mesh, (k) => {
+			const [u, v] = flow(...spots[k]);
+			return { rows: [["speed", short(Math.hypot(u, v))]] };
+		});
+	}
+};
+export { PhaseMarks, PhaseSeeding, PhaseSurface, PhaseSurfaceSystem };

package/dist/charts/threesurfaces/PolarSurface.js

@@ -0,0 +1,135 @@
+import { ChartFamily, DataShape, Dimension, ScaleKind } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { GridSurfaceBase } from "./GridSurfaceBase.js";
+import { SurfaceOverlay } from "./SurfaceBase.js";
+import { SurfaceGeometry } from "./SurfaceGeometry.js";
+import { FLOOR, PolarSurfaceSpace } from "./SurfaceSpace.js";
+import { TubeBatch } from "./TubeBatch.js";
+// src/charts/threesurfaces/PolarSurface.ts
+/** Far-side labels would sit behind the surface from the default camera. */
+var FACING = 38 * Math.PI / 180;
+var PolarAngleAxis = /* @__PURE__ */ function(PolarAngleAxis) {
+	PolarAngleAxis["X"] = "angle-from-x";
+	PolarAngleAxis["Y"] = "angle-from-y";
+	return PolarAngleAxis;
+}({});
+/** A surface over a disc: for data that is naturally polar, like antenna gain, wind roses or turbine blade loads. */
+var PolarSurface = class extends GridSurfaceBase {
+	static meta = {
+		id: "polar-surface",
+		name: "Polar surface",
+		family: ChartFamily.Radial,
+		dimension: Dimension.Three,
+		shape: DataShape.Grid,
+		description: "Wraps a height field around a disc, annulus or sector, with one grid axis as angle and the other as radius.",
+		tags: [
+			"polar",
+			"radial",
+			"disc",
+			"antenna pattern",
+			"annulus"
+		],
+		sample: (seed) => SampleData.surface(seed, 48),
+		variants: {
+			sweep: [
+				360,
+				270,
+				180
+			],
+			hole: [
+				.18,
+				0,
+				.45
+			],
+			overlay: [
+				SurfaceOverlay.Mesh,
+				SurfaceOverlay.Contours,
+				SurfaceOverlay.None
+			],
+			angle: ["angle-from-x", "angle-from-y"],
+			solidBase: [false, true]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			sweep: 360,
+			hole: .18,
+			overlay: SurfaceOverlay.Mesh,
+			angle: "angle-from-x",
+			solidBase: false
+		};
+	}
+	rings(ctx, space, parent) {
+		const { hole, sweep } = this.options;
+		const batch = new TubeBatch(.003, 4);
+		for (const radius of [hole, ...[
+			.25,
+			.5,
+			.75,
+			1
+		].filter((r) => r > hole)]) {
+			if (!radius) continue;
+			batch.add(Array.from({ length: 73 }, (_, k) => {
+				const [x, z] = space.polar(k / 72, radius);
+				return [
+					x,
+					FLOOR + .002,
+					z
+				];
+			}));
+		}
+		for (let k = 0; k <= 8; k++) {
+			if (sweep === 360 && k === 8) continue;
+			const [a, b] = space.polar(k / 8, Math.max(hole, .001)), [c, d] = space.polar(k / 8, 1);
+			batch.add([[
+				a,
+				FLOOR + .002,
+				b
+			], [
+				c,
+				FLOOR + .002,
+				d
+			]]);
+		}
+		this.tubes(batch, parent, ctx.theme.axis);
+	}
+	build(ctx) {
+		const { sweep, hole, overlay, angle, solidBase } = this.options;
+		const field = this.field();
+		const space = new PolarSurfaceSpace(field, ScaleKind.Linear, sweep, hole, angle === "angle-from-y");
+		const paint = this.painter(ctx, field.zDomain);
+		this.box(ctx, {
+			x: [],
+			y: [],
+			z: this.ticks(field.zDomain, space.level, 3)
+		}, {
+			walls: false,
+			outline: false
+		});
+		this.rings(ctx, space, ctx.root);
+		const lift = this.rise(ctx);
+		const closed = sweep === 360;
+		const wrap = closed ? angle === "angle-from-x" ? { x: true } : { y: true } : {};
+		this.solid(ctx, SurfaceGeometry.grid(field.nx, field.ny, (i, j) => space.at(i, j), (i, j) => paint(field.at(i, j)), wrap), lift, this.gridTip(space));
+		if (solidBase) this.skirt(ctx, space, paint, lift, closed ? angle === "angle-from-x" ? [0, 2] : [1, 3] : [
+			0,
+			1,
+			2,
+			3
+		], closed);
+		if (overlay === SurfaceOverlay.Mesh) this.meshLines(ctx, space, lift);
+		if (overlay === SurfaceOverlay.Contours) this.contourLines(ctx, space, lift);
+		const domain = angle === "angle-from-x" ? field.xDomain : field.yDomain;
+		for (const [turn, text] of this.ticks(domain, (v) => (v - domain[0]) / (domain[1] - domain[0] || 1), 6)) {
+			if (closed && turn >= .99) continue;
+			const [x, z] = space.polar(turn, 1.1);
+			if (x * Math.sin(FACING) + z * Math.cos(FACING) > -.2) ctx.label(text, [
+				x,
+				FLOOR,
+				z
+			], "muted", 10);
+		}
+	}
+};
+export { PolarAngleAxis, PolarSurface };