@mstone6969/graph 0.0.0-stage → 0.2.0

package/dist/charts/mathematical/FourierSeriesChart.js

@@ -0,0 +1,276 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { MathMarks } from "./MathMarks.js";
+import { MathNumerics } from "./MathNumerics.js";
+import { MathPlane } from "./MathPlane.js";
+// src/charts/mathematical/FourierSeriesChart.ts
+/** `Data` analyses the rows; the others are the textbook periodic waves. */
+var FourierWave = /* @__PURE__ */ function(FourierWave) {
+	FourierWave["Data"] = "data";
+	FourierWave["Square"] = "square";
+	FourierWave["Sawtooth"] = "sawtooth";
+	FourierWave["Triangle"] = "triangle";
+	FourierWave["Pulse"] = "pulse";
+	return FourierWave;
+}({});
+var FourierView = /* @__PURE__ */ function(FourierView) {
+	FourierView["Synthesis"] = "synthesis";
+	FourierView["Harmonics"] = "harmonics";
+	FourierView["Spectrum"] = "spectrum";
+	FourierView["Epicycles"] = "epicycles";
+	return FourierView;
+}({});
+var SAMPLES = 256;
+var TAU = Math.PI * 2;
+var MOMENT = .13;
+var ISO_DATE = /^\d{4}-\d{2}(-\d{2})?/;
+var WAVES = {
+	["square"]: (t) => t < .5 ? 1 : -1,
+	["sawtooth"]: (t) => 2 * t - 1,
+	["triangle"]: (t) => 1 - 4 * Math.abs(t - .5),
+	["pulse"]: (t) => t < .2 ? 1 : 0
+};
+/** Decomposes a periodic signal into sinusoids: how partial sums converge, what the spectrum holds, and the rotating-circle view. */
+var FourierSeriesChart = class FourierSeriesChart extends MathPlane {
+	static meta = {
+		id: "fourier-series",
+		name: "Fourier series chart",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Two,
+		shape: DataShape.Function,
+		description: "Shows a signal rebuilt from sinusoids as a partial sum, stacked harmonics, an amplitude spectrum or rotating epicycles.",
+		tags: [
+			"harmonics",
+			"spectrum",
+			"epicycles",
+			"gibbs"
+		],
+		sample: (seed) => SampleData.timeSeries(seed, 120, 1),
+		variants: {
+			wave: Object.values(FourierWave),
+			view: Object.values(FourierView),
+			terms: [
+				9,
+				3,
+				21
+			]
+		}
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			wave: "data",
+			view: "synthesis",
+			terms: 9,
+			x: "date",
+			y: "value"
+		};
+	}
+	keepsProportion() {
+		return this.options.view === "epicycles";
+	}
+	labelsY() {
+		return this.options.view !== "harmonics" && this.options.view !== "epicycles";
+	}
+	plotMargin() {
+		return this.labelsY() ? super.plotMargin() : {
+			...super.plotMargin(),
+			left: 42
+		};
+	}
+	/** A row's place along the period, NaN when it has none. */
+	static position(cell) {
+		if (cell === null || cell === void 0 || cell === "") return NaN;
+		return typeof cell === "string" && ISO_DATE.test(cell) ? Date.parse(cell) : +cell;
+	}
+	signal() {
+		const { wave, data, x, y } = this.options;
+		const ts = Array.from({ length: SAMPLES }, (_, i) => i / SAMPLES);
+		if (wave !== "data") return ts.map(WAVES[wave]);
+		const points = data.map((row) => [FourierSeriesChart.position(row[x]), row[y] === null ? NaN : +row[y]]).filter((p) => Number.isFinite(p[0]) && Number.isFinite(p[1]));
+		if (!points.length) return ts.map(() => 0);
+		const a = Math.min(...points.map((p) => p[0])), b = Math.max(...points.map((p) => p[0]));
+		const fn = MathNumerics.interpolate(points);
+		return ts.map((t) => fn(a + (b - a) * t));
+	}
+	analyse(signal) {
+		return {
+			mean: signal.reduce((sum, v) => sum + v, 0) / SAMPLES,
+			harmonics: Array.from({ length: this.options.terms }, (_, i) => {
+				const k = i + 1;
+				let a = 0, b = 0;
+				signal.forEach((v, n) => {
+					a += v * Math.cos(TAU * k * n / SAMPLES);
+					b += v * Math.sin(TAU * k * n / SAMPLES);
+				});
+				a *= 2 / SAMPLES;
+				b *= 2 / SAMPLES;
+				return {
+					k,
+					a,
+					b,
+					amplitude: Math.hypot(a, b),
+					phase: Math.atan2(a, b)
+				};
+			})
+		};
+	}
+	static wave(h, t) {
+		return h.a * Math.cos(TAU * h.k * t) + h.b * Math.sin(TAU * h.k * t);
+	}
+	partial(mean, harmonics, t, upTo = Infinity) {
+		return harmonics.reduce((sum, h) => h.k <= upTo ? sum + FourierSeriesChart.wave(h, t) : sum, mean);
+	}
+	/** Rotating arms at the moment shown, largest first, ending on the partial sum. */
+	chain(harmonics) {
+		const arms = [];
+		let tip = [0, 0];
+		for (const h of [...harmonics].sort((p, q) => q.amplitude - p.amplitude)) {
+			const angle = TAU * h.k * MOMENT + h.phase;
+			arms.push({
+				k: h.k,
+				c: tip,
+				r: h.amplitude
+			});
+			tip = [tip[0] + h.amplitude * Math.cos(angle), tip[1] + h.amplitude * Math.sin(angle)];
+		}
+		return {
+			arms,
+			tip
+		};
+	}
+	/** Half-height that holds both the circles and the traced wave. */
+	reach(harmonics) {
+		const { arms } = this.chain(harmonics);
+		const wave = MathNumerics.linspace(0, 1, 200).map((t) => Math.abs(this.partial(0, harmonics, t)));
+		return Math.max(1e-6, ...wave, ...arms.map((d) => Math.max(Math.abs(d.c[0]), Math.abs(d.c[1])) + d.r));
+	}
+	/** Spectrum bars are counted, so ticks fall on whole harmonics. */
+	xStep() {
+		return this.options.view === "spectrum" ? Math.ceil(this.options.terms / 7) : null;
+	}
+	extent() {
+		const signal = this.signal();
+		const { mean, harmonics } = this.analyse(signal);
+		const { view, terms } = this.options;
+		if (view === "spectrum") return [[.2, terms + .8], [0, Math.max(...harmonics.map((h) => h.amplitude), 1e-6) * 1.08]];
+		if (view === "epicycles") {
+			const r = this.reach(harmonics);
+			return [[-r * 1.08, r * 4.2], [-r * 1.08, r * 1.08]];
+		}
+		if (view === "harmonics") return [[0, 1], [-.7, Math.min(6, terms) + 1.6]];
+		const samples = MathNumerics.linspace(0, 1, 300).map((t) => this.partial(mean, harmonics, t));
+		const low = Math.min(...signal, ...samples), high = Math.max(...signal, ...samples), pad = (high - low || 1) * .08;
+		return [[0, 1], [low - pad, high + pad]];
+	}
+	plotPlane(ctx, plane) {
+		const signal = this.signal();
+		const { mean, harmonics } = this.analyse(signal);
+		const { view } = this.options;
+		const parts = {
+			synthesis: view === "synthesis",
+			harmonics: view === "harmonics",
+			spectrum: view === "spectrum",
+			epicycles: view === "epicycles"
+		};
+		this.drawSynthesis(ctx, plane, parts.synthesis ? signal : [], mean, parts.synthesis ? harmonics : []);
+		this.drawHarmonics(ctx, plane, parts.harmonics ? harmonics : []);
+		this.drawSpectrum(ctx, plane, parts.spectrum ? harmonics : []);
+		this.drawEpicycles(ctx, plane, parts.epicycles ? harmonics : [], mean);
+	}
+	drawSynthesis(ctx, plane, signal, mean, harmonics) {
+		const { x, y } = plane;
+		const curve = (fn) => MathMarks.line(MathNumerics.linspace(0, 1, 520).map((t) => [x(t), y(fn(t))]));
+		const target = ctx.marks("fou-target", "path", signal.length ? [0] : []);
+		MathMarks.stroke(target, ctx.theme.inkMuted, 1.5);
+		ctx.set(target, { d: () => MathMarks.line(signal.map((v, i) => [x(i / SAMPLES), y(v)])) });
+		const stages = harmonics.length ? [
+			Math.ceil(harmonics.length / 4),
+			Math.ceil(harmonics.length / 2),
+			harmonics.length
+		].filter((v, i, all) => all.indexOf(v) === i) : [];
+		const top = stages[stages.length - 1];
+		const name = (k) => `${k} term${k === 1 ? "" : "s"}`;
+		const sums = MathMarks.stroke(ctx.marks("fou-sum", "path", stages, (d) => d), (k) => ctx.palette.color(name(k))).attr("stroke-width", (k) => k === top ? 2 : 1.25);
+		MathMarks.reveal(ctx, sums, (k) => curve((t) => this.partial(mean, harmonics, t, k)));
+		if (signal.length) this.probe(ctx, plane, (t) => ({
+			title: `t = ${MathNumerics.format(t)} of the period`,
+			rows: [["Signal", MathNumerics.format(signal[Math.min(255, Math.floor(t * SAMPLES))])], ...stages.map((k) => [name(k), MathNumerics.format(this.partial(mean, harmonics, t, k))])]
+		}));
+		else ctx.marks("plane-probe", "rect", []);
+	}
+	drawHarmonics(ctx, { x, y }, harmonics) {
+		const shown = harmonics.slice(0, 6);
+		const peak = Math.max(...shown.map((h) => h.amplitude), 1e-9);
+		const rows = shown.length;
+		const sumPeak = Math.max(...MathNumerics.linspace(0, 1, 200).map((t) => Math.abs(this.partial(0, harmonics, t))), 1e-9);
+		const lane = (i) => rows - 1 - i;
+		const wave = (h, i) => MathMarks.line(MathNumerics.linspace(0, 1, 320).map((t) => [x(t), y(lane(i) + FourierSeriesChart.wave(h, t) / peak * .46)]));
+		const lines = MathMarks.stroke(ctx.marks("fou-harmonic", "path", shown, (d) => d.k), ctx.palette.sequential(.6), 1.5);
+		MathMarks.reveal(ctx, lines, wave);
+		ctx.hover(lines, (d) => ({
+			title: `Harmonic ${d.k}`,
+			rows: [["Amplitude", MathNumerics.format(d.amplitude)], ["Phase", MathNumerics.format(d.phase)]]
+		}));
+		const sum = harmonics.length ? [MathMarks.line(MathNumerics.linspace(0, 1, 520).map((t) => [x(t), y(rows + .6 + this.partial(0, harmonics, t) / sumPeak * .72)]))] : [];
+		MathMarks.stroke(ctx.set(ctx.marks("fou-total", "path", sum), { d: (d) => d }), ctx.theme.ink, 2);
+		const labels = [...shown.map((h, i) => ({
+			key: `k${h.k}`,
+			text: `k = ${h.k}`,
+			y: y(lane(i))
+		})), ...harmonics.length ? [{
+			key: "sum",
+			text: "Σ",
+			y: y(rows + .6)
+		}] : []];
+		ctx.text(ctx.marks("fou-tag", "text", labels, (d) => d.key).attr("text-anchor", "end").attr("x", -6).attr("y", (d) => d.y + 4).text((d) => d.text), 10.5);
+	}
+	drawSpectrum(ctx, { x, y }, harmonics) {
+		const step = Math.abs(x(2) - x(1)), wide = Math.max(2, Math.min(26, step - 2));
+		const bars = ctx.marks("fou-bar", "rect", harmonics, (d) => d.k).attr("fill", ctx.palette.sequential(.7)).attr("rx", Math.min(4, wide / 2));
+		ctx.set(bars, {
+			x: (d) => x(d.k) - wide / 2,
+			width: wide,
+			y: (d) => y(d.amplitude),
+			height: (d) => Math.max(0, y(0) - y(d.amplitude))
+		}, {
+			x: (d) => x(d.k) - wide / 2,
+			width: wide,
+			y: y(0),
+			height: 0
+		}, 14);
+		ctx.hover(bars, (d) => ({
+			title: `Harmonic ${d.k}`,
+			rows: [["Amplitude", MathNumerics.format(d.amplitude)], ["Phase", MathNumerics.format(d.phase)]]
+		}));
+	}
+	drawEpicycles(ctx, { x, y }, harmonics, mean) {
+		const r = this.reach(harmonics);
+		const { arms, tip } = this.chain(harmonics);
+		const toX = (v) => x(v), toY = (v) => y(v);
+		const scale = Math.abs(x(1) - x(0));
+		const circles = ctx.marks("fou-circle", "circle", arms, (d) => d.k).attr("fill", "none").attr("stroke", ctx.theme.axis);
+		ctx.set(circles, {
+			cx: (d) => toX(d.c[0]),
+			cy: (d) => toY(d.c[1]),
+			r: (d) => d.r * scale
+		});
+		ctx.hover(circles, (d) => ({
+			title: `Harmonic ${d.k}`,
+			rows: [["Radius", MathNumerics.format(d.r)]]
+		}));
+		const spine = arms.length ? [MathMarks.line([...arms.map((d) => [toX(d.c[0]), toY(d.c[1])]), [toX(tip[0]), toY(tip[1])]])] : [];
+		MathMarks.stroke(ctx.set(ctx.marks("fou-arm", "path", spine), { d: (d) => d }), ctx.theme.ink, 1.5);
+		const start = r * 1.25, length = r * 2.9;
+		const trace = arms.length ? [MathMarks.line(MathNumerics.linspace(0, 1, 420).map((s) => [toX(start + s * length), toY(this.partial(0, harmonics, MOMENT - s * .999))]))] : [];
+		MathMarks.reveal(ctx, MathMarks.stroke(ctx.marks("fou-trace", "path", trace), ctx.theme.ink), (d) => d);
+		const link = arms.length ? [MathMarks.line([[toX(tip[0]), toY(tip[1])], [toX(start), toY(tip[1])]])] : [];
+		ctx.set(MathMarks.stroke(ctx.marks("fou-link", "path", link), ctx.theme.inkMuted, 1).attr("stroke-dasharray", "3 3"), { d: (d) => d });
+		const pens = MathMarks.dot(ctx, ctx.marks("fou-pen", "circle", arms.length ? [start] : []), (d) => toX(d), () => toY(tip[1]), ctx.theme.ink);
+		ctx.hover(pens, () => ({
+			title: "Partial sum now",
+			rows: [["Value", MathNumerics.format(tip[1] + mean)]]
+		}));
+	}
+};
+export { FourierSeriesChart, FourierView, FourierWave };

