@altpsyche/maths 0.10.0 → 0.12.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
@@ -243,7 +243,7 @@ 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. Three axes with their numbers stand behind it and the equation of the surface is typeset in the top left.">
+<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
@@ -268,11 +268,45 @@ The camera is driven by a track and never by an animation, which is the call the
 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 and pane from four points around one orbit of the eye.">
+<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
@@ -326,6 +360,31 @@ marks onto a two-dimensional canvas, which is what a recording needs, because an
 one surface. A test holds the two to emitting the same geometry and the same style for every
 mark.
 
+## Frames out
+
+`framesOf(figure, options)` walks a figure at a fixed step and hands back a frame at a time. A frame
+is its index, its time, its marks and the view those marks are painted through, read together at one
+moment. A consumer that asks for the marks and the view in two calls has two chances to pass different
+times, and a figure whose view moves then paints its marks through the matrix of some other moment:
+the flat demo's view is carried 312 across its own walk, in the units a 1080 by 600 surface counts in.
+
+Frames come back one at a time rather than as a list. Ten seconds at sixty frames a second is six
+hundred frames of every mark a figure draws, and a recorder encodes a frame and throws it away.
+`frameTimes` answers the times up front, since a recorder showing a reader how far along it is needs
+the total before it has drawn anything.
+
+The step is given as a rate or as a count, and the two are different questions. A recorder knows how
+fast the frames play and needs a step of exactly one over that, or the encoded video drifts from the
+figure's own clock. A strip knows how many pictures fit across a page and wants them spread over the
+whole figure. A walk stops strictly before the duration either way: the frame at the duration of a
+figure that loops is its own first frame, and a recording would show it twice. The rotation strip
+above is a walk of four frames over a six second turn, and it draws the same bytes as the four times
+that were written out by hand before it.
+
+Nothing here writes a file. Every frame of both demos is painted through `paintCanvas` and written by
+`svgMarkup` in the suite, which is the whole claim and needs no browser, and what a consumer does with
+a painted frame is the consumer's own.
+
 ## The way in
 
 `pathFromData` reads an SVG `d` attribute as a path, which is the inverse of what the SVG painter

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/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/frames.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A figure walked at a fixed step, a frame at a time.
+ *
+ * A frame is the marks and the view read at one time, handed over together. A
+ * consumer that asked for them separately holds two calls it can pass different
+ * times, and a figure whose view moves then paints its marks through the matrix
+ * of some other moment.
+ *
+ * Frames come back one at a time rather than as a list. A ten second figure at
+ * sixty frames a second is six hundred frames of every mark it draws, and a
+ * recorder encodes a frame and throws it away.
+ */
+import { type Figure } from './figure.js';
+import type { Mark } from './mark.js';
+import type { Mat3 } from '../values/mat3.js';
+export interface Frame {
+    /** Its place in the walk, counting from nothing. */
+    index: number;
+    /** The time it was read at, in seconds. */
+    seconds: number;
+    marks: readonly Mark[];
+    /** The matrix a painter needs for these marks, built at this frame's own
+     * time. */
+    view: Mat3;
+}
+/**
+ * How the walk is stepped, as a rate or as a count.
+ *
+ * The two are different questions. A recorder knows how fast the frames play and
+ * needs a step of exactly one over that, or the encoded video drifts from the
+ * figure's own clock. A strip knows how many pictures fit across a page and wants
+ * them spread over the whole figure.
+ */
+export type FrameStep = {
+    fps: number;
+    frames?: never;
+} | {
+    frames: number;
+    fps?: never;
+};
+export type FramesOptions = FrameStep & {
+    /** The surface the view is built for, in whatever units a painter counts in. */
+    width: number;
+    height: number;
+};
+/**
+ * The times a walk reads, which a recorder needs before it has drawn anything to
+ * say how far along it is.
+ *
+ * A walk stops strictly before the duration. The frame at the duration of a
+ * figure that loops is its own first frame, and a recording would show it twice.
+ * A figure with no duration is one frame, since a picture that never moves still
+ * has a picture.
+ */
+export declare function frameTimes(figure: Figure, step: FrameStep): number[];
+/** A figure walked at a fixed step, a frame at a time. */
+export declare function framesOf(figure: Figure, options: FramesOptions): Generator<Frame>;

package/dist/figure/frames.js

