@altpsyche/maths 0.3.0 → 0.4.1

package/README.md

@@ -18,6 +18,49 @@ const figure = {
 svgMarkup(at(figure, 0.5), viewMatrix(figure.extent, 'contain', 640, 360), 640, 360);
 ```
 
+## Axes and a plotted function
+
+<img src="docs/tangent.svg" width="720" alt="A parabola on a labelled grid, the region under it shaded to a point on the curve, the tangent at that point drawn, and the slope written as a number.">
+
+```ts
+import { axes, coordsOf, group, interval, numberPlane, plot, scaleOf, shape } from '@altpsyche/maths';
+
+const coords = coordsOf(
+  scaleOf(interval(-1, 4), interval(-4.6, 4.6)),
+  scaleOf(interval(-1, 9), interval(-2.4, 2.4))
+);
+
+group('graph', [
+  numberPlane('grid', coords, { stroke: faint, minors: 4 }),
+  axes('axes', coords, { stroke: pen, fill: ink, size: 0.26, tip: 0.18 }),
+  shape('curve', plot(coords, (x) => x * x), { stroke: drawn }),
+]);
+```
+
+A **scale** is the run of numbers an axis counts through and where that run lands in figure units.
+Two of them are a **coords**, and `pointOf` reads a pair of graph numbers as a point. The steps
+between ticks are one, two or five times a power of ten, because those are the numbers a reader
+adds up in their head.
+
+`plot` samples a function at a fixed count and joins the samples with cubics that leave each one at
+the slope the function has there. It cuts the curve where the curve leaves the graph, so a pole
+breaks in two instead of drawing a line up the picture, and the cut end sits on the edge rather
+than a sample short of it. The curve above is cut at x = 3, where the parabola meets the 9 its y
+axis stops at.
+
+`areaUnder` closes the region between a curve and a level line, `riemannBars` draws the bars the
+region is the limit of at the left edge, the right edge or the middle of each one, and `tangentAt`
+lays the tangent along the curve, cut where it leaves the graph. `slopeOf` reads the slope itself,
+which is what the number in the corner is.
+
+<img src="docs/tangent-strip.svg" width="960" alt="Four frames of the same figure side by side, the point walking up the curve and the shaded region growing behind it.">
+
+Four times of one figure, side by side. A moving picture in a README needs a GIF and this package
+has no encoder, so the strip shows the motion in a still.
+
+Both pictures are written by `svgMarkup`, which needs no browser, so `npm run demos` regenerates
+them and a test compares the bytes against the committed files.
+
 ## What it is built on
 
 **A figure at a time is data.** `at(figure, seconds)` is the whole public surface, and it is a
@@ -56,4 +99,4 @@ arcs included, and a command it does not know stops the read rather than being s
 along, and a value walked between keys. That half changes almost never. **Figures and painters**
 are above it. Nothing below the line imports anything above it, and a test says so.
 
-One door, no runtime dependencies. MIT.
+One door. MIT.

package/dist/figure/axis.d.ts

@@ -0,0 +1,75 @@
+import { type GroupNode } from './node.js';
+import { type Coords, type Scale } from './scale.js';
+import type { Fill, Stroke } from './mark.js';
+export interface NumberLineOptions {
+    /** The line, its ticks and the outline of its tips. */
+    stroke: Stroke;
+    /** The labels and the tips. Nothing is written where this is missing. */
+    fill?: Fill;
+    /** How big the labels are, in figure units. Nothing is written where this is
+     * missing. */
+    size?: number;
+    /** Where the line sits on the other axis, in figure units. */
+    at?: number;
+    direction?: 'across' | 'up';
+    /** About how many ticks are wanted. The step is a round number, so the count
+     * that comes back is near this rather than equal to it. */
+    ticks?: number;
+    /** How far a tick reaches across the line in total, half of it either side. */
+    tickLength?: number;
+    /** From the end of a tick to the label's own anchor. */
+    gap?: number;
+    /** How long the head at each end is. Nothing is drawn where this is zero. */
+    tip?: number;
+    /** How wide a head is across its base, against its length. */
+    spread?: number;
+    family?: string;
+    weight?: number;
+    /** Leaves the label at zero out, which is what a second axis crossing here
+     * wants, since both would otherwise write the same number in the same place. */
+    skipZero?: boolean;
+}
+/**
+ * One axis as a group: the line, the ticks under `ticks`, the labels under
+ * `labels`, and the tips under `tips`.
+ *
+ * Each tick and each label is named after the number it shows rather than by its
+ * position in the list. An animation naming a tick then follows that number when
+ * the axis is rebuilt with a different range, where a position would quietly
+ * follow whichever tick had moved into the slot.
+ */
+export declare function numberLine(name: string, scale: Scale, options: NumberLineOptions): GroupNode;
+/** Everything a pair of axes hands to each of its two lines. A figure wanting
+ * the two to differ builds them as two number lines instead, which is what that
+ * call is exported for. */
+export type AxesOptions = Omit<NumberLineOptions, 'at' | 'direction' | 'skipZero'>;
+/**
+ * Two number lines under one group, named `x` and `y`, each crossing the other
+ * at that other's zero.
+ *
+ * Where zero is outside an interval the line sits at the near edge of it instead.
+ * An axis drawn at a zero the graph never reaches is an axis off the picture, and
+ * a reader is left with labels along an edge that has no line on it.
+ */
+export declare function axes(name: string, coords: Coords, options: AxesOptions): GroupNode;
+export interface NumberPlaneOptions {
+    /** The lines standing on the ticks. */
+    stroke: Stroke;
+    /** How many gaps each step is divided into, so one less than this many lines
+     * sit between one tick and the next. Nothing extra is drawn below two. */
+    minors?: number;
+    /** How much of the stroke a minor line is drawn with, since a grid a reader
+     * notices is a grid competing with the curve on top of it. */
+    minorOpacity?: number;
+    ticks?: number;
+}
+/**
+ * The grid behind a graph: a line standing on each tick of both axes, and
+ * fainter lines dividing the gaps between them.
+ *
+ * The minor lines are drawn first and the major ones over them, so a major line
+ * a minor one lands on is the one a reader sees. The stroke is handed down from
+ * the group rather than set on each line, which is what lets the whole grid fade
+ * as one thing.
+ */
+export declare function numberPlane(name: string, coords: Coords, options: NumberPlaneOptions): GroupNode;

package/dist/figure/axis.js

@@ -0,0 +1,133 @@
+/**
+ * A drawn axis: the line, a tick at each of its numbers, and the numbers
+ * written beside them.
+ *
+ * The line takes a direction rather than being rotated into place. A horizontal
+ * axis turned on its side would turn its labels with it, and a reader cannot
+ * read those, so the two directions place their labels differently and both
+ * write them upright.
+ */
+import { interval } from '../values/interval.js';
+import { vec2 } from '../values/vec2.js';
+import { line, polygon } from './path.js';
+import { group, shape, text } from './node.js';
+import { multiplesOn, tickStep, ticksOn } from './ticks.js';
+import { scaled } from './scale.js';
+/** A head pointing along the line, apex at the end and base back along it. */
+function head(apex, back, spread) {
+    const along = vec2.normalize(vec2.sub(apex, back));
+    const across = vec2.scale(vec2.perpendicular(along), (vec2.distance(apex, back) * spread) / 2);
+    return polygon([apex, vec2.add(back, across), vec2.sub(back, across)]);
+}
+/**
+ * One axis as a group: the line, the ticks under `ticks`, the labels under
+ * `labels`, and the tips under `tips`.
+ *
+ * Each tick and each label is named after the number it shows rather than by its
+ * position in the list. An animation naming a tick then follows that number when
+ * the axis is rebuilt with a different range, where a position would quietly
+ * follow whichever tick had moved into the slot.
+ */
+export function numberLine(name, scale, options) {
+    const across = (options.direction ?? 'across') === 'across';
+    const seat = options.at ?? 0;
+    const tip = options.tip ?? 0;
+    const tickLength = options.tickLength ?? options.stroke.width * 8;
+    const size = options.size ?? 0;
+    const gap = options.gap ?? size * 0.35;
+    const { from: low, to: high } = interval.ordered(scale.units);
+    const at = (along, off) => (across ? vec2(along, seat + off) : vec2(seat + off, along));
+    // The line stops where a head begins rather than running under it, because a
+    // line drawn to the point shows through a head that is not fully opaque.
+    const parts = [shape('line', line(at(low + tip, 0), at(high - tip, 0)), { stroke: options.stroke })];
+    if (tip > 0 && options.fill) {
+        const spread = options.spread ?? 0.6;
+        parts.push(group('tips', [
+            shape('low', head(at(low, 0), at(low + tip, 0), spread), { fill: options.fill }),
+            shape('high', head(at(high, 0), at(high - tip, 0), spread), { fill: options.fill }),
+        ]));
+    }
+    const step = tickStep(scale.graph, options.ticks);
+    const marked = ticksOn(scale.graph, options.ticks);
+    const half = tickLength / 2;
+    parts.push(group('ticks', marked.map((tick) => {
+        const along = interval.remap(tick.value, scale.graph, scale.units);
+        return shape(tick.label, line(at(along, -half), at(along, half)), { stroke: options.stroke });
+    })));
+    if (options.fill && size > 0) {
+        // Placed by an anchor and an alignment and never by how wide the text is,
+        // so a long label moves nothing else in the figure.
+        const align = across ? 'middle' : 'end';
+        const baseline = across ? 'hanging' : 'middle';
+        const written = marked.filter((tick) => !(options.skipZero && tick.value === 0));
+        parts.push(group('labels', written.map((tick) => {
+            const along = interval.remap(tick.value, scale.graph, scale.units);
+            return text(tick.label, at(along, -(half + gap)), tick.label, size, {
+                fill: options.fill,
+                family: options.family,
+                weight: options.weight,
+                align,
+                baseline,
+            });
+        })));
+    }
+    return group(name, parts);
+}
+/**
+ * Two number lines under one group, named `x` and `y`, each crossing the other
+ * at that other's zero.
+ *
+ * Where zero is outside an interval the line sits at the near edge of it instead.
+ * An axis drawn at a zero the graph never reaches is an axis off the picture, and
+ * a reader is left with labels along an edge that has no line on it.
+ */
+export function axes(name, coords, options) {
+    const holdsOrigin = interval.holds(coords.x.graph, 0) && interval.holds(coords.y.graph, 0);
+    const seat = (scale) => scaled(scale, interval.clampTo(scale.graph, 0));
+    return group(name, [
+        numberLine('x', coords.x, { ...options, at: seat(coords.y), direction: 'across' }),
+        numberLine('y', coords.y, { ...options, at: seat(coords.x), direction: 'up', skipZero: holdsOrigin }),
+    ]);
+}
+/** Whether a value is a whole number of steps from zero, which is what tells a
+ * minor line it is standing where a major one already is. */
+function onStep(value, step) {
+    return Math.abs(value / step - Math.round(value / step)) < 1e-9;
+}
+/** Lines of constant x reaching the full height, and of constant y reaching the
+ * full width, at every multiple of the step. */
+function gridLines(coords, step, along, skipping) {
+    const scale = along === 'x' ? coords.x : coords.y;
+    const other = interval.ordered(along === 'x' ? coords.y.units : coords.x.units);
+    const ends = (at) => along === 'x' ? [vec2(at, other.from), vec2(at, other.to)] : [vec2(other.from, at), vec2(other.to, at)];
+    return multiplesOn(scale.graph, step)
+        .filter((value) => !(skipping && onStep(value, skipping)))
+        .map((value) => {
+        const [from, to] = ends(scaled(scale, value));
+        return shape(String(value), line(from, to), {});
+    });
+}
+/**
+ * The grid behind a graph: a line standing on each tick of both axes, and
+ * fainter lines dividing the gaps between them.
+ *
+ * The minor lines are drawn first and the major ones over them, so a major line
+ * a minor one lands on is the one a reader sees. The stroke is handed down from
+ * the group rather than set on each line, which is what lets the whole grid fade
+ * as one thing.
+ */
+export function numberPlane(name, coords, options) {
+    const step = { x: tickStep(coords.x.graph, options.ticks), y: tickStep(coords.y.graph, options.ticks) };
+    const minors = Math.max(1, Math.round(options.minors ?? 1));
+    const parts = [];
+    if (minors > 1 && step.x > 0 && step.y > 0) {
+        parts.push(group('minors', [
+            group('x', gridLines(coords, step.x / minors, 'x', step.x)),
+            group('y', gridLines(coords, step.y / minors, 'y', step.y)),
+        ], { style: { stroke: options.stroke, opacity: options.minorOpacity ?? 0.4 } }));
+    }
+    parts.push(group('majors', [group('x', gridLines(coords, step.x, 'x')), group('y', gridLines(coords, step.y, 'y'))], {
+        style: { stroke: options.stroke },
+    }));
+    return group(name, parts);
+}

package/dist/figure/plot.d.ts

@@ -0,0 +1,100 @@
+/**
+ * A function of one number drawn as a curve.
+ *
+ * The function is sampled at a fixed number of places and the samples are joined
+ * by cubics that leave each one at the slope the function has there. Joining them
+ * by straight lines instead is what makes a plotted sine look faceted, and the
+ * slope costs nothing to work out because it comes from samples already taken.
+ *
+ * A curve is cut where it leaves the graph. A pole otherwise draws as a line
+ * straight up the picture, and the coordinates on either side of it run to
+ * numbers a painter has nowhere to put.
+ *
+ * The count is fixed and the curve is never subdivided by how much it bends.
+ * Subdivision hands back a different number of points as the curve changes, and
+ * one path is walked into another by pairing their points, so a curve that
+ * resamples itself between frames could not be morphed into anything.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Coords } from './scale.js';
+import { type GroupNode } from './node.js';
+import type { Fill, Stroke } from './mark.js';
+import { type Path } from './path.js';
+export interface PlotOptions {
+    /** How many pieces the curve is cut into. */
+    samples?: number;
+    /** The run of x the curve is drawn over, which is the whole width of the graph
+     * where it is left out. */
+    over?: Interval;
+}
+/**
+ * The curve of a function over a run of x, in the figure's own units, as one
+ * subpath per stretch of it that is on the graph.
+ *
+ * Each piece is a Hermite cubic written as a Bézier: the controls sit a third of
+ * the way along in x and carry the sample's own slope, which is the placement
+ * that makes the cubic pass through both samples at both slopes.
+ */
+export declare function plot(coords: Coords, of: (x: number) => number, options?: PlotOptions): Path;
+export interface AreaOptions extends PlotOptions {
+    /** The height the region is measured down to, which is the axis itself where
+     * it is left out. A height off the graph sits at the near edge instead. */
+    baseline?: number;
+}
+/**
+ * The region between a curve and a level line, closed, as one subpath per
+ * stretch of the curve that is on the graph.
+ *
+ * The curve is the same one `plot` draws over the same run, so the top of the
+ * region and the curve laid over it are the same geometry rather than two
+ * samplings that agree to within a sample.
+ */
+export declare function areaUnder(coords: Coords, of: (x: number) => number, over: Interval, options?: AreaOptions): Path;
+export interface BarsOptions {
+    fill?: Fill;
+    stroke?: Stroke;
+    /** How many bars the run is cut into. */
+    bars?: number;
+    /** The run of x the bars cover, which is the whole width of the graph where it
+     * is left out. */
+    over?: Interval;
+    /** Where in each bar its height is read: at the left edge, the right edge or
+     * the middle. The three are what a reader is shown to see that the first is
+     * always short and the second always over. */
+    height?: 'left' | 'right' | 'middle';
+    /** The level the bars stand on. */
+    baseline?: number;
+}
+/**
+ * The bars under a curve, each one named by its place in the run so a stagger
+ * can reach them one at a time.
+ *
+ * A bar whose top is off the graph is cut at the edge, and a bar whose height is
+ * not a number is left out. The style sits on the group rather than on each bar,
+ * which is what lets the whole run fade as one thing.
+ */
+export declare function riemannBars(name: string, coords: Coords, of: (x: number) => number, options?: BarsOptions): GroupNode;
+/**
+ * The slope of a function at a point, from the central difference either side of
+ * it.
+ *
+ * The difference either side rather than one side is what makes the error fall
+ * as the step squared instead of the step, and it costs the same two calls.
+ */
+export declare function slopeOf(of: (x: number) => number, x: number, step?: number): number;
+export interface TangentOptions {
+    /** How far the line reaches either side of the point, in graph units. */
+    reach?: number;
+    /** The step the slope is read over, for a function whose own scale asks for a
+     * different one. */
+    step?: number;
+}
+/**
+ * The tangent to a curve at a point, as a straight line held inside the graph.
+ *
+ * The line is cut where it leaves the graph rather than sampled and broken like
+ * a curve, because a straight line crosses each edge once and the crossing is
+ * arithmetic rather than a search. A tangent at a steep place otherwise runs the
+ * width of the picture and out of it.
+ */
+export declare function tangentAt(coords: Coords, of: (x: number) => number, x: number, options?: TangentOptions): Path;

package/dist/figure/plot.js

@@ -0,0 +1,264 @@
+/**
+ * A function of one number drawn as a curve.
+ *
+ * The function is sampled at a fixed number of places and the samples are joined
+ * by cubics that leave each one at the slope the function has there. Joining them
+ * by straight lines instead is what makes a plotted sine look faceted, and the
+ * slope costs nothing to work out because it comes from samples already taken.
+ *
+ * A curve is cut where it leaves the graph. A pole otherwise draws as a line
+ * straight up the picture, and the coordinates on either side of it run to
+ * numbers a painter has nowhere to put.
+ *
+ * The count is fixed and the curve is never subdivided by how much it bends.
+ * Subdivision hands back a different number of points as the curve changes, and
+ * one path is walked into another by pairing their points, so a curve that
+ * resamples itself between frames could not be morphed into anything.
+ */
+import { interval } from '../values/interval.js';
+import { vec2 } from '../values/vec2.js';
+import { pointOf, scaled } from './scale.js';
+import { group, shape } from './node.js';
+import { line, polygon, straight } from './path.js';
+/**
+ * How many pieces a curve is cut into when a figure does not say.
+ *
+ * A sine over two turns at this count leaves the drawn curve within 3.3e-4
+ * figure units of the true one, which is under a tenth of a pixel on the largest
+ * surface anything here is drawn at.
+ */
+const SAMPLES = 96;
+/**
+ * The slope at each sample of one run, from the central difference of its
+ * neighbours, which is the tangent a Catmull-Rom spline uses.
+ *
+ * An end with evenly spaced neighbours takes the three-point one-sided
+ * difference, which is second order like the middle and exact for a quadratic.
+ * An end that was cut at the edge of the graph is not evenly spaced, so it takes
+ * the two-point difference instead: measured on a parabola at 64 samples, the
+ * three-point ends leave an uncut curve exact where the two-point ends leave it
+ * 3.7e-4 figure units out.
+ */
+function slopes(xs, ys) {
+    const last = xs.length - 1;
+    if (last < 1)
+        return [0];
+    const even = (a, b, c) => Math.abs((b - a) - (c - b)) < Math.abs(c - a) * 1e-9;
+    const out = [];
+    for (let at = 0; at <= last; at++) {
+        if (last < 2)
+            out.push((ys[last] - ys[0]) / (xs[last] - xs[0]));
+        else if (at === 0) {
+            out.push(even(xs[0], xs[1], xs[2])
+                ? (-3 * ys[0] + 4 * ys[1] - ys[2]) / (xs[2] - xs[0])
+                : (ys[1] - ys[0]) / (xs[1] - xs[0]));
+        }
+        else if (at === last) {
+            out.push(even(xs[last - 2], xs[last - 1], xs[last])
+                ? (3 * ys[last] - 4 * ys[last - 1] + ys[last - 2]) / (xs[last] - xs[last - 2])
+                : (ys[last] - ys[last - 1]) / (xs[last] - xs[last - 1]));
+        }
+        else
+            out.push((ys[at + 1] - ys[at - 1]) / (xs[at + 1] - xs[at - 1]));
+    }
+    return out;
+}
+/** How many times the gap either side of the edge is halved when looking for the
+ * place the curve crosses it. Twenty-four leaves it within a millionth of one
+ * sample's width. */
+const HALVINGS = 24;
+/**
+ * The place between a sample on the graph and a sample off it where the curve
+ * crosses the edge, by halving the gap between them.
+ *
+ * The y it hands back is held on the edge rather than taken from the function,
+ * so the cut end sits exactly on the boundary instead of a millionth past it.
+ */
+function crossing(of, drawable, bounds, inside, outside) {
+    let near = inside;
+    let far = outside;
+    for (let halving = 0; halving < HALVINGS; halving++) {
+        const middle = (near + far) / 2;
+        if (drawable(of(middle)))
+            near = middle;
+        else
+            far = middle;
+    }
+    return { x: near, y: interval.clampTo(bounds, of(near)) };
+}
+/**
+ * The curve of a function over a run of x, in the figure's own units, as one
+ * subpath per stretch of it that is on the graph.
+ *
+ * Each piece is a Hermite cubic written as a Bézier: the controls sit a third of
+ * the way along in x and carry the sample's own slope, which is the placement
+ * that makes the cubic pass through both samples at both slopes.
+ */
+export function plot(coords, of, options = {}) {
+    const samples = Math.max(1, Math.round(options.samples ?? SAMPLES));
+    const { from, to } = interval.ordered(options.over ?? coords.x.graph);
+    if (!(to > from))
+        return [];
+    const grain = ((to - from) / samples) * 1e-9;
+    const drawable = (y) => Number.isFinite(y) && interval.holds(coords.y.graph, y);
+    const xs = [];
+    const ys = [];
+    const on = [];
+    for (let at = 0; at <= samples; at++) {
+        const x = from + ((to - from) * at) / samples;
+        const y = of(x);
+        xs.push(x);
+        ys.push(y);
+        on.push(drawable(y));
+    }
+    const path = [];
+    let at = 0;
+    while (at <= samples) {
+        if (!on[at]) {
+            at++;
+            continue;
+        }
+        let end = at;
+        while (end + 1 <= samples && on[end + 1])
+            end++;
+        const runX = xs.slice(at, end + 1);
+        const runY = ys.slice(at, end + 1);
+        if (at > 0) {
+            const cut = crossing(of, drawable, coords.y.graph, xs[at], xs[at - 1]);
+            // A sample sitting exactly on the edge leaves nothing between it and the
+            // crossing, and a piece of no width has no slope to leave at.
+            if (xs[at] - cut.x > grain) {
+                runX.unshift(cut.x);
+                runY.unshift(cut.y);
+            }
+        }
+        if (end < samples) {
+            const cut = crossing(of, drawable, coords.y.graph, xs[end], xs[end + 1]);
+            if (cut.x - xs[end] > grain) {
+                runX.push(cut.x);
+                runY.push(cut.y);
+            }
+        }
+        if (runX.length > 1) {
+            const slope = slopes(runX, runY);
+            const curves = [];
+            for (let piece = 0; piece + 1 < runX.length; piece++) {
+                const reach = (runX[piece + 1] - runX[piece]) / 3;
+                curves.push({
+                    control1: pointOf(coords, runX[piece] + reach, runY[piece] + reach * slope[piece]),
+                    control2: pointOf(coords, runX[piece + 1] - reach, runY[piece + 1] - reach * slope[piece + 1]),
+                    to: pointOf(coords, runX[piece + 1], runY[piece + 1]),
+                });
+            }
+            path.push({ start: pointOf(coords, runX[0], runY[0]), curves, closed: false });
+        }
+        at = end + 1;
+    }
+    return path;
+}
+/**
+ * The region between a curve and a level line, closed, as one subpath per
+ * stretch of the curve that is on the graph.
+ *
+ * The curve is the same one `plot` draws over the same run, so the top of the
+ * region and the curve laid over it are the same geometry rather than two
+ * samplings that agree to within a sample.
+ */
+export function areaUnder(coords, of, over, options = {}) {
+    const foot = scaled(coords.y, interval.clampTo(coords.y.graph, options.baseline ?? 0));
+    return plot(coords, of, { ...options, over }).map((top) => {
+        const last = top.curves.length > 0 ? top.curves[top.curves.length - 1].to : top.start;
+        const under = vec2(last.x, foot);
+        const back = vec2(top.start.x, foot);
+        return {
+            start: top.start,
+            curves: [...top.curves, straight(last, under), straight(under, back), straight(back, top.start)],
+            closed: true,
+        };
+    });
+}
+/**
+ * The bars under a curve, each one named by its place in the run so a stagger
+ * can reach them one at a time.
+ *
+ * A bar whose top is off the graph is cut at the edge, and a bar whose height is
+ * not a number is left out. The style sits on the group rather than on each bar,
+ * which is what lets the whole run fade as one thing.
+ */
+export function riemannBars(name, coords, of, options = {}) {
+    const bars = Math.max(1, Math.round(options.bars ?? 8));
+    const { from, to } = interval.ordered(options.over ?? coords.x.graph);
+    const foot = interval.clampTo(coords.y.graph, options.baseline ?? 0);
+    const read = options.height ?? 'left';
+    const children = [];
+    for (let bar = 0; bar < bars; bar++) {
+        const left = from + ((to - from) * bar) / bars;
+        const right = from + ((to - from) * (bar + 1)) / bars;
+        const x = read === 'left' ? left : read === 'right' ? right : (left + right) / 2;
+        const y = of(x);
+        if (!Number.isFinite(y))
+            continue;
+        const top = interval.clampTo(coords.y.graph, y);
+        // Built from its four corners rather than from a corner and a size. A bar
+        // whose top is held on the graph's own edge has that edge as an exact
+        // number, and adding a height back on to the near corner overshoots it.
+        const corner = pointOf(coords, left, foot);
+        const far = pointOf(coords, right, top);
+        children.push(shape(String(bar), polygon([corner, vec2(far.x, corner.y), far, vec2(corner.x, far.y)]), {}));
+    }
+    return group(name, children, { style: { fill: options.fill, stroke: options.stroke } });
+}
+/**
+ * The step the central difference is taken over, against the size of x.
+ *
+ * The cube root of the smallest gap between two doubles is the step where the
+ * two errors in a central difference are the same size: the formula's own error
+ * falls as the step squared and the rounding error rises as one over the step.
+ */
+const STEP = Math.cbrt(Number.EPSILON);
+/**
+ * The slope of a function at a point, from the central difference either side of
+ * it.
+ *
+ * The difference either side rather than one side is what makes the error fall
+ * as the step squared instead of the step, and it costs the same two calls.
+ */
+export function slopeOf(of, x, step = STEP * Math.max(Math.abs(x), 1)) {
+    return (of(x + step) - of(x - step)) / (2 * step);
+}
+/**
+ * The tangent to a curve at a point, as a straight line held inside the graph.
+ *
+ * The line is cut where it leaves the graph rather than sampled and broken like
+ * a curve, because a straight line crosses each edge once and the crossing is
+ * arithmetic rather than a search. A tangent at a steep place otherwise runs the
+ * width of the picture and out of it.
+ */
+export function tangentAt(coords, of, x, options = {}) {
+    const reach = options.reach ?? interval.span(coords.x.graph) / 8;
+    const height = of(x);
+    const slope = slopeOf(of, x, options.step);
+    if (!Number.isFinite(height) || !Number.isFinite(slope))
+        return [];
+    const graphX = interval.ordered(coords.x.graph);
+    const graphY = interval.ordered(coords.y.graph);
+    let low = Math.max(x - reach, graphX.from);
+    let high = Math.min(x + reach, graphX.to);
+    if (slope === 0) {
+        if (!interval.holds(graphY, height))
+            return [];
+    }
+    else {
+        const atY = (y) => x + (y - height) / slope;
+        const first = atY(graphY.from);
+        const second = atY(graphY.to);
+        low = Math.max(low, Math.min(first, second));
+        high = Math.min(high, Math.max(first, second));
+    }
+    if (!(high > low))
+        return [];
+    // Held on the graph so an end cut at an edge sits on it rather than a rounding
+    // error past it.
+    const at = (t) => pointOf(coords, t, interval.clampTo(graphY, height + slope * (t - x)));
+    return line(at(low), at(high));
+}

package/dist/figure/scale.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The mapping from the numbers on an axis to places in a figure.
+ *
+ * A scale is two intervals: the run of numbers a graph counts through, and where
+ * that run lands in the figure's own units. Two of them together turn a pair of
+ * graph numbers into a point.
+ *
+ * The mapping is a value a caller holds rather than something read back out of a
+ * drawn group. Axes draw two lines and a plotted curve needs the mapping, so a
+ * curve drawn over axes that were never drawn has to work.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Vec2 } from '../values/vec2.js';
+export interface Scale {
+    /** The numbers the axis counts through. */
+    readonly graph: Interval;
+    /** Where those numbers land, in the figure's own units. */
+    readonly units: Interval;
+}
+export declare function scaleOf(graph: Interval, units: Interval): Scale;
+/** A number on the axis, as a place in the figure's own units. */
+export declare function scaled(scale: Scale, value: number): number;
+/** A place in the figure's own units, as a number on the axis, which is what a
+ * reader pointing at the picture is asking for. */
+export declare function unscaled(scale: Scale, place: number): number;
+export interface Coords {
+    readonly x: Scale;
+    readonly y: Scale;
+}
+export declare function coordsOf(x: Scale, y: Scale): Coords;
+/** A pair of graph numbers as a point in the figure's own units. */
+export declare function pointOf(coords: Coords, x: number, y: number): Vec2;

package/dist/figure/scale.js

@@ -0,0 +1,32 @@
+/**
+ * The mapping from the numbers on an axis to places in a figure.
+ *
+ * A scale is two intervals: the run of numbers a graph counts through, and where
+ * that run lands in the figure's own units. Two of them together turn a pair of
+ * graph numbers into a point.
+ *
+ * The mapping is a value a caller holds rather than something read back out of a
+ * drawn group. Axes draw two lines and a plotted curve needs the mapping, so a
+ * curve drawn over axes that were never drawn has to work.
+ */
+import { interval } from '../values/interval.js';
+import { vec2 } from '../values/vec2.js';
+export function scaleOf(graph, units) {
+    return { graph, units };
+}
+/** A number on the axis, as a place in the figure's own units. */
+export function scaled(scale, value) {
+    return interval.remap(value, scale.graph, scale.units);
+}
+/** A place in the figure's own units, as a number on the axis, which is what a
+ * reader pointing at the picture is asking for. */
+export function unscaled(scale, place) {
+    return interval.remap(place, scale.units, scale.graph);
+}
+export function coordsOf(x, y) {
+    return { x, y };
+}
+/** A pair of graph numbers as a point in the figure's own units. */
+export function pointOf(coords, x, y) {
+    return vec2(scaled(coords.x, x), scaled(coords.y, y));
+}

package/dist/figure/ticks.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the marks along an axis go, and what is written under each one.
+ *
+ * A reader adds up an axis in their head, so the steps between its ticks have to
+ * be numbers a head adds: one, two or five times a power of ten. That is the
+ * whole of the choice here, and the rest of this file is walking the interval in
+ * those steps and writing each one down without floating point noise in it.
+ */
+import { type Interval } from '../values/interval.js';
+export interface Tick {
+    /** In the graph's own units, rounded to the decimals its own label shows, so
+     * the number drawn and the number placed are the same number. */
+    readonly value: number;
+    readonly label: string;
+}
+/**
+ * The gap between one tick and the next for an interval that wants about this
+ * many of them.
+ *
+ * The published version rounds the whole span before dividing it, which suits a
+ * graph free to move its own bounds outward to the next nice number. An axis
+ * here is given its bounds and keeps them, so the span is divided as it stands:
+ * over eight ranges that turned a worst count error of four ticks into one.
+ */
+export declare function tickStep(bounds: Interval, about?: number): number;
+/**
+ * A tick's value written out, with as many decimals as its step needs and no
+ * more.
+ *
+ * A step of a fifth reaches three fifths as 0.6000000000000001, and printing the
+ * number as it stands puts that in the picture. The decimal count comes from the
+ * step rather than from the value, so every label along one axis is written to
+ * the same width.
+ */
+export declare function labelFor(value: number, step: number): string;
+/**
+ * Every multiple of the step inside the interval, from its lower bound upward,
+ * whichever way round the interval was given.
+ *
+ * The values are counted as multiples rather than reached by adding the step
+ * over and over, because the additions drift and the last one then misses the
+ * bound it sits on.
+ */
+export declare function multiplesOn(bounds: Interval, step: number): readonly number[];
+/** Every tick inside the interval, with the number each one shows. */
+export declare function ticksOn(bounds: Interval, about?: number): readonly Tick[];

package/dist/figure/ticks.js

@@ -0,0 +1,97 @@
+/**
+ * Where the marks along an axis go, and what is written under each one.
+ *
+ * A reader adds up an axis in their head, so the steps between its ticks have to
+ * be numbers a head adds: one, two or five times a power of ten. That is the
+ * whole of the choice here, and the rest of this file is walking the interval in
+ * those steps and writing each one down without floating point noise in it.
+ */
+import { interval as intervalOf } from '../values/interval.js';
+/**
+ * The nearest one, two, five or ten times a power of ten, which is Heckbert's
+ * nice numbers from Graphics Gems.
+ *
+ * Rounding up gives a step that never asks for more ticks than were wanted;
+ * rounding to nearest gives the count closest to it, which is what an axis
+ * wants because a step slightly too small crowds the labels.
+ */
+function niceNumber(value, toNearest) {
+    const power = Math.floor(Math.log10(value));
+    const decade = 10 ** power;
+    const leading = value / decade;
+    const nice = toNearest
+        ? leading < 1.5
+            ? 1
+            : leading < 3
+                ? 2
+                : leading < 7
+                    ? 5
+                    : 10
+        : leading <= 1
+            ? 1
+            : leading <= 2
+                ? 2
+                : leading <= 5
+                    ? 5
+                    : 10;
+    return nice * decade;
+}
+/**
+ * The gap between one tick and the next for an interval that wants about this
+ * many of them.
+ *
+ * The published version rounds the whole span before dividing it, which suits a
+ * graph free to move its own bounds outward to the next nice number. An axis
+ * here is given its bounds and keeps them, so the span is divided as it stands:
+ * over eight ranges that turned a worst count error of four ticks into one.
+ */
+export function tickStep(bounds, about = 6) {
+    const span = intervalOf.span(bounds);
+    if (!Number.isFinite(span) || span === 0)
+        return 0;
+    return niceNumber(span / Math.max(1, Math.round(about) - 1), true);
+}
+/**
+ * A tick's value written out, with as many decimals as its step needs and no
+ * more.
+ *
+ * A step of a fifth reaches three fifths as 0.6000000000000001, and printing the
+ * number as it stands puts that in the picture. The decimal count comes from the
+ * step rather than from the value, so every label along one axis is written to
+ * the same width.
+ */
+export function labelFor(value, step) {
+    const decimals = step > 0 ? Math.max(0, -Math.floor(Math.log10(step))) : 0;
+    const written = value.toFixed(decimals);
+    // A value a hair below zero rounds to a signed zero, which prints its minus.
+    return Number(written) === 0 ? (0).toFixed(decimals) : written;
+}
+/** How far past a bound a value may sit and still count as on it, against the
+ * step, so a tick landing on its own end is not lost to a rounding error. */
+const ON_THE_BOUND = 1e-9;
+/**
+ * Every multiple of the step inside the interval, from its lower bound upward,
+ * whichever way round the interval was given.
+ *
+ * The values are counted as multiples rather than reached by adding the step
+ * over and over, because the additions drift and the last one then misses the
+ * bound it sits on.
+ */
+export function multiplesOn(bounds, step) {
+    if (!(step > 0))
+        return [];
+    const { from, to } = intervalOf.ordered(bounds);
+    const slack = step * ON_THE_BOUND;
+    const values = [];
+    for (let count = Math.ceil(from / step - ON_THE_BOUND); count * step <= to + slack; count++) {
+        // Twelve digits drops the noise the multiplication leaves in the last few
+        // and shifts no value a step of any size could land on.
+        values.push(Number((count * step).toPrecision(12)));
+    }
+    return values;
+}
+/** Every tick inside the interval, with the number each one shows. */
+export function ticksOn(bounds, about = 6) {
+    const step = tickStep(bounds, about);
+    return multiplesOn(bounds, step).map((value) => ({ value, label: labelFor(value, step) }));
+}

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { vec2 } from './values/vec2.js';
 export type { Vec2 } from './values/vec2.js';
 export { vec3 } from './values/vec3.js';
 export type { Vec3 } from './values/vec3.js';
+export { interval } from './values/interval.js';
+export type { Interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
 export type { Mat3 } from './values/mat3.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
@@ -24,6 +26,14 @@ export { pathFromData } from './figure/path-data.js';
 export type { Colour, Fill, Mark, PathMark, Stroke, TextMark } from './figure/mark.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export type { Extent, ExtentChoice, Fit } from './figure/extent.js';
+export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
+export type { AreaOptions, BarsOptions, PlotOptions, TangentOptions } from './figure/plot.js';
+export { axes, numberLine, numberPlane } from './figure/axis.js';
+export type { AxesOptions, NumberLineOptions, NumberPlaneOptions } from './figure/axis.js';
+export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
+export type { Coords, Scale } from './figure/scale.js';
+export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
+export type { Tick } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
 export type { GroupNode, Node, ShapeNode, Style, TextNode, TextOptions } from './figure/node.js';
 export { fadeIn, fadeOut, fadeTo, draw, morph, moveBy } from './figure/animation.js';

package/dist/index.js

@@ -11,11 +11,16 @@ export { clamp, inverseLerp, lerp, remap } from './values/scalar.js';
 export { curveFor, easeIn, easeOut, linear, smoothstep } from './values/ease.js';
 export { vec2 } from './values/vec2.js';
 export { vec3 } from './values/vec3.js';
+export { interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
 export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
+export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
+export { axes, numberLine, numberPlane } from './figure/axis.js';
+export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
+export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
 export { fadeIn, fadeOut, fadeTo, draw, morph, moveBy } from './figure/animation.js';
 export { Timeline } from './figure/timeline.js';

package/dist/values/interval.d.ts

@@ -0,0 +1,42 @@
+export interface Interval {
+    readonly from: number;
+    readonly to: number;
+}
+declare function makeInterval(from: number, to: number): Interval;
+/** How far the interval reaches, without a sign, so an interval given either way
+ * round reports the same width. */
+declare function span(interval: Interval): number;
+/** Both bounds counting as inside, whichever way round they were given. */
+declare function holds(interval: Interval, value: number): boolean;
+/** The same two bounds with the lower one first, for anything that has to walk
+ * from one end to the other and would otherwise step backwards. */
+declare function ordered(interval: Interval): Interval;
+/** A fraction of the way along, and past either bound when the fraction is
+ * outside zero to one. */
+declare function at(interval: Interval, along: number): number;
+/** Held inside the two bounds, whichever way round they were given. */
+declare function clampTo(interval: Interval, value: number): number;
+/**
+ * The place a value holds in one interval, read at the same place in another.
+ *
+ * A source of no width has no place to read, so this hands back the target's
+ * first bound rather than an infinity that then spreads through every coordinate
+ * built on it.
+ */
+declare function remap(value: number, source: Interval, target: Interval): number;
+/**
+ * The interval calls under one name, so a call site says which kind of thing it
+ * is reading and an import line says what these operate on.
+ *
+ * The width is not called `length`: a function's own `length` is how many
+ * arguments it takes, it is not writable, and assigning one throws.
+ */
+export declare const interval: typeof makeInterval & {
+    span: typeof span;
+    holds: typeof holds;
+    ordered: typeof ordered;
+    at: typeof at;
+    clampTo: typeof clampTo;
+    remap: typeof remap;
+};
+export {};

package/dist/values/interval.js

@@ -0,0 +1,66 @@
+/**
+ * A run of numbers from one bound to the other, and the arithmetic that reads
+ * one against another.
+ *
+ * This is what a graph's own units are given in, and what a figure's units are
+ * given in, so mapping a value from a graph onto a picture is one interval read
+ * against another rather than four loose numbers passed around together.
+ *
+ * A bound above its partner is allowed everywhere here. An axis that counts down
+ * the screen and a scale that reverses a direction are both an interval given
+ * the other way round, and neither is a mistake to be corrected.
+ */
+import { clamp, lerp, remap as remapNumber } from './scalar.js';
+function makeInterval(from, to) {
+    return { from, to };
+}
+/** How far the interval reaches, without a sign, so an interval given either way
+ * round reports the same width. */
+function span(interval) {
+    return Math.abs(interval.to - interval.from);
+}
+/** Both bounds counting as inside, whichever way round they were given. */
+function holds(interval, value) {
+    const low = Math.min(interval.from, interval.to);
+    const high = Math.max(interval.from, interval.to);
+    return value >= low && value <= high;
+}
+/** The same two bounds with the lower one first, for anything that has to walk
+ * from one end to the other and would otherwise step backwards. */
+function ordered(interval) {
+    return interval.from <= interval.to ? interval : { from: interval.to, to: interval.from };
+}
+/** A fraction of the way along, and past either bound when the fraction is
+ * outside zero to one. */
+function at(interval, along) {
+    return lerp(interval.from, interval.to, along);
+}
+/** Held inside the two bounds, whichever way round they were given. */
+function clampTo(interval, value) {
+    return clamp(value, interval.from, interval.to);
+}
+/**
+ * The place a value holds in one interval, read at the same place in another.
+ *
+ * A source of no width has no place to read, so this hands back the target's
+ * first bound rather than an infinity that then spreads through every coordinate
+ * built on it.
+ */
+function remap(value, source, target) {
+    return remapNumber(value, source.from, source.to, target.from, target.to);
+}
+/**
+ * The interval calls under one name, so a call site says which kind of thing it
+ * is reading and an import line says what these operate on.
+ *
+ * The width is not called `length`: a function's own `length` is how many
+ * arguments it takes, it is not writable, and assigning one throws.
+ */
+export const interval = Object.assign(makeInterval, {
+    span,
+    holds,
+    ordered,
+    at,
+    clampTo,
+    remap,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altpsyche/maths",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
   "license": "MIT",
   "author": "Siva",
@@ -36,6 +36,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
+    "demos": "tsc -p tsconfig.demos.json && node .demos/demos/write.js",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "prepack": "npm run build"
   },