package/dist/charts/mathematical/FunctionCurves.js

@@ -0,0 +1,33 @@
+import { MathNumerics } from "./MathNumerics.js";
+import { group, quantile } from "d3";
+// src/charts/mathematical/FunctionCurves.ts
+var isLive = (item) => typeof item.fn === "function";
+var usable = (cell) => cell !== null && cell !== void 0 && cell !== "" && Number.isFinite(+cell);
+/** Turns `FunctionData` into callable curves so every chart treats formulas and measurements alike. */
+function resolveCurves(data, x, y, series) {
+	const curves = data.filter(isLive);
+	const rows = data.filter((item) => !isLive(item)).filter((row) => usable(row[x]) && usable(row[y]));
+	if (!rows.length) return { curves };
+	const xs = rows.map((row) => +row[x]);
+	const tables = group(rows, (row) => String(row[series] ?? "y"));
+	for (const [name, part] of tables) curves.push({
+		name,
+		fn: MathNumerics.interpolate(part.map((row) => [+row[x], +row[y]]))
+	});
+	return {
+		curves,
+		domain: [Math.min(...xs), Math.max(...xs)]
+	};
+}
+/** Value range that survives poles: a heavy tail is cut at the percentiles, then padded. */
+function robustRange(values) {
+	const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+	if (!sorted.length) return [-1, 1];
+	const low = sorted[0], high = sorted[sorted.length - 1];
+	const q05 = quantile(sorted, .05), q95 = quantile(sorted, .95);
+	const heavy = high - low > 6 * (q95 - q05 || 1);
+	const a = heavy ? quantile(sorted, .03) : low, b = heavy ? quantile(sorted, .97) : high;
+	const pad = (b - a || 1) * .08;
+	return [a - pad, b + pad];
+}
+export { resolveCurves, robustRange };