@@ -0,0 +1,43 @@
+/**
+ * A figure walked at a fixed step, a frame at a time.
+ *
+ * A frame is the marks and the view read at one time, handed over together. A
+ * consumer that asked for them separately holds two calls it can pass different
+ * times, and a figure whose view moves then paints its marks through the matrix
+ * of some other moment.
+ *
+ * Frames come back one at a time rather than as a list. A ten second figure at
+ * sixty frames a second is six hundred frames of every mark it draws, and a
+ * recorder encodes a frame and throws it away.
+ */
+import { at, durationOf, viewAt } from './figure.js';
+/**
+ * The times a walk reads, which a recorder needs before it has drawn anything to
+ * say how far along it is.
+ *
+ * A walk stops strictly before the duration. The frame at the duration of a
+ * figure that loops is its own first frame, and a recording would show it twice.
+ * A figure with no duration is one frame, since a picture that never moves still
+ * has a picture.
+ */
+export function frameTimes(figure, step) {
+    const duration = durationOf(figure);
+    const count = step.fps === undefined
+        ? Math.max(1, Math.round(step.frames))
+        : Math.max(1, Math.round(duration * step.fps));
+    const gap = step.fps === undefined ? duration / count : 1 / step.fps;
+    return Array.from({ length: count }, (_, index) => index * gap);
+}
+/** A figure walked at a fixed step, a frame at a time. */
+export function* framesOf(figure, options) {
+    const times = frameTimes(figure, options);
+    for (let index = 0; index < times.length; index += 1) {
+        const seconds = times[index];
+        yield {
+            index,
+            seconds,
+            marks: at(figure, seconds),
+            view: viewAt(figure, seconds, options.width, options.height),
+        };
+    }
+}

package/dist/figure/space.d.ts

@@ -11,7 +11,8 @@ import { type Vec3 } from '../values/vec3.js';
 import type { Vec2 } from '../values/vec2.js';
 import { type GroupNode, type Node, type Style, type TextOptions } from './node.js';
 import { type Interval } from '../values/interval.js';
