@altpsyche/maths 0.2.0

package/dist/figure/morph.js

@@ -0,0 +1,117 @@
+/**
+ * Walking one path into another.
+ *
+ * Two paths can only be walked between when they hold the same number of points,
+ * so the one with fewer is subdivided until they match. Everything is a cubic
+ * already, which is what makes this possible at all: there is no case where a
+ * line has to become an arc, because a line is an arc whose controls sit on it.
+ */
+import { vec2 } from '../values/vec2.js';
+import { pointOn } from './path.js';
+/** One segment cut into two at a fraction, both pieces kept, which is how a
+ * subpath gains a point without changing shape. */
+function halves(from, curve, along) {
+    const a = vec2.lerp(from, curve.control1, along);
+    const b = vec2.lerp(curve.control1, curve.control2, along);
+    const c = vec2.lerp(curve.control2, curve.to, along);
+    const d = vec2.lerp(a, b, along);
+    const e = vec2.lerp(b, c, along);
+    const middle = vec2.lerp(d, e, along);
+    return [
+        { control1: a, control2: d, to: middle },
+        { control1: e, control2: c, to: curve.to },
+    ];
+}
+/**
+ * A subpath rewritten to hold exactly this many segments, drawing the same shape.
+ *
+ * The extra cuts are spread across the longest segments one at a time rather than
+ * all put in the first, so the points stay roughly evenly spaced and the walk
+ * between two paths does not drag one region while another sits still.
+ */
+function withCurves(subpath, wanted) {
+    if (subpath.curves.length >= wanted || subpath.curves.length === 0)
+        return subpath;
+    let curves = [...subpath.curves];
+    while (curves.length < wanted) {
+        let longest = 0;
+        let best = -1;
+        let from = subpath.start;
+        for (let at = 0; at < curves.length; at++) {
+            const span = vec2.distance(from, pointOn(from, curves[at], 1));
+            if (span > longest) {
+                longest = span;
+                best = at;
+            }
+            from = curves[at].to;
+        }
+        const cutAt = best < 0 ? 0 : best;
+        let start = subpath.start;
+        for (let at = 0; at < cutAt; at++)
+            start = curves[at].to;
+        const [first, second] = halves(start, curves[cutAt], 0.5);
+        curves = [...curves.slice(0, cutAt), first, second, ...curves.slice(cutAt + 1)];
+    }
+    return { start: subpath.start, curves, closed: subpath.closed };
+}
+/** A subpath standing still at one point, for a path that has fewer subpaths
+ * than the one it is becoming. It draws nothing and it gives the other side
+ * something to walk from. */
+function collapsed(at, curves) {
+    return {
+        start: at,
+        curves: Array.from({ length: curves }, () => ({ control1: at, control2: at, to: at })),
+        closed: false,
+    };
+}
+/** Where a path sits, for a subpath the other side does not have. Its own first
+ * point, so a shape appearing grows out of where the shape beside it starts. */
+function anchorOf(path) {
+    return path.length > 0 ? path[0].start : vec2(0, 0);
+}
+/** The two paths rewritten to the same shape of point list, drawing exactly what
+ * they drew before. */
+export function alignPaths(from, to) {
+    const count = Math.max(from.length, to.length);
+    const left = [];
+    const right = [];
+    for (let at = 0; at < count; at++) {
+        const a = from[at];
+        const b = to[at];
+        if (a && b) {
+            const curves = Math.max(a.curves.length, b.curves.length);
+            left.push(withCurves(a, curves));
+            right.push(withCurves(b, curves));
+            continue;
+        }
+        if (a) {
+            left.push(a);
+            right.push(collapsed(anchorOf(to), a.curves.length));
+            continue;
+        }
+        if (b) {
+            left.push(collapsed(anchorOf(from), b.curves.length));
+            right.push(b);
+        }
+    }
+    return [left, right];
+}
+/** Part way from one path to another, point by point, after aligning them. */
+export function lerpPath(from, to, along) {
+    const [a, b] = alignPaths(from, to);
+    return a.map((subpath, at) => {
+        const other = b[at];
+        return {
+            start: vec2.lerp(subpath.start, other.start, along),
+            curves: subpath.curves.map((curve, piece) => {
+                const twin = other.curves[piece];
+                return {
+                    control1: vec2.lerp(curve.control1, twin.control1, along),
+                    control2: vec2.lerp(curve.control2, twin.control2, along),
+                    to: vec2.lerp(curve.to, twin.to, along),
+                };
+            }),
+            closed: along < 0.5 ? subpath.closed : other.closed,
+        };
+    });
+}

