@altpsyche/maths 0.11.0 → 0.13.0

package/dist/figure/path.js

@@ -55,8 +55,8 @@ export function rect(corner, width, height) {
  * fraction of the radius.
  *
  * Four cubics cannot be a circle exactly, and this is the value that makes the
- * error smallest: the arc passes through both ends and the midpoint, and never
- * leaves the true radius by more than 2.7 parts in ten thousand of it.
+ * error smallest: the arc passes through both ends and the midpoint, and leaves
+ * the true radius by a few parts in ten thousand of it between them.
  */
 const KAPPA = 0.5522847498307936;
 /** A circle as four cubic quarters, anticlockwise from the positive x axis. */
@@ -123,7 +123,7 @@ export function pointOn(from, curve, along) {
 }
 /** Which way a piece is heading at a fraction along it, which is the derivative
  * of a cubic and so a quadratic over the gaps between neighbouring points. */
-export function slopeOn(from, curve, along) {
+export function tangentOn(from, curve, along) {
     const u = 1 - along;
     const a = 3 * u * u;
     const b = 6 * u * along;

package/dist/figure/plot.d.ts

@@ -22,7 +22,7 @@ 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;
+    resolution?: 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;

package/dist/figure/plot.js

@@ -17,15 +17,14 @@
  */
 import { interval } from '../values/interval.js';
 import { vec2 } from '../values/vec2.js';
-import { pointOf, scaled } from './scale.js';
+import { pointOf, toUnits } 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.
+ * The count is what draws a sine over two turns under a tenth of a pixel from
+ * the true one on the largest surface anything here is drawn at.
  */
 const SAMPLES = 96;
 /**
@@ -34,10 +33,8 @@ const SAMPLES = 96;
  *
  * 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.
+ * An end that was cut at the edge of the graph is not evenly spaced, so the
+ * three-point form does not hold there and it takes the two-point difference.
  */
 function slopes(xs, ys) {
     const last = xs.length - 1;
@@ -95,7 +92,7 @@ function crossing(of, drawable, bounds, inside, outside) {
  * 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 samples = Math.max(1, Math.round(options.resolution ?? SAMPLES));
     const { from, to } = interval.ordered(options.over ?? coords.x.graph);
     if (!(to > from))
         return [];
@@ -165,7 +162,7 @@ export function plot(coords, of, options = {}) {
  * 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));
+    const foot = toUnits(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);
@@ -199,9 +196,8 @@ export function riemannBars(name, coords, of, options = {}) {
         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.
+        // Built from four corners rather than a corner and a size: a bar whose top is held on the
+        // graph's own edge has that edge exactly, and adding a height back on 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)]), {}));

package/dist/figure/scale.d.ts

@@ -19,10 +19,10 @@ export interface Scale {
 }
 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;
+export declare function toUnits(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 declare function toGraph(scale: Scale, place: number): number;
 export interface Coords {
     readonly x: Scale;
     readonly y: Scale;

package/dist/figure/scale.js

@@ -15,12 +15,12 @@ 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) {
+export function toUnits(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) {
+export function toGraph(scale, place) {
     return interval.remap(place, scale.units, scale.graph);
 }
 export function coordsOf(x, y) {
@@ -28,5 +28,5 @@ export function coordsOf(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));
+    return vec2(toUnits(coords.x, x), toUnits(coords.y, y));
 }

package/dist/figure/section.d.ts

@@ -19,8 +19,11 @@ export interface Plane {
     normal: Vec3;
 }
 export interface SectionOptions {
-    u?: Interval;
-    v?: Interval;
+    /** The runs of the two parameters, nothing to one each unless named. */
+    over?: {
+        u?: Interval;
+        v?: Interval;
+    };
     resolution?: number | {
         u: number;
         v: number;

package/dist/figure/section.js

@@ -13,6 +13,7 @@
 import { interval } from '../values/interval.js';
 import { vec3 } from '../values/vec3.js';
 import { TOLERANCE } from './tolerance.js';
+import { cornersOf, stepsOf } from './grid.js';
 /** Which edge of a cell each pair of corners is, going round from the corner at
  * the low end of both parameters. */
 const EDGES = [
@@ -128,20 +129,13 @@ function joinEnds(runs, tolerance) {
  * so drawing the points as they are given draws the loop closed.
  */
 export function sectionOf(of, plane, options = {}) {
-    const { u = interval(0, 1), v = interval(0, 1), resolution = 24, tolerance = TOLERANCE } = options;
-    const steps = typeof resolution === 'number' ? { u: resolution, v: resolution } : resolution;
+    const { over = {}, resolution = 24, tolerance = TOLERANCE } = options;
+    const u = over.u ?? interval(0, 1);
+    const v = over.v ?? interval(0, 1);
+    const steps = stepsOf(resolution, 'u', 'v');
     const facing = vec3.normalize(plane.normal);
-    const sample = [];
-    const gap = [];
-    for (let i = 0; i <= steps.u; i += 1) {
-        sample.push([]);
-        gap.push([]);
-        for (let j = 0; j <= steps.v; j += 1) {
-            const point = of(interval.at(u, i / steps.u), interval.at(v, j / steps.v));
-            sample[i].push(point);
-            gap[i].push(vec3.dot(facing, vec3.sub(point, plane.point)));
-        }
-    }
+    const sample = cornersOf(of, u, v, steps);
+    const gap = sample.map((column) => column.map((point) => vec3.dot(facing, vec3.sub(point, plane.point))));
     const points = [];
     const found = new Map();
     const segments = [];
@@ -169,9 +163,8 @@ export function sectionOf(of, plane, options = {}) {
             }
             if (crossed.length !== 4)
                 continue;
-            // A cell whose corners alternate in sign has two ways to be joined and the
-            // grid cannot tell them apart. The middle of the cell decides: the pair of
-            // corners it agrees with is the pair the curve runs around.
+            // A cell whose corners alternate in sign has two ways to be joined, so the middle of the cell
+            // decides: the pair of corners it agrees with is the pair the curve runs around.
             const middle = (gaps[0] + gaps[1] + gaps[2] + gaps[3]) / 4;
             const pairs = middle >= 0 === gaps[0] >= 0 ? [[0, 1], [2, 3]] : [[3, 0], [1, 2]];
             for (const [first, second] of pairs) {

package/dist/figure/space.d.ts

@@ -2,16 +2,17 @@
  * Marks placed at points in space, which a camera turns into the flat nodes the
  * rest of this package already draws.
  *
- * Every builder here hands back a group, because a shape in space is not always
- * one shape on the page: a line running past the eye comes back as the pieces of
- * it the eye can see, and a shape wholly behind the eye comes back as a group
- * with no children, which flattens to no marks rather than to a mark of nothing.
+ * A builder that draws one thing hands back a group, because a shape in space is
+ * not always one shape on the page: a line running past the eye comes back as
+ * the pieces of it the eye can see, and a shape wholly behind the eye comes back
+ * as a group with no children, which flattens to no marks rather than to a mark
+ * of nothing. A builder that draws pieces for a scene to sort hands back those
+ * pieces with the points they came from, which is what says how far off each is.
  */
 import { type Vec3 } from '../values/vec3.js';
 import type { Vec2 } from '../values/vec2.js';
+import type { Fill } from './mark.js';
 import { type GroupNode, type Node, type Style, type TextOptions } from './node.js';
-import { type Interval } from '../values/interval.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 & {
@@ -53,7 +54,7 @@ export type SpaceItem = {
  * sort is stable, and a picture that changed which of two touching faces was on
  * top between frames would flicker.
  */
-export declare function space(name: string, items: readonly SpaceItem[], camera: Camera3): GroupNode;
+export declare function scene3(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.
@@ -67,87 +68,3 @@ export type Arrow3Options = ArrowOptions;
  * 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;
-    /** The run of the second parameter, nothing to one unless named. */
-    v?: Interval;
-    /** How many cells each way. */
-    resolution?: number | {
-        u: number;
-        v: number;
-    };
-    /**
-     * The colour a cell is filled with, given how squarely it faces the light: one
-     * where it faces the light head on, a half where it is edge on, and nothing
-     * where it faces straight away.
-     *
-     * The author supplies this rather than naming two colours to mix, because
-     * mixing two colours means reading them, and a colour here is any CSS colour
-     * written as text with nothing that parses one.
-     */
-    shade: (amount: number) => Fill;
-    /** Which way the light comes from, over the shoulder of an eye on the positive
-     * z axis unless named. */
-    light?: Vec3;
-    /** Whether a cell facing away from the eye is left out. Off by default, because
-     * a count that changes as the camera turns is a count no gate can hold. */
-    cull?: boolean;
-    stroke?: Stroke;
-};
-/**
- * The cells a surface is made of, before they are put in an order.
- *
- * Cells rather than one shape is what makes the depth sort work at all: a surface
- * that folds over itself has no one place in a painting order, and pieces small
- * enough to be flat do.
- *
- * A scene holding a surface and a plane that cuts through it has to sort all of
- * their cells together, since two surfaces sorted apart are two groups and the
- * second is painted over the first whichever way round they stand. Each cell
- * carries the name it was given ahead of its own place in the grid, so an
- * animation can still name a whole surface once its cells are mixed with
- * another's.
- */
-export declare function surfaceCells(name: string, of: (u: number, v: number) => Vec3, camera: Camera3, options: Surface3Options): SpaceItem[];
-/**
- * A surface given by a function of two parameters, drawn as a grid of
- * four-cornered cells ordered back to front.
- */
-export declare function surface3(name: string, of: (u: number, v: number) => Vec3, camera: Camera3, options: Surface3Options): GroupNode;

package/dist/figure/space.js

@@ -2,15 +2,16 @@
  * Marks placed at points in space, which a camera turns into the flat nodes the
  * rest of this package already draws.
  *
- * Every builder here hands back a group, because a shape in space is not always
- * one shape on the page: a line running past the eye comes back as the pieces of
- * it the eye can see, and a shape wholly behind the eye comes back as a group
- * with no children, which flattens to no marks rather than to a mark of nothing.
+ * A builder that draws one thing hands back a group, because a shape in space is
+ * not always one shape on the page: a line running past the eye comes back as
+ * the pieces of it the eye can see, and a shape wholly behind the eye comes back
+ * as a group with no children, which flattens to no marks rather than to a mark
+ * of nothing. A builder that draws pieces for a scene to sort hands back those
+ * pieces with the points they came from, which is what says how far off each is.
  */
 import { vec3 } from '../values/vec3.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.
@@ -104,7 +105,7 @@ function middleDepth(points, camera) {
  * sort is stable, and a picture that changed which of two touching faces was on
  * top between frames would flicker.
  */
-export function space(name, items, camera) {
+export function scene3(name, items, camera) {
     const measured = items.map((item) => ({ node: item.node, depth: middleDepth(item.points, camera) }));
     measured.sort((a, b) => b.depth - a.depth);
     return group(name, measured.map((item) => item.node));
@@ -136,107 +137,3 @@ export function arrow3(name, from, to, camera, options) {
         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;
-}
-/**
- * The cells a surface is made of, before they are put in an order.
- *
- * Cells rather than one shape is what makes the depth sort work at all: a surface
- * that folds over itself has no one place in a painting order, and pieces small
- * enough to be flat do.
- *
- * A scene holding a surface and a plane that cuts through it has to sort all of
- * their cells together, since two surfaces sorted apart are two groups and the
- * second is painted over the first whichever way round they stand. Each cell
- * carries the name it was given ahead of its own place in the grid, so an
- * animation can still name a whole surface once its cells are mixed with
- * another's.
- */
-export function surfaceCells(name, of, camera, options) {
-    const { u = interval(0, 1), v = interval(0, 1), resolution = 24, shade, light = vec3(0, 0, 1), cull = false, stroke } = options;
-    const steps = resolutionOf(resolution);
-    const toLight = vec3.normalize(light);
-    const items = [];
-    for (let i = 0; i < steps.u; i += 1) {
-        for (let j = 0; j < steps.v; j += 1) {
-            const corners = [
-                of(interval.at(u, i / steps.u), interval.at(v, j / steps.v)),
-                of(interval.at(u, (i + 1) / steps.u), interval.at(v, j / steps.v)),
-                of(interval.at(u, (i + 1) / steps.u), interval.at(v, (j + 1) / steps.v)),
-                of(interval.at(u, i / steps.u), interval.at(v, (j + 1) / steps.v)),
-            ];
-            const normal = vec3.normalize(vec3.cross(vec3.sub(corners[1], corners[0]), vec3.sub(corners[3], corners[0])));
-            if (cull) {
-                const middle = corners.reduce((sum, corner) => vec3.add(sum, vec3.scale(corner, 1 / 4)), vec3.ZERO);
-                if (vec3.dot(normal, vec3.sub(camera.eye, middle)) <= 0)
-                    continue;
-            }
-            const fill = shade((vec3.dot(normal, toLight) + 1) / 2);
-            items.push({
-                points: corners,
-                node: polyline3(`${name}/${i}-${j}`, corners, camera, { close: true, fill, stroke }),
-            });
-        }
-    }
-    return items;
-}
-/**
- * A surface given by a function of two parameters, drawn as a grid of
- * four-cornered cells ordered back to front.
- */
-export function surface3(name, of, camera, options) {
-    return space(name, surfaceCells('cell', of, camera, options), camera);
-}

package/dist/figure/surface3.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A surface given by a function of two parameters, drawn as a grid of cells.
+ *
+ * Cells rather than one shape is what makes the depth sort work at all: a
+ * surface that folds over itself has no one place in a painting order, and
+ * pieces small enough to be flat do.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Vec3 } from '../values/vec3.js';
+import type { Fill, Stroke } from './mark.js';
+import type { Camera3 } from './camera.js';
+import { type SpaceItem } from './space.js';
+import type { GroupNode } from './node.js';
+export type Surface3Options = {
+    /** The runs of the two parameters, nothing to one each unless named. */
+    over?: {
+        u?: Interval;
+        v?: Interval;
+    };
+    /** How many cells each way. */
+    resolution?: number | {
+        u: number;
+        v: number;
+    };
+    /**
+     * The colour a cell is filled with, given how squarely it faces the light: one
+     * where it faces the light head on, a half where it is edge on, and nothing
+     * where it faces straight away.
+     *
+     * The author supplies this rather than naming two colours to mix, because
+     * mixing two colours means reading them, and a colour here is any CSS colour
+     * written as text with nothing that parses one.
+     */
+    shade: (amount: number) => Fill;
+    /** Which way the light comes from, over the shoulder of an eye on the positive
+     * z axis unless named. */
+    light?: Vec3;
+    /** Whether a cell facing away from the eye is left out. Off by default, because
+     * a count that changes as the camera turns is a count no gate can hold. */
+    cull?: boolean;
+    stroke?: Stroke;
+};
+/**
+ * The cells a surface is made of, before they are put in an order.
+ *
+ * Cells rather than one shape is what makes the depth sort work at all: a surface
+ * that folds over itself has no one place in a painting order, and pieces small
+ * enough to be flat do.
+ *
+ * A scene holding a surface and a plane that cuts through it has to sort all of
+ * their cells together, since two surfaces sorted apart are two groups and the
+ * second is painted over the first whichever way round they stand. Each cell
+ * carries the name it was given ahead of its own place in the grid, so an
+ * animation can still name a whole surface once its cells are mixed with
+ * another's.
+ */
+export declare function surfaceCells(name: string, of: (u: number, v: number) => Vec3, camera: Camera3, options: Surface3Options): SpaceItem[];
+/**
+ * A surface given by a function of two parameters, drawn as a grid of
+ * four-cornered cells ordered back to front.
+ */
+export declare function surface3(name: string, of: (u: number, v: number) => Vec3, camera: Camera3, options: Surface3Options): GroupNode;

package/dist/figure/surface3.js

@@ -0,0 +1,58 @@
+/**
+ * A surface given by a function of two parameters, drawn as a grid of cells.
+ *
+ * Cells rather than one shape is what makes the depth sort work at all: a
+ * surface that folds over itself has no one place in a painting order, and
+ * pieces small enough to be flat do.
+ */
+import { interval } from '../values/interval.js';
+import { vec3 } from '../values/vec3.js';
+import { cornersOf, stepsOf } from './grid.js';
+import { polyline3, scene3 } from './space.js';
+/**
+ * The cells a surface is made of, before they are put in an order.
+ *
+ * Cells rather than one shape is what makes the depth sort work at all: a surface
+ * that folds over itself has no one place in a painting order, and pieces small
+ * enough to be flat do.
+ *
+ * A scene holding a surface and a plane that cuts through it has to sort all of
+ * their cells together, since two surfaces sorted apart are two groups and the
+ * second is painted over the first whichever way round they stand. Each cell
+ * carries the name it was given ahead of its own place in the grid, so an
+ * animation can still name a whole surface once its cells are mixed with
+ * another's.
+ */
+export function surfaceCells(name, of, camera, options) {
+    const { over = {}, resolution = 24, shade, light = vec3(0, 0, 1), cull = false, stroke } = options;
+    const u = over.u ?? interval(0, 1);
+    const v = over.v ?? interval(0, 1);
+    const steps = stepsOf(resolution, 'u', 'v');
+    const grid = cornersOf(of, u, v, steps);
+    const toLight = vec3.normalize(light);
+    const items = [];
+    for (let i = 0; i < steps.u; i += 1) {
+        for (let j = 0; j < steps.v; j += 1) {
+            const corners = [grid[i][j], grid[i + 1][j], grid[i + 1][j + 1], grid[i][j + 1]];
+            const normal = vec3.normalize(vec3.cross(vec3.sub(corners[1], corners[0]), vec3.sub(corners[3], corners[0])));
+            if (cull) {
+                const middle = corners.reduce((sum, corner) => vec3.add(sum, vec3.scale(corner, 1 / 4)), vec3.ZERO);
+                if (vec3.dot(normal, vec3.sub(camera.eye, middle)) <= 0)
+                    continue;
+            }
+            const fill = shade((vec3.dot(normal, toLight) + 1) / 2);
+            items.push({
+                points: corners,
+                node: polyline3(`${name}/${i}-${j}`, corners, camera, { close: true, fill, stroke }),
+            });
+        }
+    }
+    return items;
+}
+/**
+ * A surface given by a function of two parameters, drawn as a grid of
+ * four-cornered cells ordered back to front.
+ */
+export function surface3(name, of, camera, options) {
+    return scene3(name, surfaceCells('cell', of, camera, options), camera);
+}

package/dist/index.d.ts

@@ -8,6 +8,8 @@
  * Nothing below the line may import anything above it.
  */
 export { clamp, inverseLerp, lerp, remap } from './values/scalar.js';
+export { colourOf, colourText, lerpColour } from './values/colour.js';
+export type { Rgba } from './values/colour.js';
 export { curveFor, easeIn, easeOut, linear, smoothstep } from './values/ease.js';
 export type { Curve } from './values/ease.js';
 export { vec2 } from './values/vec2.js';
@@ -19,10 +21,10 @@ export type { Interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
 export type { Mat3 } from './values/mat3.js';
 export { mat4 } from './values/mat4.js';
-export type { Mat4, OrthographicOptions, PerspectiveOptions } from './values/mat4.js';
+export type { Mat4 } from './values/mat4.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
 export type { Key, Track, TrackValue, Tracks } from './timing/track.js';
-export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, slopeOn, splitCurve, straight, transformPath } from './figure/path.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, splitCurve, straight, tangentOn, transformPath } from './figure/path.js';
 export type { Cubic, Path, Subpath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
 export { TOLERANCE } from './figure/tolerance.js';
@@ -30,7 +32,7 @@ export { areaOf } from './figure/area.js';
 export { differenceOf, intersectionOf, unionOf } from './figure/boolean.js';
 export type { BooleanOptions } from './figure/boolean.js';
 export { containsPoint, flattenPath, nearestEdge, windingAt } from './figure/inside.js';
-export type { Edge, FlattenOptions } from './figure/inside.js';
+export type { FlatEdge, FlattenOptions } from './figure/inside.js';
 export { cutPath } from './figure/cut.js';
 export type { Cut, CutOptions } from './figure/cut.js';
 export { curveCrossings } from './figure/intersect.js';
@@ -50,13 +52,17 @@ 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 { 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 { arrow3, dot3, polyline3, scene3, text3 } from './figure/space.js';
+export type { Arrow3Options, Polyline3Options, SpaceItem, Text3Options } from './figure/space.js';
+export { fieldArrows3, vectorField3 } from './figure/field3.js';
+export type { VectorField3Options } from './figure/field3.js';
+export { surface3, surfaceCells } from './figure/surface3.js';
+export type { Surface3Options } from './figure/surface3.js';
 export { axes3 } from './figure/axis3.js';
 export type { Axes3Options } from './figure/axis3.js';
 export { sectionOf } from './figure/section.js';
 export type { Plane, SectionOptions } from './figure/section.js';
-export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
+export { coordsOf, pointOf, scaleOf, toGraph, toUnits } 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';
@@ -69,17 +75,19 @@ export type { PlayOptions, Span, StaggerOptions } from './figure/timeline.js';
 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 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';
+export { durationOf, isLoop, marksAt, sameMarks, viewAt } from './figure/figure.js';
+export { frameTimesOf, framesOf } from './figure/frames.js';
+export type { Frame, FrameStep, FramesOptions } from './figure/frames.js';
+export type { Figure, TrackValues } from './figure/figure.js';
+export { paintSvg, pathToData, svgElements, svgMarkup } from './paint/svg.js';
+export type { ElementMaker, PaintNode, PaintTarget, SvgElement, SvgMarkupOptions, SvgTheme } from './paint/svg.js';
 export { paintCanvas } from './paint/canvas.js';
 export type { CanvasLike } from './paint/canvas.js';
 export { arrow, brace, bracePath, callout, dot } from './figure/annotate.js';
 export type { ArrowOptions, BraceOptions, BracedOptions, CalloutOptions } from './figure/annotate.js';
 export { typesetElement } from './figure/typeset.js';
 export type { EquationElement } from './figure/typeset.js';
-export { equationFromTex, equationMarks, equationNode } from './figure/equation.js';
+export { equationFromTex, equationNode, equationOf } from './figure/equation.js';
 export type { Equation, EquationBox, EquationOptions } from './figure/equation.js';
 export { glyphToken, matchGlyphs } from './figure/equation-match.js';
 export type { GlyphMatch } from './figure/equation-match.js';