@altpsyche/maths 0.9.5 → 0.11.0

package/README.md

@@ -20,7 +20,7 @@ svgMarkup(at(figure, 0.5), viewMatrix(figure.extent, 'contain', 640, 360), 640,
 
 ## 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 under the typeset rule it comes from.">
+<img src="docs/tangent.svg" width="720" alt="A parabola on a labelled grid over a field of small blue arrows, the region under it shaded to a point on the curve, the tangent at that point drawn, and the slope written as a number under the typeset rule it comes from.">
 
 The picture arrives rather than appearing. The grid fades, the axes draw on, their labels come in one
 after another, the curve draws, the dot grows out of the origin, and the dot is pointed at where the
@@ -60,7 +60,7 @@ region is the limit of at the left edge, the right edge or the middle of each on
 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, the shaded region growing behind it, the typeset rule in the corner changing from a slope of nothing to one that depends on x, and a brace measuring the rise in the last frame.">
+<img src="docs/tangent-strip.svg" width="960" alt="Four frames of the same figure side by side, the point walking up the curve over the field of slope arrows, the shaded region growing behind it, the typeset rule in the corner changing from a slope of nothing to one that depends on x, and a brace measuring the rise in the last frame.">
 
 Four times of one figure, side by side: the picture arrived, the beat at the stationary point, half
 way up, and the top. A moving picture in a README needs a GIF and this package has no encoder, so the
@@ -241,6 +241,84 @@ The quarters of the turn. The whole turn is left off the strip because it draws
 nothing draws: this is the first figure here to declare itself a loop, and `loops(figure)` is the gate
 behind that flag, comparing the marks at the duration against the marks at zero.
 
+## A surface in space
+
+<img src="docs/surface.svg" width="720" alt="A saddle-shaped surface drawn as a grid of shaded cells, with a flat pane cutting through it at one height and the two branches of the curve where they meet drawn in orange along the surface. Blue arrows across the pane show the way the saddle falls and three green runs of steepest descent are drawn on it. Three axes with their numbers stand behind it and the equation of the surface is typeset in the top left.">
+
+A figure's camera is a value the caller holds. `camera3({ eye, target, up, projection })` answers
+where a point in space lands in the figure's own units, how far off it is along the way the camera
+looks, and whether it is in front of the eye at all. `polyline3`, `dot3`, `text3` and `surface3` take
+points in space and hand back the same flat nodes everything else here draws, so `fadeIn` and `draw`
+reach a mark in space with no change to either of them. Nothing in the marks, the tree, the flattening
+or the two painters knows that space exists.
+
+`space(name, items, camera)` puts the pieces in the order they are painted, near over far. That is
+the painter's algorithm, and what it cannot do is worth knowing before it is used: two pieces that
+pass through each other have no one order at all. The answer for those is smaller pieces, which is why
+`surfaceCells` cuts a surface into a grid and why the saddle and the pane above are sorted together
+rather than one after the other.
+
+`sectionOf` finds the curve where a plane cuts a surface, by marching squares over the grid the
+surface is already drawn from. Every point it finds lies on the plane exactly, because signed distance
+to a plane changes evenly along a straight line. What it does not lie on exactly is the surface: it
+sits on the chord between two samples of it, 4.870e-4 of a unit off at the resolution the demo uses,
+and halving the cell size quarters that.
+
+The camera is driven by a track and never by an animation, which is the call the flat demo's walk
+already made: a span's eased fraction and a track's value are unrelated numbers, and a camera on one
+with a surface on the other would be two clocks free to disagree.
+
+<img src="docs/surface-strip.svg" width="820" alt="Four frames in two rows, showing the same saddle, pane, field arrows and runs of descent from four points around one orbit of the eye.">
+
+The quarters of one orbit. The eye comes back to where it started, which the gate holds by comparing
+the marks at the end of the entrance against the marks one orbit later, mark for mark by name.
+
+## Fields and streamlines
+
+`vectorField(name, coords, of, options)` samples a grid over a graph and draws an arrow at each
+sample. A field is a function from a place to a vector, so nothing here stores one. How long an arrow
+is and what colour it is are both the author's, taken from the magnitude of the vector at that
+sample: a field drawn at its true lengths is unreadable the moment two samples differ by a factor of
+ten. The count is fixed by the resolution and never by the field, so a gate can hold it. An arrow's
+length is in figure units, like the width of its shaft, and only its direction comes from the
+mapping of its own vector. The flat demo's own axes count at 1.84 and 0.415 figure units to the graph
+unit, and a length in graph units would draw a level arrow there 4.43 times longer than an upright one
+beside it.
+
+The arrows above are the slope field of the curve they sit under, read from the curve itself with
+`slopeOf`. `streamlineOf(of, from, options)` walks Runge-Kutta 4 through a field and hands back the
+points, and the run through the origin of that field never leaves the plotted parabola by more than
+4.689e-10 of a figure unit. Two answers to one question.
+
+The step is a distance rather than a time: the field is read as a direction and its magnitude decides
+nothing about how far a step moves, which keeps the points evenly spaced in a field whose strength
+changes across the picture. It is fixed and never adaptive, because an adaptive step hands back a
+different number of points as the field changes, and one path is walked into another by pairing their
+points. Three rules stop a run and each has a measurement: a seed outside the region comes back as one
+point, a field that is nothing everywhere stops at one point rather than at its cap, and a run leaving
+its region stops at the last point inside it. In the field that turns a point about the origin,
+halving the step divides the error along the curve by 15.1 and then 15.6, which is the fourth order
+the integrator is named for.
+
+`arrow3` and `fieldArrows3` do the same in space. An arrow there is measured in the world's own units
+rather than the figure's, since a far arrow drawing shorter than a near one of the same magnitude is
+what says which is far, and its head is a flat triangle at the projected tip so it stays readable
+however steeply the arrow points away. The solid demo runs three streamlines of steepest descent down
+its saddle: each is walked in the plane the surface is drawn over and lifted onto it, so every point
+lies on the surface exactly and the height falls at every step.
+
+## A view that follows
+
+`Extent` carries a `centre`, which is where the middle of the frame sits in figure units, and an
+extent may be a function of the shape of the surface and of the time. `viewAt(figure, seconds, width,
+height)` hands a painter its matrix at a time in one call, so a figure whose extent moves cannot be
+asked for its extent at one time and its marks at another.
+
+The flat demo's view follows its dot across. The dot stays within 1.2 figure units of the middle of
+the frame, where before it crossed 2.76. `fractionOf` reads the centre off the extent it is handed, so
+the reading and the typeset rule stay where they are on the surface while the grid slides under them:
+they drift 1.14e-15 figure units over the whole walk.
+
 ## The animations
 
 `fadeIn`, `fadeOut`, `fadeTo`, `draw`, `morph`, `morphEquation`, `countTo`, `moveBy`, `rotate`,
@@ -256,7 +334,7 @@ moving fast, which on a quarter circle is a 6.9% difference between the longest
 and on the demo's own walk is 82%.
 
 Every picture here is written by `svgMarkup`, which needs no browser, so `npm run demos` regenerates
-all six and a test compares the bytes against the committed files.
+all eight and a test compares the bytes against the committed files.
 
 ## What it is built on
 

package/dist/figure/annotate.d.ts

@@ -29,6 +29,9 @@ export interface ArrowOptions {
  *
  * The shaft stops where the head begins rather than running under it, because a
  * shaft drawn to the point shows through a head that is not fully opaque.
+ *
+ * The head is never longer than the arrow. A head longer than that puts its own
+ * base behind the tail, which draws the shaft pointing back the way it came.
  */
 export declare function arrow(name: string, from: Vec2, to: Vec2, options: ArrowOptions): GroupNode;
 /** A filled disc, which is what marks a place a line is pointing at. */

package/dist/figure/annotate.js

@@ -15,9 +15,12 @@ import { group, shape, text } from './node.js';
  *
  * The shaft stops where the head begins rather than running under it, because a
  * shaft drawn to the point shows through a head that is not fully opaque.
+ *
+ * The head is never longer than the arrow. A head longer than that puts its own
+ * base behind the tail, which draws the shaft pointing back the way it came.
  */
 export function arrow(name, from, to, options) {
-    const head = options.head ?? options.stroke.width * 4;
+    const head = Math.min(options.head ?? options.stroke.width * 4, vec2.distance(from, to));
     const spread = options.spread ?? 0.6;
     const along = vec2.normalize(vec2.sub(to, from));
     const base = vec2.sub(to, vec2.scale(along, head));

package/dist/figure/axis3.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Three number lines in space, with a tick at each of their numbers and the
+ * numbers written beside them.
+ *
+ * A tick reaches along the next axis round, x along y, y along z and z along x,
+ * so every tick lies in a plane the axis is part of and no tick needs the camera
+ * to decide which way to point. A label is flat text at the projected tick,
+ * standing off it in the direction that leads away from the projected origin, so
+ * labels fall outside the picture at every pose rather than over it.
+ */
+import { type Interval } from '../values/interval.js';
+import { type GroupNode } from './node.js';
+import type { Camera3 } from './camera.js';
+import type { Fill, Stroke } from './mark.js';
+export interface Axes3Options {
+    /** The run of each axis in world units, minus one to one unless named. */
+    x?: Interval;
+    y?: Interval;
+    z?: Interval;
+    /** The lines and their ticks. */
+    stroke: Stroke;
+    /** The labels. 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;
+    /** About how many ticks are wanted on each axis. 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 its axis in world units, half either side. */
+    tickLength?: number;
+    /** From the projected tick to the label's own anchor, in figure units. */
+    gap?: number;
+    family?: string;
+    weight?: number;
+}
+/**
+ * The three axes as a group, one child per axis, each holding its line under
+ * `line`, its ticks under `ticks` and its labels under `labels`.
+ *
+ * Each tick and each label is named after the number it shows rather than by its
+ * place in the list, so an animation naming a tick follows that number when the
+ * axes are rebuilt over a different range.
+ */
+export declare function axes3(name: string, camera: Camera3, options: Axes3Options): GroupNode;

package/dist/figure/axis3.js

@@ -0,0 +1,75 @@
+/**
+ * Three number lines in space, with a tick at each of their numbers and the
+ * numbers written beside them.
+ *
+ * A tick reaches along the next axis round, x along y, y along z and z along x,
+ * so every tick lies in a plane the axis is part of and no tick needs the camera
+ * to decide which way to point. A label is flat text at the projected tick,
+ * standing off it in the direction that leads away from the projected origin, so
+ * labels fall outside the picture at every pose rather than over it.
+ */
+import { interval } from '../values/interval.js';
+import { vec2 } from '../values/vec2.js';
+import { vec3 } from '../values/vec3.js';
+import { group } from './node.js';
+import { ticksOn } from './ticks.js';
+import { polyline3, text3 } from './space.js';
+const ALONG = {
+    x: vec3(1, 0, 0),
+    y: vec3(0, 1, 0),
+    z: vec3(0, 0, 1),
+};
+const ACROSS = { x: ALONG.y, y: ALONG.z, z: ALONG.x };
+/** Which way a label leans away from where the three lines cross, or straight
+ * down where the tick lands on that crossing and there is no direction to lean
+ * in. */
+function leaning(from, to, gap) {
+    const away = vec2.sub(to, from);
+    if (vec2.magnitude(away) < 1e-12)
+        return vec2(0, -gap);
+    return vec2.scale(vec2.normalize(away), gap);
+}
+function oneAxis(which, bounds, camera, options) {
+    const along = ALONG[which];
+    const across = ACROSS[which];
+    const size = options.size ?? 0;
+    const tickLength = options.tickLength ?? options.stroke.width * 8;
+    const gap = options.gap ?? size * 0.35;
+    const { from: low, to: high } = interval.ordered(bounds);
+    const at = (value) => vec3.scale(along, value);
+    const marked = ticksOn(bounds, options.ticks);
+    const half = tickLength / 2;
+    const origin = camera.project(vec3.ZERO).at;
+    const parts = [polyline3('line', [at(low), at(high)], camera, { stroke: options.stroke })];
+    parts.push(group('ticks', marked.map((tick) => polyline3(tick.label, [vec3.sub(at(tick.value), vec3.scale(across, half)), vec3.add(at(tick.value), vec3.scale(across, half))], camera, { stroke: options.stroke }))));
+    if (options.fill && size > 0) {
+        // The three lines cross at the origin, so only one of them writes the number
+        // there and the other two would write it again in the same place.
+        const written = marked.filter((tick) => which === 'x' || tick.value !== 0);
+        parts.push(group('labels', written.map((tick) => text3(tick.label, at(tick.value), tick.label, size, camera, {
+            fill: options.fill,
+            family: options.family,
+            weight: options.weight,
+            align: 'middle',
+            baseline: 'middle',
+            offset: leaning(origin, camera.project(at(tick.value)).at, gap),
+        }))));
+    }
+    return group(which, parts);
+}
+/**
+ * The three axes as a group, one child per axis, each holding its line under
+ * `line`, its ticks under `ticks` and its labels under `labels`.
+ *
+ * Each tick and each label is named after the number it shows rather than by its
+ * place in the list, so an animation naming a tick follows that number when the
+ * axes are rebuilt over a different range.
+ */
+export function axes3(name, camera, options) {
+    const span = interval(-1, 1);
+    return group(name, [
+        oneAxis('x', options.x ?? span, camera, options),
+        oneAxis('y', options.y ?? span, camera, options),
+        oneAxis('z', options.z ?? span, camera, options),
+    ]);
+}

package/dist/figure/camera.d.ts

@@ -0,0 +1,100 @@
+/**
+ * A figure's own camera: where an eye is, what it looks at, and how a point in
+ * space becomes a point in the figure's units.
+ *
+ * A camera is a value the caller holds, the way a `Scale` is, and nothing inside
+ * a figure owns one. That is what keeps the seam: `at(figure, seconds)` gives
+ * back marks measured in the figure's own units, so a point in space has to
+ * become a point in those units before it is a mark at all. A camera inside the
+ * flattening would make every animation say whether it acts on the shape in
+ * space or on the picture of it, which is a question `fadeIn` should never be
+ * asked.
+ *
+ * So a camera moves by being rebuilt from values a track samples, and never by an
+ * animation. A span's eased fraction and a track's value are unrelated numbers,
+ * and a camera on one with a surface on the other is two clocks free to disagree.
+ */
+import { type Mat4 } from '../values/mat4.js';
+import { type Vec3 } from '../values/vec3.js';
+import type { Vec2 } from '../values/vec2.js';
+/**
+ * How a point that the eye has already lined up becomes a point on the page.
+ *
+ * `place` takes a point in view space, where the eye is at the origin looking
+ * down the negative z axis, and gives its place in figure units measured from the
+ * middle of the frame. `near` is how close to the eye a point may come before it
+ * has no place on the page at all.
+ */
+export type Projection = {
+    near: number;
+    place: (view: Vec3) => Vec2;
+};
+export type OrthographicChoice = {
+    /** How many figure units across the frame one world unit becomes. */
+    scale?: number;
+};
+/**
+ * An eye that sees everything at the size it is, however far off it is.
+ *
+ * A parallel projection is a multiplication rather than a divide, so there is no
+ * matrix here and no clip box: near and far planes are what a divide needs, and
+ * this has none. Nothing shrinks with distance, so a point behind the eye lands
+ * where the point in front of it that it lines up with lands, and the near plane
+ * is at negative infinity to say that nothing is ever cut away.
+ */
+export declare function orthographic({ scale }?: OrthographicChoice): Projection;
+export type PerspectiveChoice = {
+    /** The angle the frame covers up and down, in radians. */
+    fov?: number;
+    /** How tall the frame is in figure units, so handing this the extent's own
+     * height makes the picture fill the frame. */
+    height?: number;
+    near?: number;
+    far?: number;
+};
+/**
+ * An eye that sees things smaller the further off they are.
+ *
+ * The matrix is built at an aspect of one and only its x and y are read, so the
+ * same shrinking factor is used across and up and a circle facing the eye stays a
+ * circle at every shape of surface. How wide the frame is comes from the extent,
+ * and how deep a point is comes from view space, where it is a distance rather
+ * than the squeezed value a projection writes into z.
+ */
+export declare function perspective({ fov, height, near, far, }?: PerspectiveChoice): Projection;
+export type Camera3Choice = {
+    eye: Vec3;
+    target: Vec3;
+    up?: Vec3;
+    projection?: Projection;
+};
+/** Where a point in space landed, how far off it is, and whether the eye can see
+ * it at all. */
+export type Projected = {
+    /** The place in the figure's own units, measured from the middle of the frame. */
+    at: Vec2;
+    /** How far the point is from the eye along the way the camera looks, which is
+     * what a depth sort orders by and not the straight-line distance to the eye. */
+    depth: number;
+    /** Whether the point is further off than the near plane. A point that is not is
+     * still given a place, and that place is meaningless. */
+    inFront: boolean;
+};
+export type Camera3 = {
+    eye: Vec3;
+    target: Vec3;
+    up: Vec3;
+    projection: Projection;
+    /** The matrix that lines the world up with the eye, kept so a caller that has
+     * many points to place does not rebuild it per point. */
+    view: Mat4;
+    project: (point: Vec3) => Projected;
+};
+/**
+ * An eye at `eye` looking at `target`, with `up` saying which way is up.
+ *
+ * An `up` lying along the line of sight has no sideways direction in it and gives
+ * a camera that places every point at the middle of the frame, which is a pose
+ * the caller has to avoid rather than one this can fix.
+ */
+export declare function camera3({ eye, target, up, projection, }: Camera3Choice): Camera3;

package/dist/figure/camera.js

@@ -0,0 +1,74 @@
+/**
+ * A figure's own camera: where an eye is, what it looks at, and how a point in
+ * space becomes a point in the figure's units.
+ *
+ * A camera is a value the caller holds, the way a `Scale` is, and nothing inside
+ * a figure owns one. That is what keeps the seam: `at(figure, seconds)` gives
+ * back marks measured in the figure's own units, so a point in space has to
+ * become a point in those units before it is a mark at all. A camera inside the
+ * flattening would make every animation say whether it acts on the shape in
+ * space or on the picture of it, which is a question `fadeIn` should never be
+ * asked.
+ *
+ * So a camera moves by being rebuilt from values a track samples, and never by an
+ * animation. A span's eased fraction and a track's value are unrelated numbers,
+ * and a camera on one with a surface on the other is two clocks free to disagree.
+ */
+import { mat4 } from '../values/mat4.js';
+import { vec3 } from '../values/vec3.js';
+/**
+ * An eye that sees everything at the size it is, however far off it is.
+ *
+ * A parallel projection is a multiplication rather than a divide, so there is no
+ * matrix here and no clip box: near and far planes are what a divide needs, and
+ * this has none. Nothing shrinks with distance, so a point behind the eye lands
+ * where the point in front of it that it lines up with lands, and the near plane
+ * is at negative infinity to say that nothing is ever cut away.
+ */
+export function orthographic({ scale = 1 } = {}) {
+    return {
+        near: -Infinity,
+        place: (view) => ({ x: view.x * scale, y: view.y * scale }),
+    };
+}
+/**
+ * An eye that sees things smaller the further off they are.
+ *
+ * The matrix is built at an aspect of one and only its x and y are read, so the
+ * same shrinking factor is used across and up and a circle facing the eye stays a
+ * circle at every shape of surface. How wide the frame is comes from the extent,
+ * and how deep a point is comes from view space, where it is a distance rather
+ * than the squeezed value a projection writes into z.
+ */
+export function perspective({ fov = Math.PI / 4, height = 2, near = 0.01, far = 1000, } = {}) {
+    const matrix = mat4.perspective({ fov, aspect: 1, near, far });
+    return {
+        near,
+        place: (view) => {
+            const clip = mat4.transformPoint(matrix, view);
+            return { x: (clip.x * height) / 2, y: (clip.y * height) / 2 };
+        },
+    };
+}
+/**
+ * An eye at `eye` looking at `target`, with `up` saying which way is up.
+ *
+ * An `up` lying along the line of sight has no sideways direction in it and gives
+ * a camera that places every point at the middle of the frame, which is a pose
+ * the caller has to avoid rather than one this can fix.
+ */
+export function camera3({ eye, target, up = vec3(0, 1, 0), projection = perspective(), }) {
+    const view = mat4.lookAt(eye, target, up);
+    return {
+        eye,
+        target,
+        up,
+        projection,
+        view,
+        project: (point) => {
+            const seen = mat4.transformPoint(view, point);
+            const depth = -seen.z;
+            return { at: projection.place(seen), depth, inFront: depth > projection.near };
+        },
+    };
+}

package/dist/figure/extent.d.ts

@@ -10,14 +10,18 @@ import { type Vec2 } from '../values/vec2.js';
 export interface Extent {
     width: number;
     height: number;
+    /** Where the middle of the frame sits in the figure's own units, the origin
+     * unless named. A figure whose view follows something moves this rather than
+     * moving everything it draws. */
+    centre?: Vec2;
 }
 /** Whether the extent is held inside the surface, leaving margins where the
  * shapes differ, or fills it and runs off two edges. */
 export type Fit = 'contain' | 'cover';
 /** An extent that never changes, or one chosen from the shape of the surface it
- * is about to be drawn on. */
-export type ExtentChoice = Extent | ((aspect: number) => Extent);
-export declare function resolveExtent(choice: ExtentChoice, aspect: number): Extent;
+ * is about to be drawn on and the time it is drawn at. */
+export type ExtentChoice = Extent | ((aspect: number, seconds: number) => Extent);
+export declare function resolveExtent(choice: ExtentChoice, aspect: number, seconds?: number): Extent;
 /**
  * An extent per shape, for a figure whose composition does not survive being
  * reframed.

package/dist/figure/extent.js

@@ -7,8 +7,8 @@
  */
 import { mat3 } from '../values/mat3.js';
 import { vec2 } from '../values/vec2.js';
-export function resolveExtent(choice, aspect) {
-    return typeof choice === 'function' ? choice(aspect) : choice;
+export function resolveExtent(choice, aspect, seconds = 0) {
+    return typeof choice === 'function' ? choice(aspect, seconds) : choice;
 }
 /**
  * An extent per shape, for a figure whose composition does not survive being
@@ -49,7 +49,8 @@ export function matchingAspect(height = 2) {
  * is drawing would need the shader's camera, and nothing can read one.
  */
 export function fractionOf(extent, across, up) {
-    return vec2((across - 0.5) * extent.width, (up - 0.5) * extent.height);
+    const centre = extent.centre ?? vec2(0, 0);
+    return vec2(centre.x + (across - 0.5) * extent.width, centre.y + (up - 0.5) * extent.height);
 }
 /**
  * The one matrix taking figure units onto a surface, with the extent centred.
@@ -63,7 +64,9 @@ export function viewMatrix(extent, fit, surfaceWidth, surfaceHeight) {
     const byWidth = surfaceWidth / extent.width;
     const byHeight = surfaceHeight / extent.height;
     const scale = fit === 'cover' ? Math.max(byWidth, byHeight) : Math.min(byWidth, byHeight);
-    const centre = mat3.translation(vec2(surfaceWidth / 2, surfaceHeight / 2));
+    const middle = mat3.translation(vec2(surfaceWidth / 2, surfaceHeight / 2));
     const flip = mat3.scaling(vec2(scale, -scale));
-    return mat3.multiply(centre, flip);
+    const seen = extent.centre ?? vec2(0, 0);
+    const follow = mat3.translation(vec2(-seen.x, -seen.y));
+    return mat3.multiply(mat3.multiply(middle, flip), follow);
 }

package/dist/figure/field.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A field of vectors sampled over a graph and drawn as one arrow per sample.
+ *
+ * Nothing here stores a field. A field is a function from a place to a vector,
+ * so what this adds is where it is read and how what it reads is drawn.
+ *
+ * How long an arrow is and what colour it is are both the author's, taken from
+ * the vector's own magnitude. A field drawn at its true lengths is unreadable
+ * the moment two samples differ by a factor of ten, and choosing the scale needs
+ * numbers about the picture this package does not have.
+ *
+ * The count is fixed by the resolution and never by the field, so a gate can
+ * hold it. The one sample that draws nothing is the one whose vector is nothing,
+ * and the count is what says where that happened.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Vec2 } from '../values/vec2.js';
+import { type Coords } from './scale.js';
+import { type GroupNode } from './node.js';
+import type { Colour } from './mark.js';
+export interface VectorFieldOptions {
+    /** How long an arrow is, in figure units, from the magnitude of the vector at
+     * its own sample. */
+    lengthOf: (magnitude: number) => number;
+    /** What colour an arrow is, from that same magnitude. */
+    colourFor: (magnitude: number) => Colour;
+    /** How wide a shaft is, in figure units, like any other stroke here. */
+    width: number;
+    /** How many samples across and up. One number is both. */
+    resolution?: number | {
+        x: number;
+        y: number;
+    };
+    /** The run of x sampled, which is the whole width of the graph where it is
+     * left out. */
+    overX?: Interval;
+    /** The run of y sampled, which is the whole height of the graph where it is
+     * left out. */
+    overY?: Interval;
+    /** How long a head is, in figure units. Four times the shaft's width unless
+     * named, which is what an arrow takes when nothing says. */
+    head?: number;
+    /** How wide a head is across its base, against its length. */
+    spread?: number;
+}
+/**
+ * The arrows of a field over a graph, one group per sample, named by its column
+ * and row so a stagger can reach them one at a time.
+ *
+ * A sample sits at the middle of its cell rather than on the grid line. An
+ * inclusive grid would put the arrows of the outer row and column half outside
+ * the graph, where a painter has to clip them.
+ *
+ * An arrow points where the mapping of its own vector points, so it lies along
+ * the curves drawn over the same coordinates. Taking the direction in graph
+ * units instead would tilt every arrow wherever the two axes count at different
+ * rates.
+ *
+ * Its length is in figure units, like the width of its shaft and the length of
+ * its head. A length in graph units under two axes counting at different rates
+ * would draw the arrows pointing one way several times shorter than the arrows
+ * pointing the other, at the same magnitude.
+ */
+export declare function vectorField(name: string, coords: Coords, of: (at: Vec2) => Vec2, options: VectorFieldOptions): GroupNode;

package/dist/figure/field.js

@@ -0,0 +1,69 @@
+/**
+ * A field of vectors sampled over a graph and drawn as one arrow per sample.
+ *
+ * Nothing here stores a field. A field is a function from a place to a vector,
+ * so what this adds is where it is read and how what it reads is drawn.
+ *
+ * How long an arrow is and what colour it is are both the author's, taken from
+ * the vector's own magnitude. A field drawn at its true lengths is unreadable
+ * the moment two samples differ by a factor of ten, and choosing the scale needs
+ * numbers about the picture this package does not have.
+ *
+ * The count is fixed by the resolution and never by the field, so a gate can
+ * hold it. The one sample that draws nothing is the one whose vector is nothing,
+ * and the count is what says where that happened.
+ */
+import { interval } from '../values/interval.js';
+import { vec2 } from '../values/vec2.js';
+import { pointOf } from './scale.js';
+import { group } from './node.js';
+import { arrow } from './annotate.js';
+function stepsOf(resolution) {
+    return typeof resolution === 'number' ? { x: resolution, y: resolution } : resolution;
+}
+/**
+ * The arrows of a field over a graph, one group per sample, named by its column
+ * and row so a stagger can reach them one at a time.
+ *
+ * A sample sits at the middle of its cell rather than on the grid line. An
+ * inclusive grid would put the arrows of the outer row and column half outside
+ * the graph, where a painter has to clip them.
+ *
+ * An arrow points where the mapping of its own vector points, so it lies along
+ * the curves drawn over the same coordinates. Taking the direction in graph
+ * units instead would tilt every arrow wherever the two axes count at different
+ * rates.
+ *
+ * Its length is in figure units, like the width of its shaft and the length of
+ * its head. A length in graph units under two axes counting at different rates
+ * would draw the arrows pointing one way several times shorter than the arrows
+ * pointing the other, at the same magnitude.
+ */
+export function vectorField(name, coords, of, options) {
+    const steps = stepsOf(options.resolution ?? 12);
+    const overX = interval.ordered(options.overX ?? coords.x.graph);
+    const overY = interval.ordered(options.overY ?? coords.y.graph);
+    const children = [];
+    for (let column = 0; column < steps.x; column += 1) {
+        for (let row = 0; row < steps.y; row += 1) {
+            const x = interval.at(overX, (column + 0.5) / steps.x);
+            const y = interval.at(overY, (row + 0.5) / steps.y);
+            const vector = of(vec2(x, y));
+            const magnitude = Math.hypot(vector.x, vector.y);
+            const length = options.lengthOf(magnitude);
+            if (!(magnitude > 0) || !Number.isFinite(length) || !(length > 0))
+                continue;
+            const from = pointOf(coords, x, y);
+            const along = vec2.sub(pointOf(coords, x + vector.x, y + vector.y), from);
+            if (!(vec2.magnitude(along) > 0))
+                continue;
+            const to = vec2.add(from, vec2.scale(vec2.normalize(along), length));
+            children.push(arrow(`${column}-${row}`, from, to, {
+                stroke: { colour: options.colourFor(magnitude), width: options.width },
+                head: options.head,
+                spread: options.spread,
+            }));
+        }
+    }
+    return group(name, children);
+}

package/dist/figure/figure.d.ts

@@ -12,7 +12,8 @@
 import { type TrackValue, type Tracks } from '../timing/track.js';
 import { type Node } from './node.js';
 import { Timeline } from './timeline.js';
-import type { ExtentChoice, Fit } from './extent.js';
+import { type ExtentChoice, type Fit } from './extent.js';
+import type { Mat3 } from '../values/mat3.js';
 import type { Mark } from './mark.js';
 /** The values a scene is rebuilt from, sampled out of the figure's tracks. This
  * is what lets geometry follow a number rather than only be moved about: a
@@ -44,6 +45,15 @@ export interface Figure {
 export declare function durationOf(figure: Figure): number;
 /** The marks a figure shows at a time. */
 export declare function at(figure: Figure, seconds: number): readonly Mark[];
+/**
+ * The matrix a painter needs at a time, in one call.
+ *
+ * A figure whose extent is a function of the clock has to be asked for its
+ * extent at the same time its marks were asked for, and a consumer writing that
+ * as two calls has two chances to pass different times. What the painter is
+ * handed is the matrix, so the extent and the centring stay in here.
+ */
+export declare function viewAt(figure: Figure, seconds: number, width: number, height: number): Mat3;
 /** Whether a figure declaring itself a loop actually is one, which is the gate
  * behind that flag. The comparison is by tolerance rather than exactly, because
  * the sine and cosine a figure is built from are not specified to the last bit