package/dist/figure/node.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The tree an author builds, and the flat list a painter is given.
+ *
+ * The two are different on purpose. A tree is how a picture is written, with a
+ * group carrying a transform and a style its children inherit. A flat list is
+ * how a picture is drawn, compared and hit tested, with nothing left to inherit
+ * and nothing left to walk.
+ */
+import { type Mat3 } from '../values/mat3.js';
+import type { Path } from './path.js';
+import type { Vec2 } from '../values/vec2.js';
+import type { Fill, Mark, Stroke } from './mark.js';
+/** What a group hands down and a child may override. */
+export interface Style {
+    fill?: Fill;
+    stroke?: Stroke;
+    opacity?: number;
+    family?: string;
+    weight?: number;
+}
+interface Named {
+    /** Its own name among its siblings. The id a mark carries is the names on the
+     * way down joined together. */
+    name: string;
+}
+export interface ShapeNode extends Named, Style {
+    kind: 'shape';
+    path: Path;
+}
+export interface TextNode extends Named, Style {
+    kind: 'text';
+    at: Vec2;
+    text: string;
+    size: number;
+    align?: 'start' | 'middle' | 'end';
+    baseline?: 'alphabetic' | 'middle' | 'hanging';
+}
+export interface GroupNode extends Named {
+    kind: 'group';
+    transform?: Mat3;
+    style?: Style;
+    children: readonly Node[];
+}
+export type Node = ShapeNode | TextNode | GroupNode;
+export declare function shape(name: string, path: Path, style?: Style): ShapeNode;
+/** What a text node takes beyond a shared style, which is where it sits against
+ * its own anchor point rather than anything a group can hand down. */
+export type TextOptions = Style & Pick<TextNode, 'align' | 'baseline'>;
+export declare function text(name: string, at: Vec2, content: string, size: number, options?: TextOptions): TextNode;
+export declare function group(name: string, children: readonly Node[], options?: {
+    transform?: Mat3;
+    style?: Style;
+}): GroupNode;
+/**
+ * The tree resolved into the list a painter draws.
+ *
+ * A shape with neither a fill nor a stroke is left out rather than emitted
+ * invisible, and so is a text with no fill. An invisible mark still costs a
+ * painter an element and still turns up in a comparison between two frames as
+ * something that changed, so a picture that draws nothing should be a list with
+ * nothing in it.
+ */
+export declare function flatten(root: Node, transform?: Mat3, style?: Style): readonly Mark[];
+export {};

package/dist/figure/node.js

