@altpsyche/maths 0.9.5 → 0.11.0

package/dist/figure/figure.js

@@ -11,6 +11,7 @@
  */
 import { sampleTracks } from '../timing/track.js';
 import { flatten } from './node.js';
+import { resolveExtent, viewMatrix } from './extent.js';
 export function durationOf(figure) {
     return figure.duration ?? figure.timeline?.duration ?? 0;
 }
@@ -21,6 +22,18 @@ export function at(figure, seconds) {
     const marks = flatten(tree);
     return figure.timeline ? figure.timeline.at(marks, seconds) : marks;
 }
+/**
+ * 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 function viewAt(figure, seconds, width, height) {
+    const extent = resolveExtent(figure.extent, width / height, seconds);
+    return viewMatrix(extent, figure.fit ?? 'contain', width, height);
+}
 /** 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

package/dist/figure/section.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The curve where a plane cuts a surface, found on the grid the surface is
+ * already drawn from.
+ *
+ * This is marching squares, with the plane's signed distance as the value at each
+ * grid point. A crossing point is found by walking along a cell edge to where
+ * that distance reaches nothing, and because signed distance to a plane changes
+ * evenly along a straight line, every point this finds lies on the plane exactly.
+ * It lies on the chord between two samples of the surface rather than on the
+ * surface itself, which is the whole of the error and is why halving the cell
+ * size quarters it.
+ */
+import { type Interval } from '../values/interval.js';
+import { type Vec3 } from '../values/vec3.js';
+export interface Plane {
+    /** A point the plane passes through. */
+    point: Vec3;
+    /** Which way the plane faces. Its length does not matter. */
+    normal: Vec3;
+}
+export interface SectionOptions {
+    u?: Interval;
+    v?: Interval;
+    resolution?: number | {
+        u: number;
+        v: number;
+    };
+    /** How close two ends come before they are read as the same place. */
+    tolerance?: number;
+}
+/**
+ * The runs of points where a plane cuts a surface, in space.
+ *
+ * A run whose two ends meet comes back with its first point repeated at the end,
+ * so drawing the points as they are given draws the loop closed.
+ */
+export declare function sectionOf(of: (u: number, v: number) => Vec3, plane: Plane, options?: SectionOptions): Vec3[][];

package/dist/figure/section.js