-import type { Fill, Stroke } from './mark.js';
+import type { Colour, Fill, Stroke } from './mark.js';
+import { type ArrowOptions } from './annotate.js';
 import type { Camera3 } from './camera.js';
 export type Polyline3Options = Style & {
     /** Whether the last point joins back to the first. A run that the near plane
@@ -53,6 +54,55 @@ export type SpaceItem = {
  * top between frames would flicker.
  */
 export declare function space(name: string, items: readonly SpaceItem[], camera: Camera3): GroupNode;
+export type Arrow3Options = ArrowOptions;
+/**
+ * A line between two points in space with a head at the far end.
+ *
+ * The head is a flat triangle at the projected tip rather than a shape in
+ * space, so it stays the size it was given however far off the arrow is and
+ * however steeply it points away. A head built in space turns edge on to the eye
+ * and disappears exactly where the arrow is hardest to read.
+ *
+ * An arrow whose far end is behind the eye is cut at the near plane and drawn
+ * with no head, since the place the head belongs is not on the page.
+ */
+export declare function arrow3(name: string, from: Vec3, to: Vec3, camera: Camera3, options: Arrow3Options): GroupNode;
+export type VectorField3Options = ArrowOptions & {
+    /** The box the samples are taken in, nothing to one each way unless named. */
+    over?: {
+        x?: Interval;
+        y?: Interval;
+        z?: Interval;
+    };
+    /** How many samples each way. One number is all three. */
+    resolution?: number | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** How long an arrow is, in the world's own 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;
+};
+/**
+ * The arrows of a field sampled over a box in space, and the points each was
+ * drawn from, for a figure that sorts them among pieces of its own.
+ *
+ * An arrow is measured in the world's own units rather than the figure's, unlike
+ * the arrows of a flat field, because a length in space is what perspective is
+ * for: a far arrow drawing shorter than a near one of the same magnitude is what
+ * says which is far. Its head is still in figure units, since the head is drawn
+ * on the page.
+ *
+ * A sample sits at the middle of its cell and the count is fixed by the
+ * resolution, so a gate can hold it as the eye moves. A sample whose vector is
+ * nothing draws no arrow there.
+ */
+export declare function fieldArrows3(name: string, of: (at: Vec3) => Vec3, camera: Camera3, options: VectorField3Options): SpaceItem[];
+/** A field of vectors in space, drawn as arrows ordered back to front. */
+export declare function vectorField3(name: string, of: (at: Vec3) => Vec3, camera: Camera3, options: VectorField3Options): GroupNode;
 export type Surface3Options = {
     /** The run of the first parameter, nothing to one unless named. */
     u?: Interval;

package/dist/figure/space.js

@@ -8,9 +8,10 @@
  * with no children, which flattens to no marks rather than to a mark of nothing.
  */
 import { vec3 } from '../values/vec3.js';
-import { circle, polygon, polyline } from './path.js';
+import { circle, line, polygon, polyline } from './path.js';
 import { group, shape, text } from './node.js';
 import { interval } from '../values/interval.js';
+import { arrow } from './annotate.js';
 /**
  * Where along a segment the near plane is crossed.
  *
@@ -108,6 +109,85 @@ export function space(name, items, camera) {
     measured.sort((a, b) => b.depth - a.depth);
     return group(name, measured.map((item) => item.node));
 }
+/**
+ * A line between two points in space with a head at the far end.
+ *
+ * The head is a flat triangle at the projected tip rather than a shape in
+ * space, so it stays the size it was given however far off the arrow is and
+ * however steeply it points away. A head built in space turns edge on to the eye
+ * and disappears exactly where the arrow is hardest to read.
+ *
+ * An arrow whose far end is behind the eye is cut at the near plane and drawn
+ * with no head, since the place the head belongs is not on the page.
+ */
+export function arrow3(name, from, to, camera, options) {
+    const start = camera.project(from);
+    const end = camera.project(to);
+    if (!start.inFront && !end.inFront)
+        return group(name, []);
+    const cut = () => {
+        const along = crossingAt(start.depth, end.depth, camera.projection.near);
+        return camera.project(vec3.lerp(from, to, along)).at;
+    };
+    if (!end.inFront)
+        return group(name, [shape('shaft', line(start.at, cut()), { stroke: options.stroke })]);
+    const tail = start.inFront ? start.at : cut();
+    if (tail.x === end.at.x && tail.y === end.at.y)
+        return group(name, []);
+    return arrow(name, tail, end.at, options);
+}
+function gridOf(resolution) {
+    return typeof resolution === 'number' ? { x: resolution, y: resolution, z: resolution } : resolution;
+}
+/**
+ * The arrows of a field sampled over a box in space, and the points each was
+ * drawn from, for a figure that sorts them among pieces of its own.
+ *
+ * An arrow is measured in the world's own units rather than the figure's, unlike
+ * the arrows of a flat field, because a length in space is what perspective is
+ * for: a far arrow drawing shorter than a near one of the same magnitude is what
+ * says which is far. Its head is still in figure units, since the head is drawn
+ * on the page.
+ *
+ * A sample sits at the middle of its cell and the count is fixed by the
+ * resolution, so a gate can hold it as the eye moves. A sample whose vector is
+ * nothing draws no arrow there.
+ */
+export function fieldArrows3(name, of, camera, options) {
+    const { over = {}, resolution = 6, lengthOf, colourFor, ...rest } = options;
+    const box = {
+        x: interval.ordered(over.x ?? interval(0, 1)),
+        y: interval.ordered(over.y ?? interval(0, 1)),
+        z: interval.ordered(over.z ?? interval(0, 1)),
+    };
+    const steps = gridOf(resolution);
+    const items = [];
+    for (let i = 0; i < steps.x; i += 1) {
+        for (let j = 0; j < steps.y; j += 1) {
+            for (let k = 0; k < steps.z; k += 1) {
+                const from = vec3(interval.at(box.x, (i + 0.5) / steps.x), interval.at(box.y, (j + 0.5) / steps.y), interval.at(box.z, (k + 0.5) / steps.z));
+                const vector = of(from);
+                const magnitude = vec3.magnitude(vector);
+                const length = lengthOf(magnitude);
+                if (!(magnitude > 0) || !Number.isFinite(length) || !(length > 0))
+                    continue;
+                const to = vec3.add(from, vec3.scale(vector, length / magnitude));
+                items.push({
+                    points: [from, to],
+                    node: arrow3(`${name}/${i}-${j}-${k}`, from, to, camera, {
+                        ...rest,
+                        stroke: { ...rest.stroke, colour: colourFor(magnitude) },
+                    }),
+                });
+            }
+        }
+    }
+    return items;
+}
+/** A field of vectors in space, drawn as arrows ordered back to front. */
+export function vectorField3(name, of, camera, options) {
+    return space(name, fieldArrows3('arrow', of, camera, options), camera);
+}
 function resolutionOf(resolution) {
     return typeof resolution === 'number' ? { u: resolution, v: resolution } : resolution;
 }

package/dist/figure/streamline.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The path a point follows through a field of vectors, walked by Runge-Kutta 4.
+ *
+ * The points come back in graph units and nothing here draws them, the way the
+ * curve where a plane cuts a surface comes back as points in space. What a
+ * figure does with them is its own.
+ *
+ * The step is a distance rather than a time, so the field is read as a
+ * direction and its magnitude decides nothing about how far the run moves. A
+ * step in the field's own time crowds the points where the field is weak and
+ * spreads them where it is strong, and a curve drawn from those is faceted
+ * exactly where it turns hardest.
+ *
+ * The step is fixed and never adaptive. An adaptive step hands back a different
+ * number of points as the field changes, which is a count no gate can hold and
+ * a path no morph can pair up against another.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Vec2 } from '../values/vec2.js';
+export interface StreamlineOptions {
+    /** How far each step moves, in graph units. */
+    step: number;
+    /** How many steps the run takes at most, in each direction it is run. */
+    steps?: number;
+    /** The region the run is held inside. It has no edges where this is left out,
+     * and only the step cap and a vanishing field stop it. */
+    within?: {
+        x: Interval;
+        y: Interval;
+    };
+    /** Which way the run goes from its seed. Both puts the backward half first,
+     * so the points read from one end of the curve to the other. */
+    direction?: 'forward' | 'backward' | 'both';
+    /** The magnitude below which the field is taken to have vanished, in graph
+     * units. */
+    least?: number;
+}
+/**
+ * The streamline of a field through a seed point, in graph units.
+ *
+ * The run stops on one of three rules: it leaves the region, it reaches its step
+ * cap, or the field where it stands is too small to point anywhere. A seed
+ * outside the region comes back as that seed alone, which is a curve with
+ * nothing to draw rather than a run that starts by escaping.
+ *
+ * A run that leaves the region stops at the last point inside it and is not cut
+ * at the edge, so it ends within one step of the boundary.
+ */
+export declare function streamlineOf(of: (at: Vec2) => Vec2, from: Vec2, options: StreamlineOptions): Vec2[];

package/dist/figure/streamline.js

@@ -0,0 +1,95 @@
+/**
+ * The path a point follows through a field of vectors, walked by Runge-Kutta 4.
+ *
+ * The points come back in graph units and nothing here draws them, the way the
+ * curve where a plane cuts a surface comes back as points in space. What a
+ * figure does with them is its own.
+ *
+ * The step is a distance rather than a time, so the field is read as a
+ * direction and its magnitude decides nothing about how far the run moves. A
+ * step in the field's own time crowds the points where the field is weak and
+ * spreads them where it is strong, and a curve drawn from those is faceted
+ * exactly where it turns hardest.
+ *
+ * The step is fixed and never adaptive. An adaptive step hands back a different
+ * number of points as the field changes, which is a count no gate can hold and
+ * a path no morph can pair up against another.
+ */
+import { interval } from '../values/interval.js';
+import { vec2 } from '../values/vec2.js';
+const STEPS = 200;
+const LEAST = 1e-9;
+function holds(within, at) {
+    if (!Number.isFinite(at.x) || !Number.isFinite(at.y))
+        return false;
+    if (!within)
+        return true;
+    return interval.holds(interval.ordered(within.x), at.x) && interval.holds(interval.ordered(within.y), at.y);
+}
+/**
+ * One run from the seed, as the points after it, with the seed left out so the
+ * two directions can be joined without repeating it.
+ *
+ * A stage whose field has vanished stops the run there rather than being taken
+ * as a direction, since dividing by a magnitude near nothing turns rounding
+ * error into a direction of its own.
+ */
+function run(of, from, step, steps, within, least) {
+    const direction = (at) => {
+        const vector = of(at);
+        const magnitude = Math.hypot(vector.x, vector.y);
+        if (!Number.isFinite(magnitude) || magnitude <= least)
+            return undefined;
+        return vec2(vector.x / magnitude, vector.y / magnitude);
+    };
+    const points = [];
+    let at = from;
+    for (let taken = 0; taken < steps; taken += 1) {
+        const first = direction(at);
+        if (!first)
+            break;
+        const second = direction(vec2.add(at, vec2.scale(first, step / 2)));
+        if (!second)
+            break;
+        const third = direction(vec2.add(at, vec2.scale(second, step / 2)));
+        if (!third)
+            break;
+        const fourth = direction(vec2.add(at, vec2.scale(third, step)));
+        if (!fourth)
+            break;
+        const along = vec2((first.x + 2 * second.x + 2 * third.x + fourth.x) / 6, (first.y + 2 * second.y + 2 * third.y + fourth.y) / 6);
+        const next = vec2.add(at, vec2.scale(along, step));
+        if (!holds(within, next))
+            break;
+        points.push(next);
+        at = next;
+    }
+    return points;
+}
+/**
+ * The streamline of a field through a seed point, in graph units.
+ *
+ * The run stops on one of three rules: it leaves the region, it reaches its step
+ * cap, or the field where it stands is too small to point anywhere. A seed
+ * outside the region comes back as that seed alone, which is a curve with
+ * nothing to draw rather than a run that starts by escaping.
+ *
+ * A run that leaves the region stops at the last point inside it and is not cut
+ * at the edge, so it ends within one step of the boundary.
+ */
+export function streamlineOf(of, from, options) {
+    const steps = Math.max(0, Math.round(options.steps ?? STEPS));
+    const least = options.least ?? LEAST;
+    const direction = options.direction ?? 'forward';
+    if (!holds(options.within, from))
+        return [from];
+    const forward = direction === 'backward' ? [] : run(of, from, options.step, steps, options.within, least);
+    if (direction === 'forward')
+        return [from, ...forward];
+    const back = (at) => {
+        const vector = of(at);
+        return vec2(-vector.x, -vector.y);
+    };
+    const backward = run(back, from, options.step, steps, options.within, least);
+    return [...backward.reverse(), from, ...forward];
+}

package/dist/index.d.ts

@@ -42,12 +42,16 @@ export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
 export type { Bounds } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
 export type { AreaOptions, BarsOptions, PlotOptions, TangentOptions } from './figure/plot.js';
+export { vectorField } from './figure/field.js';
+export { streamlineOf } from './figure/streamline.js';
+export type { StreamlineOptions } from './figure/streamline.js';
+export type { VectorFieldOptions } from './figure/field.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
 export type { AxesOptions, NumberLineOptions, NumberPlaneOptions } from './figure/axis.js';
 export { camera3, orthographic, perspective } from './figure/camera.js';
 export type { Camera3, Camera3Choice, OrthographicChoice, PerspectiveChoice, Projected, Projection } from './figure/camera.js';
-export { dot3, polyline3, space, surface3, surfaceCells, text3 } from './figure/space.js';
-export type { Polyline3Options, SpaceItem, Surface3Options, Text3Options } from './figure/space.js';
+export { arrow3, dot3, fieldArrows3, polyline3, space, surface3, surfaceCells, text3, vectorField3 } from './figure/space.js';
+export type { Arrow3Options, Polyline3Options, SpaceItem, Surface3Options, Text3Options, VectorField3Options } from './figure/space.js';
 export { axes3 } from './figure/axis3.js';
 export type { Axes3Options } from './figure/axis3.js';
 export { sectionOf } from './figure/section.js';
@@ -66,6 +70,8 @@ export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
 export { at, durationOf, loops, sameMarks, viewAt } from './figure/figure.js';
+export { frameTimes, framesOf } from './figure/frames.js';
+export type { Frame, FrameStep, FramesOptions } from './figure/frames.js';
 export type { Figure, Values } from './figure/figure.js';
 export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
 export type { ElementMaker, PaintNode, PaintTarget, SvgElement } from './paint/svg.js';

package/dist/index.js

@@ -26,9 +26,11 @@ export { curveCrossings } from './figure/intersect.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
+export { vectorField } from './figure/field.js';
+export { streamlineOf } from './figure/streamline.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
 export { camera3, orthographic, perspective } from './figure/camera.js';
-export { dot3, polyline3, space, surface3, surfaceCells, text3 } from './figure/space.js';
+export { arrow3, dot3, fieldArrows3, polyline3, space, surface3, surfaceCells, text3, vectorField3 } from './figure/space.js';
 export { axes3 } from './figure/axis3.js';
 export { sectionOf } from './figure/section.js';
 export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
@@ -40,6 +42,7 @@ export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
 export { at, durationOf, loops, sameMarks, viewAt } from './figure/figure.js';
+export { frameTimes, framesOf } from './figure/frames.js';
 export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
 export { paintCanvas } from './paint/canvas.js';
 export { arrow, brace, bracePath, callout, dot } from './figure/annotate.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altpsyche/maths",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
   "license": "MIT",
   "author": "Siva",