@@ -0,0 +1,106 @@
+/**
+ * The tree an author builds, and the flat list a painter is given.
+ *
+ * The two are different on purpose. A tree is how a picture is written, with a
+ * group carrying a transform and a style its children inherit. A flat list is
+ * how a picture is drawn, compared and hit tested, with nothing left to inherit
+ * and nothing left to walk.
+ */
+import { mat3 } from '../values/mat3.js';
+import { transformPath } from './path.js';
+export function shape(name, path, style = {}) {
+    return { kind: 'shape', name, path, ...style };
+}
+export function text(name, at, content, size, options = {}) {
+    return { kind: 'text', name, at, text: content, size, ...options };
+}
+export function group(name, children, options = {}) {
+    return { kind: 'group', name, children, transform: options.transform, style: options.style };
+}
+/** The font a text mark falls back to when no group above it named one. Both
+ * painters need a family by name, and neither has a sensible default. */
+const DEFAULT_FAMILY = 'sans-serif';
+function inherited(parent, own) {
+    return {
+        fill: own.fill ?? parent.fill,
+        stroke: own.stroke ?? parent.stroke,
+        family: own.family ?? parent.family,
+        weight: own.weight ?? parent.weight,
+        opacity: (parent.opacity ?? 1) * (own.opacity ?? 1),
+    };
+}
+/**
+ * Sibling names made unique, so two shapes called the same thing do not become
+ * one id.
+ *
+ * A repeated name gets a number rather than an error, because a figure built in
+ * a loop names its parts the same way on purpose and the author still needs the
+ * ids to be stable frame to frame. Counting per parent keeps them stable: the
+ * same tree gives the same ids every time.
+ */
+function uniqueNames(children) {
+    const seen = new Map();
+    return children.map((child) => {
+        const count = seen.get(child.name) ?? 0;
+        seen.set(child.name, count + 1);
+        return count === 0 ? child.name : `${child.name}#${count + 1}`;
+    });
+}
+function walk(node, prefix, transform, style, into) {
+    const id = prefix === '' ? node.name : `${prefix}/${node.name}`;
+    if (node.kind === 'group') {
+        const next = node.transform ? mat3.multiply(transform, node.transform) : transform;
+        const handed = inherited(style, node.style ?? {});
+        const names = uniqueNames(node.children);
+        node.children.forEach((child, at) => walk({ ...child, name: names[at] }, id, next, handed, into));
+        return;
+    }
+    const settled = inherited(style, node);
+    const opacity = settled.opacity ?? 1;
+    // A group that scales makes the lines inside it thicker, the way it makes
+    // everything else bigger, so the width travels through the same transform the
+    // geometry did rather than staying at the number the author typed.
+    const scale = mat3.scaleFactor(transform);
+    if (node.kind === 'shape') {
+        if (!settled.fill && !settled.stroke)
+            return;
+        into.push({
+            kind: 'path',
+            id,
+            path: transformPath(node.path, transform),
+            fill: settled.fill,
+            stroke: settled.stroke ? { ...settled.stroke, width: settled.stroke.width * scale } : undefined,
+            opacity,
+        });
+        return;
+    }
+    if (!settled.fill)
+        return;
+    into.push({
+        kind: 'text',
+        id,
+        at: mat3.transformPoint(transform, node.at),
+        text: node.text,
+        size: node.size * scale,
+        family: settled.family ?? DEFAULT_FAMILY,
+        weight: settled.weight,
+        align: node.align,
+        baseline: node.baseline,
+        fill: settled.fill,
+        opacity,
+    });
+}
+/**
+ * The tree resolved into the list a painter draws.
+ *
+ * A shape with neither a fill nor a stroke is left out rather than emitted
+ * invisible, and so is a text with no fill. An invisible mark still costs a
+ * painter an element and still turns up in a comparison between two frames as
+ * something that changed, so a picture that draws nothing should be a list with
+ * nothing in it.
+ */
+export function flatten(root, transform = mat3.IDENTITY, style = {}) {
+    const marks = [];
+    walk(root, '', transform, style, marks);
+    return marks;
+}