@@ -0,0 +1,184 @@
+/**
+ * The curve where a plane cuts a surface, found on the grid the surface is
+ * already drawn from.
+ *
+ * This is marching squares, with the plane's signed distance as the value at each
+ * grid point. A crossing point is found by walking along a cell edge to where
+ * that distance reaches nothing, and because signed distance to a plane changes
+ * evenly along a straight line, every point this finds lies on the plane exactly.
+ * It lies on the chord between two samples of the surface rather than on the
+ * surface itself, which is the whole of the error and is why halving the cell
+ * size quarters it.
+ */
+import { interval } from '../values/interval.js';
+import { vec3 } from '../values/vec3.js';
+import { TOLERANCE } from './tolerance.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 = [
+    [0, 1],
+    [1, 2],
+    [2, 3],
+    [3, 0],
+];
+function keyFor(i, j, edge) {
+    if (edge === 0)
+        return `h${i},${j}`;
+    if (edge === 1)
+        return `v${i + 1},${j}`;
+    if (edge === 2)
+        return `h${i},${j + 1}`;
+    return `v${i},${j}`;
+}
+/**
+ * The chains a set of segments makes, each walked from one loose end to the other
+ * and then round whatever loops are left.
+ */
+function chainsOf(segments, count) {
+    const next = new Map();
+    for (const [from, to] of segments) {
+        if (!next.has(from))
+            next.set(from, []);
+        if (!next.has(to))
+            next.set(to, []);
+        next.get(from).push(to);
+        next.get(to).push(from);
+    }
+    const used = segments.map(() => false);
+    const at = new Map();
+    segments.forEach(([from, to], index) => {
+        if (!at.has(from))
+            at.set(from, []);
+        if (!at.has(to))
+            at.set(to, []);
+        at.get(from).push(index);
+        at.get(to).push(index);
+    });
+    const walkFrom = (start) => {
+        const chain = [start];
+        let here = start;
+        for (;;) {
+            const step = (at.get(here) ?? []).find((index) => !used[index]);
+            if (step === undefined)
+                return chain;
+            used[step] = true;
+            const [from, to] = segments[step];
+            here = from === here ? to : from;
+            chain.push(here);
+        }
+    };
+    const chains = [];
+    // Loose ends first, so a chain that runs off the edge of the grid is walked
+    // from its end rather than being started in the middle and coming out as two.
+    for (let point = 0; point < count; point += 1) {
+        if ((next.get(point)?.length ?? 0) === 1) {
+            const chain = walkFrom(point);
+            if (chain.length > 1)
+                chains.push(chain);
+        }
+    }
+    for (let index = 0; index < segments.length; index += 1) {
+        if (used[index])
+            continue;
+        const chain = walkFrom(segments[index][0]);
+        if (chain.length > 1)
+            chains.push(chain);
+    }
+    return chains;
+}
+/** Chains whose ends meet joined into one, which is what closes a curve that the
+ * grid split at the seam where a parameter wraps round. */
+function joinEnds(runs, tolerance) {
+    const meets = (a, b) => vec3.magnitude(vec3.sub(a, b)) <= tolerance;
+    const open = runs.slice();
+    const done = [];
+    while (open.length > 0) {
+        let run = open.shift();
+        for (;;) {
+            if (run.length > 2 && meets(run[0], run[run.length - 1]))
+                break;
+            const found = open.findIndex((other) => meets(run[run.length - 1], other[0]) ||
+                meets(run[run.length - 1], other[other.length - 1]) ||
+                meets(run[0], other[0]) ||
+                meets(run[0], other[other.length - 1]));
+            if (found === -1)
+                break;
+            const other = open.splice(found, 1)[0];
+            if (meets(run[run.length - 1], other[0]))
+                run = [...run, ...other.slice(1)];
+            else if (meets(run[run.length - 1], other[other.length - 1]))
+                run = [...run, ...other.slice(0, -1).reverse()];
+            else if (meets(run[0], other[other.length - 1]))
+                run = [...other.slice(0, -1), ...run];
+            else
+                run = [...other.slice(1).reverse(), ...run];
+        }
+        // A run whose two ends meet is given its first point again, so a caller draws
+        // a loop by drawing the points it is handed and needs no flag.
+        if (run.length > 2 && meets(run[0], run[run.length - 1]))
+            run = [...run.slice(0, -1), run[0]];
+        done.push(run);
+    }
+    return done;
+}
+/**
+ * The runs of points where a plane cuts a surface, in space.
+ *
+ * A run whose two ends meet comes back with its first point repeated at the end,
+ * 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 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 points = [];
+    const found = new Map();
+    const segments = [];
+    for (let i = 0; i < steps.u; i += 1) {
+        for (let j = 0; j < steps.v; j += 1) {
+            const corners = [sample[i][j], sample[i + 1][j], sample[i + 1][j + 1], sample[i][j + 1]];
+            const gaps = [gap[i][j], gap[i + 1][j], gap[i + 1][j + 1], gap[i][j + 1]];
+            const crossed = [];
+            for (let edge = 0; edge < 4; edge += 1) {
+                const [from, to] = EDGES[edge];
+                if (gaps[from] >= 0 === gaps[to] >= 0)
+                    continue;
+                const key = keyFor(i, j, edge);
+                let index = found.get(key);
+                if (index === undefined) {
+                    const along = gaps[from] / (gaps[from] - gaps[to]);
+                    index = points.push(vec3.lerp(corners[from], corners[to], along)) - 1;
+                    found.set(key, index);
+                }
+                crossed.push(edge);
+            }
+            if (crossed.length === 2) {
+                segments.push([found.get(keyFor(i, j, crossed[0])), found.get(keyFor(i, j, crossed[1]))]);
+                continue;
+            }
+            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.
+            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) {
+                segments.push([found.get(keyFor(i, j, first)), found.get(keyFor(i, j, second))]);
+            }
+        }
+    }
+    const runs = chainsOf(segments, points.length).map((chain) => chain.map((index) => points[index]));
+    return joinEnds(runs, tolerance);
+}

package/dist/figure/space.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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.
+ */
+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 { 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
+     * cut comes back open however this is set, since closing it would draw an edge
+     * that is nowhere in the world. */
+    close?: boolean;
+};
+/** A run of straight segments through points in space. */
+export declare function polyline3(name: string, points: readonly Vec3[], camera: Camera3, options?: Polyline3Options): GroupNode;
+/** A disc marking a point in space. Its radius is in figure units and does not
+ * shrink with distance, because a dot marks where something is rather than how
+ * big it is. */
+export declare function dot3(name: string, at: Vec3, radius: number, fill: Fill, camera: Camera3): GroupNode;
+export type Text3Options = TextOptions & {
+    /** How far the label stands off the point it names, in figure units, applied
+     * after the point is placed. */
+    offset?: Vec2;
+};
+/** A label at a point in space. The letters stay upright and stay the size they
+ * are given, since a label is read rather than seen in perspective. */
+export declare function text3(name: string, at: Vec3, content: string, size: number, camera: Camera3, options?: Text3Options): GroupNode;
+/** A drawn piece and the points in space it was drawn from, which are what say
+ * how far off it is. */
+export type SpaceItem = {
+    points: readonly Vec3[];
+    node: Node;
+};
+/**
+ * A group whose children are ordered back to front, so the near piece is painted
+ * over the far one.
+ *
+ * This is the painter's algorithm, and what it cannot do is worth knowing before
+ * it is used: two pieces that pass through each other, and three that overlap in
+ * a ring, have no one order at all, and no comparison of depths can find one. The
+ * answer for those is smaller pieces, which is why a surface is cut into cells.
+ *
+ * Two pieces at the same depth keep the order the author gave them, since the
+ * 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 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;
+    /** 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

@@ -0,0 +1,242 @@
+/**
+ * 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.
+ */
+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.
+ *
+ * Depth changes evenly along a segment, because lining the world up with the eye
+ * moves and turns a point and never divides it, so the crossing is one division
+ * rather than a search.
+ */
+function crossingAt(from, to, near) {
+    return (near - from) / (to - from);
+}
+/**
+ * The pieces of a run of points in space that the eye can see, cut where they
+ * cross the near plane.
+ *
+ * A point nearer the eye than the near plane has no place on the page: under a
+ * perspective the divide flips its sign and puts it on the wrong side of the
+ * frame, so the segment is cut rather than drawn to it.
+ */
+function visibleRuns(points, camera) {
+    const near = camera.projection.near;
+    const seen = points.map((point) => camera.project(point));
+    const uncut = seen.every((point) => point.inFront);
+    const runs = [];
+    let current = [];
+    for (let i = 0; i < points.length; i += 1) {
+        const here = seen[i];
+        if (here.inFront) {
+            if (i > 0 && !seen[i - 1].inFront) {
+                const along = crossingAt(seen[i - 1].depth, here.depth, near);
+                current.push(camera.project(vec3.lerp(points[i - 1], points[i], along)).at);
+            }
+            current.push(here.at);
+            continue;
+        }
+        if (i > 0 && seen[i - 1].inFront) {
+            const along = crossingAt(seen[i - 1].depth, here.depth, near);
+            current.push(camera.project(vec3.lerp(points[i - 1], points[i], along)).at);
+        }
+        if (current.length > 1)
+            runs.push({ points: current, whole: false });
+        current = [];
+    }
+    if (current.length > 1)
+        runs.push({ points: current, whole: uncut });
+    return runs;
+}
+/** A run of straight segments through points in space. */
+export function polyline3(name, points, camera, options = {}) {
+    const { close = false, ...style } = options;
+    const runs = visibleRuns(points, camera);
+    return group(name, runs.map((run) => shape('run', close && run.whole ? polygon(run.points) : polyline(run.points), style)));
+}
+/** A disc marking a point in space. Its radius is in figure units and does not
+ * shrink with distance, because a dot marks where something is rather than how
+ * big it is. */
+export function dot3(name, at, radius, fill, camera) {
+    const seen = camera.project(at);
+    return group(name, seen.inFront ? [shape('disc', circle(seen.at, radius), { fill })] : []);
+}
+/** A label at a point in space. The letters stay upright and stay the size they
+ * are given, since a label is read rather than seen in perspective. */
+export function text3(name, at, content, size, camera, options = {}) {
+    const { offset, ...style } = options;
+    const seen = camera.project(at);
+    const anchor = offset ? { x: seen.at.x + offset.x, y: seen.at.y + offset.y } : seen.at;
+    return group(name, seen.inFront ? [text('label', anchor, content, size, style)] : []);
+}
+/**
+ * The mean of a piece's own depths, so a piece is ordered by where its middle is
+ * rather than by whichever corner happens to be nearest.
+ */
+function middleDepth(points, camera) {
+    if (points.length === 0)
+        return 0;
+    let total = 0;
+    for (const point of points)
+        total += camera.project(point).depth;
+    return total / points.length;
+}
+/**
+ * A group whose children are ordered back to front, so the near piece is painted
+ * over the far one.
+ *
+ * This is the painter's algorithm, and what it cannot do is worth knowing before
+ * it is used: two pieces that pass through each other, and three that overlap in
+ * a ring, have no one order at all, and no comparison of depths can find one. The
+ * answer for those is smaller pieces, which is why a surface is cut into cells.
+ *
+ * Two pieces at the same depth keep the order the author gave them, since the
+ * 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) {
+    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));
+}
+/**
+ * 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;
+}
+/**
+ * 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);
+}