package/dist/charts/mathematical/FunctionPlot.js

@@ -0,0 +1,188 @@
+import { ChartFamily, DataShape, Dimension, ScaleKind } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { resolveCurves, robustRange } from "./FunctionCurves.js";
+import { MathMarks } from "./MathMarks.js";
+import { MathNumerics } from "./MathNumerics.js";
+import { MathPlane, PlaneFrame, PlaneTicks } from "./MathPlane.js";
+// src/charts/mathematical/FunctionPlot.ts
+var FunctionFill = /* @__PURE__ */ function(FunctionFill) {
+	FunctionFill["None"] = "none";
+	FunctionFill["Under"] = "under";
+	FunctionFill["Between"] = "between";
+	return FunctionFill;
+}({});
+var FunctionCompanion = /* @__PURE__ */ function(FunctionCompanion) {
+	FunctionCompanion["None"] = "none";
+	FunctionCompanion["Derivative"] = "derivative";
+	FunctionCompanion["Integral"] = "integral";
+	return FunctionCompanion;
+}({});
+var TAU = Math.PI * 2;
+/** Plots y = f(x) from formulas or tabulated rows, breaking cleanly at poles: for reading shape, roots and turning points. */
+var FunctionPlot = class extends MathPlane {
+	static meta = {
+		id: "function-plot",
+		name: "Function plot",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Two,
+		shape: DataShape.Function,
+		description: "Plots one or more functions of x, with optional derivative, integral, shaded area and marked critical points.",
+		tags: [
+			"calculus",
+			"curve",
+			"graphing calculator",
+			"derivative"
+		],
+		sample: (seed) => {
+			const [a, b] = SampleData.categories(seed, 2, 1).map((row) => +row.value / 60);
+			return [{
+				name: "f(x)",
+				fn: (x) => a * Math.sin(x) + .4 * Math.sin(2.3 * x)
+			}, {
+				name: "g(x)",
+				fn: (x) => b * Math.cos(x / 2) * Math.exp(-x * x / 40) - .3
+			}];
+		},
+		variants: {
+			fill: [
+				"none",
+				"under",
+				"between"
+			],
+			companion: [
+				"none",
+				"derivative",
+				"integral"
+			],
+			features: [false, true],
+			frame: [PlaneFrame.Box, PlaneFrame.Cross],
+			ticks: [PlaneTicks.Decimal, PlaneTicks.Pi],
+			yScale: [ScaleKind.Linear, ScaleKind.Symlog]
+		},
+		valid: (v) => !(v.yScale === ScaleKind.Symlog && (v.ticks === PlaneTicks.Pi || v.fill === "between"))
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			x: "x",
+			y: "y",
+			series: "group",
+			fill: "none",
+			companion: "none",
+			features: false
+		};
+	}
+	resolved() {
+		return resolveCurves(this.options.data, this.options.x, this.options.y, this.options.series);
+	}
+	span() {
+		return this.options.xDomain ?? this.resolved().domain ?? [-TAU, TAU];
+	}
+	companion(curve) {
+		const { companion } = this.options;
+		if (companion === "derivative") return (x) => MathNumerics.derivative(curve.fn, x);
+		if (companion === "integral") return MathNumerics.antiderivative(curve.fn, this.span());
+		return null;
+	}
+	extent() {
+		const span = this.span(), xs = MathNumerics.linspace(span[0], span[1], 400);
+		const values = this.resolved().curves.flatMap((curve) => {
+			const twin = this.companion(curve);
+			return xs.flatMap((x) => twin ? [curve.fn(x), twin(x)] : [curve.fn(x)]);
+		});
+		const [a, b] = robustRange(values);
+		return [span, this.options.fill === "none" ? [a, b] : [Math.min(a, 0), Math.max(b, 0)]];
+	}
+	features(curves, span, range) {
+		return curves.flatMap((curve) => {
+			const of = (kind, xs) => xs.slice(0, 8).map((x) => ({
+				key: `${curve.name}/${kind}/${x.toFixed(4)}`,
+				x,
+				y: curve.fn(x),
+				kind,
+				name: curve.name
+			}));
+			return [...of("Root", MathNumerics.roots(curve.fn, span)), ...of("Extremum", MathNumerics.roots((x) => MathNumerics.derivative(curve.fn, x), span, 240))].filter((f) => Number.isFinite(f.y) && f.y >= range[0] && f.y <= range[1]);
+		});
+	}
+	areas(curve, { box, x, y }) {
+		const base = y(Math.max(box[1][0], Math.min(box[1][1], 0)));
+		const clamp = (value) => Math.max(box[1][0], Math.min(box[1][1], value));
+		return MathNumerics.trace(curve.fn, box[0], 420).map((run) => MathMarks.line([
+			[x(run[0][0]), base],
+			...run.map((p) => [x(p[0]), y(clamp(p[1]))]),
+			[x(run[run.length - 1][0]), base]
+		], true)).join("");
+	}
+	/** Lens-shaped regions between two curves, split wherever they cross. */
+	lenses(f, g, { box, x, y }) {
+		const clamp = (value) => Math.max(box[1][0], Math.min(box[1][1], value));
+		const xs = MathNumerics.linspace(box[0][0], box[0][1], 420);
+		const lenses = [];
+		let run = [];
+		const flush = (sign) => {
+			if (run.length > 1) lenses.push({
+				sign,
+				d: MathMarks.line([...run.map((v) => [x(v), y(clamp(f.fn(v)))]), ...[...run].reverse().map((v) => [x(v), y(clamp(g.fn(v)))])], true)
+			});
+			run = [];
+		};
+		let sign = 0;
+		for (const value of xs) {
+			const next = Math.sign(f.fn(value) - g.fn(value));
+			if (!Number.isFinite(next)) {
+				flush(sign);
+				continue;
+			}
+			if (next !== sign && run.length) {
+				run.push(value);
+				flush(sign);
+				run = [value];
+			}
+			sign = next;
+			run.push(value);
+		}
+		flush(sign);
+		return lenses;
+	}
+	plotPlane(ctx, plane) {
+		const { fill, features } = this.options;
+		const { curves } = this.resolved();
+		const { x, y, box } = plane;
+		const color = (curve) => ctx.palette.color(curve.name);
+		const toPixels = (runs) => runs.map((run) => MathMarks.line(run.map((p) => [x(p[0]), y(p[1])]))).join("");
+		const runs = (fn) => toPixels(MathNumerics.clip(MathNumerics.trace(fn, box[0]), box[1]));
+		const under = ctx.marks("fn-area", "path", fill === "under" ? curves : [], (d) => d.name).attr("fill", color).attr("fill-opacity", .14);
+		ctx.set(under, { d: (d) => this.areas(d, plane) });
+		const lenses = fill === "between" && curves.length > 1 ? this.lenses(curves[0], curves[1], plane) : [];
+		ctx.set(ctx.marks("fn-lens", "path", lenses).attr("fill", (d) => ctx.palette.diverging(d.sign * .85)).attr("fill-opacity", .45), { d: (d) => d.d });
+		const twins = curves.flatMap((curve) => {
+			const fn = this.companion(curve);
+			return fn ? [{
+				name: curve.name,
+				fn
+			}] : [];
+		});
+		const dashed = MathMarks.stroke(ctx.marks("fn-companion", "path", twins, (d) => d.name), (d) => ctx.palette.color(d.name), 1.5).attr("stroke-dasharray", "2 5").attr("stroke-opacity", .9);
+		ctx.set(dashed, { d: (d) => runs(d.fn) });
+		const lines = MathMarks.stroke(ctx.marks("fn-line", "path", curves, (d) => d.name), color);
+		MathMarks.reveal(ctx, lines, (d) => runs(d.fn));
+		this.probe(ctx, plane, (value) => ({
+			title: `x = ${MathNumerics.format(value)}`,
+			rows: curves.flatMap((curve) => {
+				const twin = twins.find((t) => t.name === curve.name);
+				const row = [curve.name, MathNumerics.format(curve.fn(value))];
+				return twin ? [row, [`${this.options.companion === "derivative" ? "d/dx" : "∫"} ${curve.name}`, MathNumerics.format(twin.fn(value))]] : [row];
+			})
+		}));
+		const marks = features ? this.features(curves, box[0], box[1]) : [];
+		const dots = ctx.marks("fn-feature", "circle", marks, (d) => d.key);
+		MathMarks.dot(ctx, dots, (d) => x(d.x), (d) => y(d.y), (d) => d.kind === "Root" ? ctx.theme.ink : ctx.palette.color(d.name), 4);
+		ctx.hover(dots, (d) => ({
+			title: `${d.kind} of ${d.name}`,
+			color: ctx.palette.color(d.name),
+			rows: [["x", MathNumerics.format(d.x)], ["y", MathNumerics.format(d.y)]]
+		}));
+	}
+};
+export { FunctionCompanion, FunctionFill, FunctionPlot };