package/dist/figure/path.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The geometry every drawn shape is made of.
+ *
+ * A path is a list of subpaths, and a subpath is a starting point followed by
+ * cubic Bézier segments. Everything is a cubic, a straight line included, with
+ * its two controls placed a third and two thirds of the way along. One shape for
+ * every curve is what makes two paths interpolable: walking one path into
+ * another is walking each control point to the matching one, and a line turning
+ * into an arc needs no special case.
+ */
+import { type Vec2 } from '../values/vec2.js';
+import { type Mat3 } from '../values/mat3.js';
+/** One cubic segment, carrying its two controls and where it ends. Where it
+ * begins is wherever the segment before it ended. */
+export interface Cubic {
+    readonly control1: Vec2;
+    readonly control2: Vec2;
+    readonly to: Vec2;
+}
+export interface Subpath {
+    readonly start: Vec2;
+    readonly curves: readonly Cubic[];
+    /** A closed subpath joins its end back to its start, which is what decides
+     * whether a fill has a straight edge there and whether the stroke has ends. */
+    readonly closed: boolean;
+}
+export type Path = readonly Subpath[];
+/** A straight segment written as a cubic, with the controls on the line at a
+ * third and two thirds, which is the placement that leaves the pace even. */
+export declare function straight(from: Vec2, to: Vec2): Cubic;
+export declare function line(from: Vec2, to: Vec2): Path;
+/** An open run of straight segments. */
+export declare function polyline(points: readonly Vec2[]): Path;
+/** A closed run of straight segments. */
+export declare function polygon(points: readonly Vec2[]): Path;
+/** An axis-aligned rectangle from its corner and its size. */
+export declare function rect(corner: Vec2, width: number, height: number): Path;
+/** A circle as four cubic quarters, anticlockwise from the positive x axis. */
+export declare function circle(centre: Vec2, radius: number): Path;
+/**
+ * An arc as a run of cubics, each covering at most a quarter turn.
+ *
+ * A single cubic drifts from a true arc as the angle it covers grows, so the
+ * sweep is cut into quarters or less and the control distance is derived per
+ * piece rather than taken from the circle's constant.
+ */
+export declare function arc(centre: Vec2, radius: number, fromAngle: number, toAngle: number): Path;
+/** A point on a cubic, with the segment's own start passed in because a segment
+ * carries where it ends and not where it began. */
+export declare function pointOn(from: Vec2, curve: Cubic, along: number): Vec2;
+/** Every point of a path moved by a transform, which is how a group's transform
+ * reaches the geometry rather than being carried alongside it. */
+export declare function transformPath(path: Path, m: Mat3): Path;
+/** How many points a path holds, which is what two paths have to agree on
+ * before one can be walked into the other. */
+export declare function pointCount(path: Path): number;

package/dist/figure/path.js

