@altpsyche/maths 0.9.4 → 0.10.0

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,103 @@
+/**
+ * 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 { Fill, Stroke } from './mark.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 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,162 @@
+/**
+ * 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, polygon, polyline } from './path.js';
+import { group, shape, text } from './node.js';
+import { interval } from '../values/interval.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));
+}
+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/index.d.ts

@@ -18,6 +18,8 @@ export { interval } from './values/interval.js';
 export type { Interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
 export type { Mat3 } from './values/mat3.js';
+export { mat4 } from './values/mat4.js';
+export type { Mat4, OrthographicOptions, PerspectiveOptions } 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';
@@ -42,6 +44,14 @@ export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.
 export type { AreaOptions, BarsOptions, PlotOptions, TangentOptions } from './figure/plot.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
 export type { AxesOptions, NumberLineOptions, NumberPlaneOptions } from './figure/axis.js';
+export { 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 { 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 type { Coords, Scale } from './figure/scale.js';
 export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
@@ -55,7 +65,7 @@ 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 } from './figure/figure.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';

package/dist/index.js

@@ -13,6 +13,7 @@ export { vec2 } from './values/vec2.js';
 export { vec3 } from './values/vec3.js';
 export { interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
+export { mat4 } from './values/mat4.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
 export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, slopeOn, splitCurve, straight, transformPath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
@@ -26,6 +27,10 @@ export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from
 export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.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 { axes3 } from './figure/axis3.js';
+export { sectionOf } from './figure/section.js';
 export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
 export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
@@ -34,7 +39,7 @@ export { Timeline } 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 } from './figure/figure.js';
+export { at, durationOf, loops, sameMarks, viewAt } from './figure/figure.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/dist/values/mat4.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The transform a point in space carries: how a figure's camera turns a place in
+ * the world into a place on the page.
+ *
+ * Sixteen numbers, column-major, matching the engine's layout the way `Mat3`
+ * does: the first four are the first column rather than the first row, and the
+ * entry at flat index `col * 4 + row` is the one in that column and row. The
+ * fourth row exists so that a translation is a multiplication like every other
+ * move, and the fourth coordinate a point picks up is what a perspective divide
+ * reads.
+ *
+ * There is no inverse here because nothing needs one: a camera builds its view
+ * and its projection forwards and never undoes either. The day something has to
+ * go from the page back into the world, that is when an inverse is written.
+ */
+import { type Vec3 } from './vec3.js';
+export type Mat4 = readonly [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/** Column-major product, so `multiply(a, b)` applies `b` to a point first and
+ * then `a`, which is the order a projection sits outside a view. */
+declare function multiply(a: Mat4, b: Mat4): Mat4;
+/** The last column carries the offset, so this moves a point and leaves a
+ * direction where it was. */
+declare function translation(v: Vec3): Mat4;
+declare function scaling(v: Vec3): Mat4;
+/** Turns y towards z, so a positive angle is anticlockwise seen from the far
+ * end of the x axis looking back at the origin. */
+declare function rotationX(radians: number): Mat4;
+/** Turns z towards x, which is the odd one out: the pair of axes runs z then x
+ * rather than x then z, and writing it the other way flips every y rotation. */
+declare function rotationY(radians: number): Mat4;
+/** Turns x towards y, which is the flat rotation `Mat3` gives with a z left
+ * alone. */
+declare function rotationZ(radians: number): Mat4;
+/**
+ * The view matrix of an eye at `eye` looking at `target`, with `up` saying which
+ * way is up.
+ *
+ * View space looks down its own negative z, so the target comes out on the
+ * negative z axis at the distance between the eye and the target. An `up` lying
+ * along the line of sight has no sideways direction in it and gives a matrix of
+ * zeroes, which is the pose a caller has to avoid rather than one this can fix.
+ */
+declare function lookAt(eye: Vec3, target: Vec3, up: Vec3): Mat4;
+export type PerspectiveOptions = {
+    /** The angle the frame covers up and down, in radians. */
+    fov: number;
+    /** Width over height, so a wide frame shows more sideways rather than less. */
+    aspect: number;
+    near: number;
+    far: number;
+};
+/**
+ * The projection of an eye that sees things smaller the further off they are.
+ *
+ * The third column puts the negated view-space z into the fourth coordinate, so
+ * a point twice as far away comes back with twice the divisor and lands half as
+ * far from the middle of the frame.
+ */
+declare function perspective({ fov, aspect, near, far }: PerspectiveOptions): Mat4;
+export type OrthographicOptions = {
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    near: number;
+    far: number;
+};
+/** The projection of an eye that sees everything at the size it is, which maps
+ * the named box onto the frame and leaves the fourth coordinate at one. */
+declare function orthographic({ left, right, bottom, top, near, far }: OrthographicOptions): Mat4;
+/**
+ * Applies the matrix to a point, taking the translation with it and dividing by
+ * the fourth coordinate the matrix gives it.
+ *
+ * That divide is why a point through `multiply(a, b)` matches the same point
+ * through `b` and then through `a` for matrices that do not touch the fourth
+ * coordinate and not for a perspective matrix: dividing halfway throws away the
+ * fourth coordinate the outer matrix still needed. A fourth coordinate of zero is
+ * a point on the plane through the eye, which has no place on the page at all, so
+ * the divide is skipped and the caller is left to notice.
+ */
+declare function transformPoint(m: Mat4, v: Vec3): Vec3;
+/** Applies the rotation and scale and neither the translation nor the divide,
+ * which is what a direction wants: moving the world must not move where an arrow
+ * points, and a direction has no distance for a perspective to shrink. */
+declare function transformDirection(m: Mat4, v: Vec3): Vec3;
+export declare const mat4: {
+    IDENTITY: Mat4;
+    multiply: typeof multiply;
+    translation: typeof translation;
+    scaling: typeof scaling;
+    rotationX: typeof rotationX;
+    rotationY: typeof rotationY;
+    rotationZ: typeof rotationZ;
+    lookAt: typeof lookAt;
+    perspective: typeof perspective;
+    orthographic: typeof orthographic;
+    transformPoint: typeof transformPoint;
+    transformDirection: typeof transformDirection;
+};
+export {};