package/dist/charts/mathematical/ImplicitPlot.js

@@ -0,0 +1,153 @@
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { BandRaster } from "./BandRaster.js";
+import { MathMarks } from "./MathMarks.js";
+import { MathNumerics } from "./MathNumerics.js";
+import { MathPlane, PlaneFrame } from "./MathPlane.js";
+// src/charts/mathematical/ImplicitPlot.ts
+var ImplicitForm = /* @__PURE__ */ function(ImplicitForm) {
+	ImplicitForm["Ellipse"] = "ellipse";
+	ImplicitForm["Hyperbola"] = "hyperbola";
+	ImplicitForm["Cassini"] = "cassini";
+	ImplicitForm["Lemniscate"] = "lemniscate";
+	ImplicitForm["Folium"] = "folium";
+	ImplicitForm["Heart"] = "heart";
+	ImplicitForm["Superellipse"] = "superellipse";
+	ImplicitForm["EllipticCurve"] = "elliptic-curve";
+	return ImplicitForm;
+}({});
+var ImplicitView = /* @__PURE__ */ function(ImplicitView) {
+	ImplicitView["Curve"] = "curve";
+	ImplicitView["Levels"] = "levels";
+	ImplicitView["Regions"] = "regions";
+	ImplicitView["Bands"] = "bands";
+	return ImplicitView;
+}({});
+var BANDS = 12;
+var GRID = [190, 130];
+function named(form, a, b) {
+	switch (form) {
+		case "hyperbola": return (x, y) => x * x / (a * a) - y * y / (b * b) - 1;
+		case "cassini": return (x, y) => (x * x + y * y) ** 2 - 2 * (x * x - y * y) - (a ** 4 - 1);
+		case "lemniscate": return (x, y) => (x * x + y * y) ** 2 - 2 * a * a * (x * x - y * y);
+		case "folium": return (x, y) => x ** 3 + y ** 3 - 3 * a * x * y;
+		case "heart": return (x, y) => {
+			const u = x / a, v = y / a;
+			return (u * u + v * v - 1) ** 3 - u * u * v ** 3;
+		};
+		case "superellipse": return (x, y) => Math.abs(x / a) ** 4 + Math.abs(y / b) ** 4 - 1;
+		case "elliptic-curve": return (x, y) => y * y - x ** 3 + a * x - b;
+		default: return (x, y) => x * x / (a * a) + y * y / (b * b) - 1;
+	}
+}
+/** Curves defined by F(x, y) = 0, such as conics and ovals that are not functions of x; can show the whole level structure of F. */
+var ImplicitPlot = class extends MathPlane {
+	static meta = {
+		id: "implicit-plot",
+		name: "Implicit plot",
+		family: ChartFamily.Mathematical,
+		dimension: Dimension.Two,
+		shape: DataShape.Function,
+		description: "Draws the solution set of F(x, y) = 0 by marching squares, with optional level sets or sign regions of F.",
+		tags: [
+			"conic",
+			"level set",
+			"relation",
+			"oval"
+		],
+		sample: (seed) => SampleData.categories(seed, 2, 1).map((row, i) => ({
+			name: String(row.category),
+			a: 1.2 + i * .5 + +row.value % 5 * .04,
+			b: .8 + i * .4
+		})),
+		variants: {
+			form: Object.values(ImplicitForm),
+			view: Object.values(ImplicitView),
+			normals: [false, true],
+			frame: [PlaneFrame.Box, PlaneFrame.Cross]
+		},
+		valid: (v) => !(v.normals && v.view !== "curve" && v.view !== "regions")
+	};
+	defaults() {
+		return {
+			...super.defaults(),
+			form: "ellipse",
+			view: "curve",
+			normals: false,
+			equal: true
+		};
+	}
+	scalar(curve) {
+		return curve.fn ?? named(this.options.form, curve.a ?? 1.5, curve.b ?? 1);
+	}
+	extent() {
+		const span = 1.5 * Math.max(1, ...this.options.data.map((curve) => Math.max(curve.a ?? 1, curve.b ?? 1)));
+		return [[-span * 1.4, span * 1.4], [-span, span]];
+	}
+	plotPlane(ctx, plane) {
+		const { view, normals, data } = this.options;
+		const { x, y, box, width, height } = plane;
+		const first = data[0];
+		const solo = view !== "curve";
+		const field = first ? this.scalar(first) : null;
+		const [nx, ny] = GRID;
+		const pixels = (line) => MathMarks.line(line.map((p) => [x(p[0]), y(p[1])]));
+		const grid = field ? MathNumerics.grid(field, box, nx, ny) : [];
+		const sorted = [...grid].sort((p, q) => p - q);
+		const peak = sorted.length ? Math.max(Math.abs(sorted[Math.floor(sorted.length * .02)]), Math.abs(sorted[Math.floor(sorted.length * .98)])) || 1 : 1;
+		const compress = (v) => Math.sign(v) * Math.sqrt(Math.min(1, Math.abs(v) / peak));
+		const shaded = field && (view === "regions" || view === "bands");
+		const stepped = view === "regions" ? 2 : BANDS;
+		const raster = shaded ? BandRaster.paths(Math.floor(width / 2), Math.floor(height / 2), width, height, (i, j) => {
+			const v = field(x.invert((i + .5) / Math.floor(width / 2) * width), y.invert((j + .5) / Math.floor(height / 2) * height));
+			if (!Number.isFinite(v)) return -1;
+			return view === "regions" ? v < 0 ? 0 : 1 : Math.min(11, Math.floor((compress(v) + 1) / 2 * BANDS));
+		}) : [];
+		const toTone = (band) => view === "regions" ? band ? .28 : -.45 : 2 * (band + .5) / stepped - 1;
+		const cells = ctx.marks("imp-raster", "path", raster, (d) => d.band).attr("fill", (d) => ctx.palette.diverging(toTone(d.band))).attr("shape-rendering", "crispEdges").attr("fill-opacity", view === "regions" ? .55 : .8);
+		ctx.set(cells, { d: (d) => d.d });
+		ctx.hover(cells, (d) => ({
+			title: view === "regions" ? d.band ? "F(x, y) > 0" : "F(x, y) < 0" : "F(x, y) band",
+			rows: [["Tone", MathNumerics.format(toTone(d.band), 2)]]
+		}));
+		const lines = (view === "levels" ? MathNumerics.linspace(-1, 1, 11).filter((t) => t !== 0).map((t) => t * Math.abs(t) * peak) : []).map((level) => ({
+			level,
+			d: MathNumerics.linesOf(grid, box, level, nx, ny).map(pixels).join("")
+		}));
+		const families = MathMarks.stroke(ctx.marks("imp-level", "path", lines, (d) => d.level), (d) => ctx.palette.diverging(Math.sign(d.level) * (.4 + .6 * Math.sqrt(Math.abs(d.level) / peak))), 1.25);
+		ctx.set(families, { d: (d) => d.d });
+		ctx.hover(families, (d) => ({ title: `F(x, y) = ${MathNumerics.format(d.level)}` }));
+		const shown = (solo ? data.slice(0, 1) : data).map((curve) => {
+			const lines = MathNumerics.linesOf(MathNumerics.grid(this.scalar(curve), box, nx, ny), box, 0, nx, ny);
+			return {
+				name: curve.name,
+				scalar: this.scalar(curve),
+				lines
+			};
+		});
+		const curves = MathMarks.stroke(ctx.marks("imp-curve", "path", shown, (d) => d.name), (d) => solo ? ctx.theme.ink : ctx.palette.color(d.name));
+		MathMarks.reveal(ctx, curves, (d) => d.lines.map(pixels).join(""));
+		ctx.hover(curves, (d) => ({
+			title: d.name,
+			rows: [["Set", "F(x, y) = 0"]]
+		}));
+		const arrows = normals ? shown.flatMap((curve) => curve.lines.filter((line) => line.length > 16).flatMap((line, l) => {
+			const every = Math.max(8, Math.floor(line.length / 14));
+			return line.filter((_, i) => i % every === 0).map((p, i) => ({
+				key: `${curve.name}/${l}/${i}`,
+				name: curve.name,
+				p,
+				scalar: curve.scalar
+			}));
+		})) : [];
+		const head = (d) => {
+			const h = .001, [a, b] = d.p;
+			const u = d.scalar(a + h, b) - d.scalar(a - h, b), v = d.scalar(a, b + h) - d.scalar(a, b - h);
+			const n = Math.hypot(u, v) || 1, px = x(a), py = y(b);
+			return MathMarks.arrow(px, py, px + u / n * 16, py - v / n * 16, 6);
+		};
+		const needles = ctx.marks("imp-normal", "path", arrows, (d) => d.key).attr("stroke", (d) => solo ? ctx.theme.ink : ctx.palette.color(d.name)).attr("fill", (d) => solo ? ctx.theme.ink : ctx.palette.color(d.name)).attr("stroke-width", 1.25);
+		ctx.set(needles, { d: head });
+	}
+};
+export { ImplicitForm, ImplicitPlot, ImplicitView };