@@ -0,0 +1,142 @@
+/**
+ * The geometry every drawn shape is made of.
+ *
+ * A path is a list of subpaths, and a subpath is a starting point followed by
+ * cubic Bézier segments. Everything is a cubic, a straight line included, with
+ * its two controls placed a third and two thirds of the way along. One shape for
+ * every curve is what makes two paths interpolable: walking one path into
+ * another is walking each control point to the matching one, and a line turning
+ * into an arc needs no special case.
+ */
+import { vec2 } from '../values/vec2.js';
+import { mat3 } from '../values/mat3.js';
+/** A straight segment written as a cubic, with the controls on the line at a
+ * third and two thirds, which is the placement that leaves the pace even. */
+export function straight(from, to) {
+    return {
+        control1: vec2.lerp(from, to, 1 / 3),
+        control2: vec2.lerp(from, to, 2 / 3),
+        to,
+    };
+}
+export function line(from, to) {
+    return [{ start: from, curves: [straight(from, to)], closed: false }];
+}
+function through(points, closed) {
+    if (points.length < 2)
+        return [];
+    const start = points[0];
+    const curves = [];
+    for (let at = 1; at < points.length; at++)
+        curves.push(straight(points[at - 1], points[at]));
+    if (closed)
+        curves.push(straight(points[points.length - 1], start));
+    return [{ start, curves, closed }];
+}
+/** An open run of straight segments. */
+export function polyline(points) {
+    return through(points, false);
+}
+/** A closed run of straight segments. */
+export function polygon(points) {
+    return through(points, true);
+}
+/** An axis-aligned rectangle from its corner and its size. */
+export function rect(corner, width, height) {
+    return polygon([
+        corner,
+        vec2(corner.x + width, corner.y),
+        vec2(corner.x + width, corner.y + height),
+        vec2(corner.x, corner.y + height),
+    ]);
+}
+/**
+ * How far a circle's control points sit from the ends of a quarter arc, as a
+ * 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.
+ */
+const KAPPA = 0.5522847498307936;
+/** A circle as four cubic quarters, anticlockwise from the positive x axis. */
+export function circle(centre, radius) {
+    const k = radius * KAPPA;
+    const right = vec2(centre.x + radius, centre.y);
+    const top = vec2(centre.x, centre.y + radius);
+    const left = vec2(centre.x - radius, centre.y);
+    const bottom = vec2(centre.x, centre.y - radius);
+    return [
+        {
+            start: right,
+            curves: [
+                { control1: vec2(right.x, right.y + k), control2: vec2(top.x + k, top.y), to: top },
+                { control1: vec2(top.x - k, top.y), control2: vec2(left.x, left.y + k), to: left },
+                { control1: vec2(left.x, left.y - k), control2: vec2(bottom.x - k, bottom.y), to: bottom },
+                { control1: vec2(bottom.x + k, bottom.y), control2: vec2(right.x, right.y - k), to: right },
+            ],
+            closed: true,
+        },
+    ];
+}
+/**
+ * An arc as a run of cubics, each covering at most a quarter turn.
+ *
+ * A single cubic drifts from a true arc as the angle it covers grows, so the
+ * sweep is cut into quarters or less and the control distance is derived per
+ * piece rather than taken from the circle's constant.
+ */
+export function arc(centre, radius, fromAngle, toAngle) {
+    const sweep = toAngle - fromAngle;
+    if (sweep === 0 || radius === 0)
+        return [];
+    const pieces = Math.max(1, Math.ceil(Math.abs(sweep) / (Math.PI / 2)));
+    const step = sweep / pieces;
+    const reach = (4 / 3) * Math.tan(step / 4);
+    const at = (angle) => vec2(centre.x + radius * Math.cos(angle), centre.y + radius * Math.sin(angle));
+    const start = at(fromAngle);
+    const curves = [];
+    for (let piece = 0; piece < pieces; piece++) {
+        const a0 = fromAngle + step * piece;
+        const a1 = a0 + step;
+        const p0 = at(a0);
+        const p1 = at(a1);
+        const t0 = vec2(-Math.sin(a0), Math.cos(a0));
+        const t1 = vec2(-Math.sin(a1), Math.cos(a1));
+        curves.push({
+            control1: vec2.add(p0, vec2.scale(t0, reach * radius)),
+            control2: vec2.sub(p1, vec2.scale(t1, reach * radius)),
+            to: p1,
+        });
+    }
+    return [{ start, curves, closed: false }];
+}
+/** A point on a cubic, with the segment's own start passed in because a segment
+ * carries where it ends and not where it began. */
+export function pointOn(from, curve, along) {
+    const u = 1 - along;
+    const a = u * u * u;
+    const b = 3 * u * u * along;
+    const c = 3 * u * along * along;
+    const d = along * along * along;
+    return vec2(a * from.x + b * curve.control1.x + c * curve.control2.x + d * curve.to.x, a * from.y + b * curve.control1.y + c * curve.control2.y + d * curve.to.y);
+}
+/** Every point of a path moved by a transform, which is how a group's transform
+ * reaches the geometry rather than being carried alongside it. */
+export function transformPath(path, m) {
+    const point = (v) => mat3.transformPoint(m, v);
+    return path.map((subpath) => ({
+        start: point(subpath.start),
+        curves: subpath.curves.map((curve) => ({
+            control1: point(curve.control1),
+            control2: point(curve.control2),
+            to: point(curve.to),
+        })),
+        closed: subpath.closed,
+    }));
+}
+/** How many points a path holds, which is what two paths have to agree on
+ * before one can be walked into the other. */
+export function pointCount(path) {
+    return path.reduce((total, subpath) => total + 1 + subpath.curves.length * 3, 0);
+}

