@altpsyche/maths 0.9.5 → 0.11.0

package/dist/figure/streamline.d.ts

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

package/dist/figure/streamline.js

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

package/dist/index.d.ts

@@ -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';
@@ -40,8 +42,20 @@ export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
 export type { Bounds } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
 export type { AreaOptions, BarsOptions, PlotOptions, TangentOptions } from './figure/plot.js';
+export { vectorField } from './figure/field.js';
+export { streamlineOf } from './figure/streamline.js';
+export type { StreamlineOptions } from './figure/streamline.js';
+export type { VectorFieldOptions } from './figure/field.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
 export type { AxesOptions, NumberLineOptions, NumberPlaneOptions } from './figure/axis.js';
+export { camera3, orthographic, perspective } from './figure/camera.js';
+export type { Camera3, Camera3Choice, OrthographicChoice, PerspectiveChoice, Projected, Projection } from './figure/camera.js';
+export { arrow3, dot3, fieldArrows3, polyline3, space, surface3, surfaceCells, text3, vectorField3 } from './figure/space.js';
+export type { Arrow3Options, Polyline3Options, SpaceItem, Surface3Options, Text3Options, VectorField3Options } from './figure/space.js';
+export { axes3 } from './figure/axis3.js';
+export type { Axes3Options } from './figure/axis3.js';
+export { sectionOf } from './figure/section.js';
+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 +69,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';
@@ -25,7 +26,13 @@ export { curveCrossings } from './figure/intersect.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export { boundsOf, boundsOfMarks, centreOf } from './figure/bounds.js';
 export { areaUnder, plot, riemannBars, slopeOf, tangentAt } from './figure/plot.js';
+export { vectorField } from './figure/field.js';
+export { streamlineOf } from './figure/streamline.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
+export { camera3, orthographic, perspective } from './figure/camera.js';
+export { arrow3, dot3, fieldArrows3, polyline3, space, surface3, surfaceCells, text3, vectorField3 } from './figure/space.js';
+export { axes3 } from './figure/axis3.js';
+export { sectionOf } from './figure/section.js';
 export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
 export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
@@ -34,7 +41,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 {};

package/dist/values/mat4.js

@@ -0,0 +1,193 @@
+/**
+ * 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 { vec3 } from './vec3.js';
+const IDENTITY = [
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+];
+/** 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. */
+function multiply(a, b) {
+    const [a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15] = a;
+    const [b0, b1, b2, b3, b4, b5, b6, b7, b8, b9, b10, b11, b12, b13, b14, b15] = b;
+    return [
+        a0 * b0 + a4 * b1 + a8 * b2 + a12 * b3,
+        a1 * b0 + a5 * b1 + a9 * b2 + a13 * b3,
+        a2 * b0 + a6 * b1 + a10 * b2 + a14 * b3,
+        a3 * b0 + a7 * b1 + a11 * b2 + a15 * b3,
+        a0 * b4 + a4 * b5 + a8 * b6 + a12 * b7,
+        a1 * b4 + a5 * b5 + a9 * b6 + a13 * b7,
+        a2 * b4 + a6 * b5 + a10 * b6 + a14 * b7,
+        a3 * b4 + a7 * b5 + a11 * b6 + a15 * b7,
+        a0 * b8 + a4 * b9 + a8 * b10 + a12 * b11,
+        a1 * b8 + a5 * b9 + a9 * b10 + a13 * b11,
+        a2 * b8 + a6 * b9 + a10 * b10 + a14 * b11,
+        a3 * b8 + a7 * b9 + a11 * b10 + a15 * b11,
+        a0 * b12 + a4 * b13 + a8 * b14 + a12 * b15,
+        a1 * b12 + a5 * b13 + a9 * b14 + a13 * b15,
+        a2 * b12 + a6 * b13 + a10 * b14 + a14 * b15,
+        a3 * b12 + a7 * b13 + a11 * b14 + a15 * b15,
+    ];
+}
+/** The last column carries the offset, so this moves a point and leaves a
+ * direction where it was. */
+function translation(v) {
+    return [
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        v.x, v.y, v.z, 1,
+    ];
+}
+function scaling(v) {
+    return [
+        v.x, 0, 0, 0,
+        0, v.y, 0, 0,
+        0, 0, v.z, 0,
+        0, 0, 0, 1,
+    ];
+}
+/** Turns y towards z, so a positive angle is anticlockwise seen from the far
+ * end of the x axis looking back at the origin. */
+function rotationX(radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return [
+        1, 0, 0, 0,
+        0, c, s, 0,
+        0, -s, c, 0,
+        0, 0, 0, 1,
+    ];
+}
+/** 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. */
+function rotationY(radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return [
+        c, 0, -s, 0,
+        0, 1, 0, 0,
+        s, 0, c, 0,
+        0, 0, 0, 1,
+    ];
+}
+/** Turns x towards y, which is the flat rotation `Mat3` gives with a z left
+ * alone. */
+function rotationZ(radians) {
+    const c = Math.cos(radians);
+    const s = Math.sin(radians);
+    return [
+        c, s, 0, 0,
+        -s, c, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+    ];
+}
+/**
+ * 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.
+ */
+function lookAt(eye, target, up) {
+    const forward = vec3.normalize(vec3.sub(target, eye));
+    const right = vec3.normalize(vec3.cross(forward, up));
+    const above = vec3.cross(right, forward);
+    return [
+        right.x, above.x, -forward.x, 0,
+        right.y, above.y, -forward.y, 0,
+        right.z, above.z, -forward.z, 0,
+        -vec3.dot(right, eye), -vec3.dot(above, eye), vec3.dot(forward, eye), 1,
+    ];
+}
+/**
+ * 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.
+ */
+function perspective({ fov, aspect, near, far }) {
+    const focal = 1 / Math.tan(fov / 2);
+    return [
+        focal / aspect, 0, 0, 0,
+        0, focal, 0, 0,
+        0, 0, (far + near) / (near - far), -1,
+        0, 0, (2 * far * near) / (near - far), 0,
+    ];
+}
+/** 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. */
+function orthographic({ left, right, bottom, top, near, far }) {
+    return [
+        2 / (right - left), 0, 0, 0,
+        0, 2 / (top - bottom), 0, 0,
+        0, 0, -2 / (far - near), 0,
+        -(right + left) / (right - left),
+        -(top + bottom) / (top - bottom),
+        -(far + near) / (far - near),
+        1,
+    ];
+}
+/**
+ * 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.
+ */
+function transformPoint(m, v) {
+    const w = m[3] * v.x + m[7] * v.y + m[11] * v.z + m[15];
+    const divisor = w === 0 ? 1 : w;
+    return {
+        x: (m[0] * v.x + m[4] * v.y + m[8] * v.z + m[12]) / divisor,
+        y: (m[1] * v.x + m[5] * v.y + m[9] * v.z + m[13]) / divisor,
+        z: (m[2] * v.x + m[6] * v.y + m[10] * v.z + m[14]) / divisor,
+    };
+}
+/** 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. */
+function transformDirection(m, v) {
+    return {
+        x: m[0] * v.x + m[4] * v.y + m[8] * v.z,
+        y: m[1] * v.x + m[5] * v.y + m[9] * v.z,
+        z: m[2] * v.x + m[6] * v.y + m[10] * v.z,
+    };
+}
+export const mat4 = {
+    IDENTITY,
+    multiply,
+    translation,
+    scaling,
+    rotationX,
+    rotationY,
+    rotationZ,
+    lookAt,
+    perspective,
+    orthographic,
+    transformPoint,
+    transformDirection,
+};

package/package.json

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