package/dist/figure/timeline.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Animations in the order they happen, turned into absolute spans.
+ *
+ * The order is written once and compiled once. Reading it at a time is then a
+ * walk over a sorted list, which is what lets the same timeline answer a page
+ * playing forward, a reader dragging backwards, and a recorder stepping.
+ */
+import { type Curve } from '../values/ease.js';
+import type { Animation } from './animation.js';
+import type { Mark } from './mark.js';
+export interface Span {
+    animation: Animation;
+    from: number;
+    to: number;
+    curve: Curve;
+}
+export interface PlayOptions {
+    /** How the change is paced. Still at both ends unless a figure says otherwise,
+     * because a move that starts and stops abruptly reads as a jump. */
+    curve?: Curve;
+    /** Seconds after the previous entry finished. A negative wait overlaps this
+     * animation with the one before it. */
+    after?: number;
+}
+/**
+ * The ordered list, built by naming one thing after another.
+ *
+ * Each call hands back a new timeline rather than changing this one, so a figure
+ * that builds a timeline inside a function called every frame cannot accumulate
+ * entries it did not mean to.
+ */
+export declare class Timeline {
+    readonly spans: readonly Span[];
+    readonly duration: number;
+    private constructor();
+    static empty(): Timeline;
+    play(animation: Animation, seconds: number, options?: PlayOptions): Timeline;
+    /** Several changes over one span, which is how two things move at once. */
+    together(animations: readonly Animation[], seconds: number, options?: PlayOptions): Timeline;
+    wait(seconds: number): Timeline;
+    /**
+     * The marks as every span leaves them at a time.
+     *
+     * A span that has not started yet is applied at nothing and a span already
+     * finished is applied in full, which is what makes this a function of time
+     * rather than a record of what has been played. A mark waiting to fade in is
+     * therefore invisible rather than solid, and one that has faded out stays gone.
+     */
+    at(marks: readonly Mark[], seconds: number): readonly Mark[];
+}

package/dist/figure/timeline.js

@@ -0,0 +1,61 @@
+/**
+ * Animations in the order they happen, turned into absolute spans.
+ *
+ * The order is written once and compiled once. Reading it at a time is then a
+ * walk over a sorted list, which is what lets the same timeline answer a page
+ * playing forward, a reader dragging backwards, and a recorder stepping.
+ */
+import { curveFor } from '../values/ease.js';
+/**
+ * The ordered list, built by naming one thing after another.
+ *
+ * Each call hands back a new timeline rather than changing this one, so a figure
+ * that builds a timeline inside a function called every frame cannot accumulate
+ * entries it did not mean to.
+ */
+export class Timeline {
+    spans;
+    duration;
+    constructor(spans, duration) {
+        this.spans = spans;
+        this.duration = duration;
+    }
+    static empty() {
+        return new Timeline([], 0);
+    }
+    play(animation, seconds, options = {}) {
+        const from = this.duration + (options.after ?? 0);
+        const to = from + seconds;
+        const span = { animation, from, to, curve: options.curve ?? curveFor(true, true) };
+        return new Timeline([...this.spans, span], Math.max(this.duration, to));
+    }
+    /** Several changes over one span, which is how two things move at once. */
+    together(animations, seconds, options = {}) {
+        let built = this;
+        animations.forEach((animation, at) => {
+            built = built.play(animation, seconds, at === 0 ? options : { ...options, after: -seconds });
+        });
+        return built;
+    }
+    wait(seconds) {
+        return new Timeline(this.spans, this.duration + seconds);
+    }
+    /**
+     * The marks as every span leaves them at a time.
+     *
+     * A span that has not started yet is applied at nothing and a span already
+     * finished is applied in full, which is what makes this a function of time
+     * rather than a record of what has been played. A mark waiting to fade in is
+     * therefore invisible rather than solid, and one that has faded out stays gone.
+     */
+    at(marks, seconds) {
+        let built = marks;
+        for (const span of this.spans) {
+            const width = span.to - span.from;
+            const raw = width <= 0 ? (seconds >= span.to ? 1 : 0) : (seconds - span.from) / width;
+            const held = raw <= 0 ? 0 : raw >= 1 ? 1 : raw;
+            built = span.animation(built, span.curve(held));
+        }
+        return built;
+    }
+}

package/dist/figure/trim.d.ts

@@ -0,0 +1,10 @@
+import { type Path } from './path.js';
+/**
+ * The path up to a fraction of its total length.
+ *
+ * A fraction at or past one is the path itself, untouched, so a finished drawing
+ * is the same geometry the author wrote rather than a rebuilt copy of it. A
+ * subpath the cut has not reached is left out entirely, and the one it lands in
+ * ends with a segment split where the cut falls.
+ */
+export declare function trimPath(path: Path, fraction: number): Path;