@altpsyche/maths 0.8.0 → 0.9.0

package/README.md

@@ -163,6 +163,47 @@ matters. The slope in the demo is a value of the walk, so it is worked out by th
 track and cannot drift from the dot. The rise is counted by the clock, which is honest only because
 the dot has stopped by the time it counts: two clocks running at once would be free to disagree.
 
+## Two shapes combined
+
+<img src="docs/boolean.svg" width="720" alt="Two discs drawn three times side by side: everything either one covers, only what both cover, and the first with the second taken out of it.">
+
+`unionOf` is everything either path covers, `intersectionOf` is only what both cover, and
+`differenceOf` is the first with the second taken out of it. Each input is closed loops that do not
+cross themselves, and a loop left open is closed by a straight run back to where it started before
+anything else happens.
+
+```ts
+import { circle, differenceOf, intersectionOf, unionOf, vec2 } from '@altpsyche/maths';
+
+const first = circle(vec2(0, 0), 0.9);
+const second = circle(vec2(-0.6, 0), 0.36);
+
+unionOf(first, second);
+intersectionOf(first, second);
+differenceOf(first, second);
+```
+
+A result may have a hole even though an input may not. A disc with a smaller disc taken out of it is
+a ring, which is an outer loop and an inner loop wound the opposite way, and the nonzero rule the
+mark already carries leaves the middle empty.
+
+The work happens in four steps, and each of them is a call of its own. `curveCrossings` says where
+two cubics cross, by halving both curves and following only the halves whose boxes still overlap,
+then sharpening what it finds by Newton's method. `cutPath` puts a cut wherever something crosses,
+so that afterwards every piece is wholly inside the other path or wholly outside it. `containsPoint`
+decides which of those a piece is, by counting how many times the other path winds round its middle.
+`areaOf` says how much a path encloses, in closed form rather than by sampling, which is what every
+claim above is checked against.
+
+<img src="docs/boolean-strip.svg" width="960" alt="Four frames side by side, each showing the three panels, as the small disc walks from clear of the large one, through touching it at one point, through overlapping it, to sitting wholly inside it.">
+
+Four times of one figure. A small disc walks across a larger one: clear of it, touching it at one
+point, crossing it at two, and wholly inside it. Those are the four cases this kind of code gets
+silently wrong, which is why the demo walks through all of them rather than drawing one.
+
+Two edges that lie on top of each other for a stretch have no one answer, and what comes back for
+them is decided by the tolerance rather than by the geometry.
+
 ## The animations
 
 `fadeIn`, `fadeOut`, `fadeTo`, `draw`, `morph`, `morphEquation`, `countTo`, `moveBy`, `rotate`,

package/dist/figure/area.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How much a path encloses.
+ *
+ * This is Green's theorem, which turns the area inside a closed loop into an
+ * integral round its edge, and for a cubic that integral has a closed form. So
+ * the answer is worked out rather than sampled, and it is exact for the shape
+ * the cubics actually draw.
+ *
+ * The sign is the direction the loop is wound in, positive anticlockwise. That
+ * is what makes a hole subtract: a loop wound the other way inside another one
+ * encloses a negative amount, and the two added together are the ring.
+ */
+import type { Path } from './path.js';
+/**
+ * How much a path encloses, positive where it is wound anticlockwise.
+ *
+ * A subpath left open is closed by the straight run back to where it started,
+ * since an open loop encloses nothing on its own. Every subpath is added, so a
+ * ring written as an outer loop and an inner loop wound the other way comes
+ * back as the difference between the two discs.
+ */
+export declare function areaOf(path: Path): number;

package/dist/figure/area.js

@@ -0,0 +1,45 @@
+/** Twice the area of the triangle two points make with the origin, positive
+ * anticlockwise. */
+function wedge(a, b) {
+    return a.x * b.y - b.x * a.y;
+}
+/**
+ * What one piece contributes to the integral round the loop.
+ *
+ * Each pair of the piece's four points contributes the triangle it makes with
+ * the origin, and the weights are what integrating a cubic against its own
+ * derivative leaves: six, three, one, three, three and six twentieths, in the
+ * order the pairs are taken.
+ */
+function pieceArea(from, curve) {
+    const { control1, control2, to } = curve;
+    return ((6 * wedge(from, control1) +
+        3 * wedge(from, control2) +
+        wedge(from, to) +
+        3 * wedge(control1, control2) +
+        3 * wedge(control1, to) +
+        6 * wedge(control2, to)) /
+        20);
+}
+/**
+ * How much a path encloses, positive where it is wound anticlockwise.
+ *
+ * A subpath left open is closed by the straight run back to where it started,
+ * since an open loop encloses nothing on its own. Every subpath is added, so a
+ * ring written as an outer loop and an inner loop wound the other way comes
+ * back as the difference between the two discs.
+ */
+export function areaOf(path) {
+    let total = 0;
+    for (const subpath of path) {
+        if (subpath.curves.length === 0)
+            continue;
+        let from = subpath.start;
+        for (const curve of subpath.curves) {
+            total += pieceArea(from, curve);
+            from = curve.to;
+        }
+        total += wedge(from, subpath.start) / 2;
+    }
+    return total;
+}

package/dist/figure/boolean.d.ts

@@ -0,0 +1,13 @@
+import { type Path } from './path.js';
+export interface BooleanOptions {
+    /** How close two things come before they count as the same place, in the
+     * picture's own units. It decides where two paths are read as crossing and
+     * which ends are read as meeting. */
+    readonly tolerance?: number;
+}
+/** Everything either path covers. */
+export declare function unionOf(first: Path, second: Path, options?: BooleanOptions): Path;
+/** Only what both paths cover. */
+export declare function intersectionOf(first: Path, second: Path, options?: BooleanOptions): Path;
+/** The first path with the second taken out of it. */
+export declare function differenceOf(first: Path, second: Path, options?: BooleanOptions): Path;

package/dist/figure/boolean.js

@@ -0,0 +1,173 @@
+/**
+ * Union, intersection and difference on paths.
+ *
+ * Both paths are cut at every place they cross, so that after the cutting every
+ * piece is wholly inside the other path or wholly outside it. Each piece is
+ * then decided one way or the other, the operation says which pieces it wants,
+ * and what is kept is stitched back into loops by joining ends that meet.
+ *
+ * The difference takes the second path's kept pieces the other way round, which
+ * is what turns a disc taken out of the middle of another disc into a ring: the
+ * inner loop is wound against the outer one and the nonzero rule the mark
+ * carries leaves it empty.
+ */
+import { vec2 } from '../values/vec2.js';
+import { pointOn } from './path.js';
+import { cutPath } from './cut.js';
+import { curveCrossings } from './intersect.js';
+import { flattenPath, windingAt } from './inside.js';
+const TOLERANCE = 1e-6;
+/** A subpath left open closed by the straight run back to where it started,
+ * since a path with an open loop has no inside for any of this to ask about. */
+function closedLoops(path) {
+    return path.map((subpath) => {
+        if (subpath.curves.length === 0)
+            return subpath;
+        const end = subpath.curves[subpath.curves.length - 1].to;
+        if (subpath.closed && end.x === subpath.start.x && end.y === subpath.start.y) {
+            return subpath;
+        }
+        const curves = end.x === subpath.start.x && end.y === subpath.start.y
+            ? subpath.curves
+            : [
+                ...subpath.curves,
+                {
+                    control1: vec2.lerp(end, subpath.start, 1 / 3),
+                    control2: vec2.lerp(end, subpath.start, 2 / 3),
+                    to: subpath.start,
+                },
+            ];
+        return { start: subpath.start, curves, closed: true };
+    });
+}
+function piecesOf(path) {
+    const pieces = [];
+    for (const subpath of path) {
+        let from = subpath.start;
+        for (const curve of subpath.curves) {
+            pieces.push({ from, curve });
+            from = curve.to;
+        }
+    }
+    return pieces;
+}
+/** A piece walked the other way, which is what puts a hole the opposite way
+ * round from the loop it sits in. */
+function reversed(piece) {
+    return {
+        from: piece.curve.to,
+        curve: { control1: piece.curve.control2, control2: piece.curve.control1, to: piece.from },
+    };
+}
+/** Where the two paths cross, as the cuts each of them needs. */
+function cutsBetween(first, second, tolerance) {
+    const forFirst = [];
+    const forSecond = [];
+    for (let left = 0; left < first.length; left++) {
+        let leftFrom = first[left].start;
+        for (let leftPiece = 0; leftPiece < first[left].curves.length; leftPiece++) {
+            const leftCurve = first[left].curves[leftPiece];
+            for (let right = 0; right < second.length; right++) {
+                let rightFrom = second[right].start;
+                for (let rightPiece = 0; rightPiece < second[right].curves.length; rightPiece++) {
+                    const rightCurve = second[right].curves[rightPiece];
+                    for (const crossing of curveCrossings(leftFrom, leftCurve, rightFrom, rightCurve, { tolerance })) {
+                        forFirst.push({ subpath: left, curve: leftPiece, along: crossing.alongFirst });
+                        forSecond.push({ subpath: right, curve: rightPiece, along: crossing.alongSecond });
+                    }
+                    rightFrom = rightCurve.to;
+                }
+            }
+            leftFrom = leftCurve.to;
+        }
+    }
+    return [forFirst, forSecond];
+}
+/**
+ * The kept pieces joined into loops, by taking each end to the piece that
+ * starts where it finishes.
+ *
+ * A piece carries its two controls and where it ends, so the loop takes where
+ * each piece begins from where the piece before it ended. The two paths put
+ * their cut at a place they each worked out on their own, so the two ends of a
+ * join differ by whatever the crossing was out by, and that difference is
+ * absorbed here rather than left as a gap.
+ */
+function stitch(pieces, tolerance) {
+    const used = pieces.map(() => false);
+    const loops = [];
+    for (let seed = 0; seed < pieces.length; seed++) {
+        if (used[seed])
+            continue;
+        used[seed] = true;
+        const start = pieces[seed].from;
+        const curves = [pieces[seed].curve];
+        let end = pieces[seed].curve.to;
+        while (vec2.distance(end, start) > tolerance) {
+            let next = -1;
+            let nearest = tolerance;
+            for (let at = 0; at < pieces.length; at++) {
+                if (used[at])
+                    continue;
+                const gap = vec2.distance(pieces[at].from, end);
+                if (gap <= nearest) {
+                    nearest = gap;
+                    next = at;
+                }
+            }
+            if (next < 0)
+                break;
+            used[next] = true;
+            curves.push(pieces[next].curve);
+            end = pieces[next].curve.to;
+        }
+        loops.push({ start, curves, closed: true });
+    }
+    return loops;
+}
+/** Which side of the other path each piece falls on, taken at its middle, which
+ * after the cutting stands for the whole piece. */
+function insideOther(pieces, other) {
+    return pieces.map((piece) => windingAt(other, pointOn(piece.from, piece.curve, 0.5)) !== 0);
+}
+function combine(first, second, keep, options) {
+    const tolerance = options.tolerance ?? TOLERANCE;
+    const left = closedLoops(first);
+    const right = closedLoops(second);
+    if (left.length === 0)
+        return keep === 'union' ? right : [];
+    if (right.length === 0)
+        return keep === 'intersection' ? [] : left;
+    const [leftCuts, rightCuts] = cutsBetween(left, right, tolerance);
+    const leftPieces = piecesOf(cutPath(left, leftCuts, { tolerance }));
+    const rightPieces = piecesOf(cutPath(right, rightCuts, { tolerance }));
+    const leftInside = insideOther(leftPieces, flattenPath(right, { tolerance }));
+    const rightInside = insideOther(rightPieces, flattenPath(left, { tolerance }));
+    const kept = [];
+    for (let at = 0; at < leftPieces.length; at++) {
+        if (leftInside[at] === (keep === 'intersection'))
+            kept.push(leftPieces[at]);
+    }
+    for (let at = 0; at < rightPieces.length; at++) {
+        if (keep === 'difference') {
+            if (rightInside[at])
+                kept.push(reversed(rightPieces[at]));
+            continue;
+        }
+        if (rightInside[at] === (keep === 'intersection'))
+            kept.push(rightPieces[at]);
+    }
+    return stitch(kept, tolerance);
+}
+/** Everything either path covers. */
+export function unionOf(first, second, options = {}) {
+    return combine(first, second, 'union', options);
+}
+/** Only what both paths cover. */
+export function intersectionOf(first, second, options = {}) {
+    return combine(first, second, 'intersection', options);
+}
+/** The first path with the second taken out of it. */
+export function differenceOf(first, second, options = {}) {
+    return combine(first, second, 'difference', options);
+}

package/dist/figure/cut.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A path cut where something crosses it.
+ *
+ * Each cut names a piece and how far along it the cut falls, and the pieces
+ * that come back draw exactly what the pieces they replace drew, because de
+ * Casteljau's construction gives both halves of a cubic as cubics. Several cuts
+ * in one piece are taken in order, and each one after the first is measured
+ * against what is left rather than against the piece it started as.
+ */
+import { type Path } from './path.js';
+/** Where one cut falls: which subpath, which piece of it, and how far along
+ * that piece. */
+export interface Cut {
+    readonly subpath: number;
+    readonly curve: number;
+    readonly along: number;
+}
+export interface CutOptions {
+    /** How close two cuts, or a cut and the end of a piece, are before they count
+     * as the same place, in the picture's own units. */
+    readonly tolerance?: number;
+}
+/**
+ * A path with every cut put in, drawing what it drew and holding one more piece
+ * for each cut.
+ *
+ * The tolerance is a distance rather than a fraction, so it is read against
+ * each piece's own length: a cut is worth making only where the piece it would
+ * leave behind is long enough to see, and a piece of nothing is one the stitch
+ * that follows would have to know to skip.
+ *
+ * A cut naming a piece the path does not have is ignored, since a caller that
+ * has already thrown one subpath away should not have to renumber the cuts it
+ * gathered before it did.
+ */
+export declare function cutPath(path: Path, cuts: readonly Cut[], options?: CutOptions): Path;

package/dist/figure/cut.js

@@ -0,0 +1,83 @@
+/**
+ * A path cut where something crosses it.
+ *
+ * Each cut names a piece and how far along it the cut falls, and the pieces
+ * that come back draw exactly what the pieces they replace drew, because de
+ * Casteljau's construction gives both halves of a cubic as cubics. Several cuts
+ * in one piece are taken in order, and each one after the first is measured
+ * against what is left rather than against the piece it started as.
+ */
+import { splitCurve } from './path.js';
+import { measurePath } from './length.js';
+const TOLERANCE = 1e-9;
+/** The fractions for one piece, in order, with the ones that would leave a
+ * piece of nothing dropped. */
+function wanted(fractions, tolerance) {
+    const kept = [];
+    for (const fraction of [...fractions].sort((a, b) => a - b)) {
+        if (fraction <= tolerance || fraction >= 1 - tolerance)
+            continue;
+        if (kept.length > 0 && fraction - kept[kept.length - 1] <= tolerance)
+            continue;
+        kept.push(fraction);
+    }
+    return kept;
+}
+/** One piece as the run of pieces the cuts leave, each cut measured against
+ * what is left of the piece rather than against the whole of it. */
+function cutCurve(from, curve, fractions) {
+    const pieces = [];
+    let rest = curve;
+    let restFrom = from;
+    let taken = 0;
+    for (const fraction of fractions) {
+        const [head, tail] = splitCurve(restFrom, rest, (fraction - taken) / (1 - taken));
+        pieces.push(head);
+        restFrom = head.to;
+        rest = tail;
+        taken = fraction;
+    }
+    pieces.push(rest);
+    return pieces;
+}
+/**
+ * A path with every cut put in, drawing what it drew and holding one more piece
+ * for each cut.
+ *
+ * The tolerance is a distance rather than a fraction, so it is read against
+ * each piece's own length: a cut is worth making only where the piece it would
+ * leave behind is long enough to see, and a piece of nothing is one the stitch
+ * that follows would have to know to skip.
+ *
+ * A cut naming a piece the path does not have is ignored, since a caller that
+ * has already thrown one subpath away should not have to renumber the cuts it
+ * gathered before it did.
+ */
+export function cutPath(path, cuts, options = {}) {
+    const tolerance = options.tolerance ?? TOLERANCE;
+    if (cuts.length === 0)
+        return path;
+    const gathered = new Map();
+    for (const cut of cuts) {
+        const key = `${cut.subpath}:${cut.curve}`;
+        const already = gathered.get(key);
+        if (already)
+            already.push(cut.along);
+        else
+            gathered.set(key, [cut.along]);
+    }
+    const measured = measurePath(path);
+    return path.map((subpath, at) => {
+        let from = subpath.start;
+        const curves = [];
+        for (let piece = 0; piece < subpath.curves.length; piece++) {
+            const curve = subpath.curves[piece];
+            const span = measured.per[at][piece].total;
+            const asFraction = span > 0 ? Math.min(tolerance / span, 0.5) : 1;
+            const fractions = wanted(gathered.get(`${at}:${piece}`) ?? [], asFraction);
+            curves.push(...cutCurve(from, curve, fractions));
+            from = curve.to;
+        }
+        return { start: subpath.start, curves, closed: subpath.closed };
+    });
+}

package/dist/figure/inside.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Whether a point is inside a path.
+ *
+ * The count is taken on a flattening rather than on the cubics, because a ray
+ * against a cubic is a cubic to solve and what is wanted here is a yes or a no
+ * rather than a place. The geometry a boolean operation keeps stays the exact
+ * cubics; only this decision is taken on the flattening.
+ *
+ * The rule is the nonzero winding rule, which is the rule a mark is already
+ * drawn under, so a loop wound the other way inside another loop is a hole.
+ * Every edge crossing the ray is counted with the sign of the direction it
+ * crosses in, and an edge is counted at its lower end and not at its upper one,
+ * which is what makes a ray leaving through a corner answer what every other
+ * ray answers.
+ */
+import { type Vec2 } from '../values/vec2.js';
+import type { Path } from './path.js';
+export interface FlattenOptions {
+    /** How far a straight run may sit from the curve it stands for, in the
+     * picture's own units. */
+    readonly tolerance?: number;
+}
+/**
+ * Every subpath as a run of points, each loop closed.
+ *
+ * A subpath that was left open is closed by the straight run back to where it
+ * started, since a path with an open loop has no inside until it has one.
+ */
+export declare function flattenPath(path: Path, options?: FlattenOptions): Vec2[][];
+/** How many times the loops wind round a point, counted along the ray heading
+ * in the positive x direction. */
+export declare function windingAt(loops: readonly (readonly Vec2[])[], point: Vec2): number;
+/**
+ * Whether a path holds a point, under the nonzero rule.
+ *
+ * A point sitting on the edge itself has no answer this can be right about, and
+ * what comes back for one is whichever side the tolerance put it on.
+ */
+export declare function containsPoint(path: Path, point: Vec2, options?: FlattenOptions): boolean;

package/dist/figure/inside.js

@@ -0,0 +1,106 @@
+/**
+ * Whether a point is inside a path.
+ *
+ * The count is taken on a flattening rather than on the cubics, because a ray
+ * against a cubic is a cubic to solve and what is wanted here is a yes or a no
+ * rather than a place. The geometry a boolean operation keeps stays the exact
+ * cubics; only this decision is taken on the flattening.
+ *
+ * The rule is the nonzero winding rule, which is the rule a mark is already
+ * drawn under, so a loop wound the other way inside another loop is a hole.
+ * Every edge crossing the ray is counted with the sign of the direction it
+ * crosses in, and an edge is counted at its lower end and not at its upper one,
+ * which is what makes a ray leaving through a corner answer what every other
+ * ray answers.
+ */
+import { vec2 } from '../values/vec2.js';
+const TOLERANCE = 1e-6;
+/** How many times a piece may be halved, which a tolerance of zero would
+ * otherwise leave unbounded. */
+const DEPTH = 24;
+/** How far the two controls sit from the straight run between the ends.
+ *
+ * The curve itself stays within three quarters of this, so measuring the
+ * controls asks for a little more than the tolerance rather than a little
+ * less. */
+function offChord(from, curve) {
+    const run = vec2.sub(curve.to, from);
+    const span = Math.hypot(run.x, run.y);
+    if (span === 0) {
+        return Math.max(vec2.distance(curve.control1, from), vec2.distance(curve.control2, from));
+    }
+    const away = (point) => Math.abs(run.x * (point.y - from.y) - run.y * (point.x - from.x)) / span;
+    return Math.max(away(curve.control1), away(curve.control2));
+}
+function walk(from, curve, tolerance, depth, into) {
+    if (depth >= DEPTH || offChord(from, curve) <= tolerance) {
+        into.push(curve.to);
+        return;
+    }
+    const a = vec2.lerp(from, curve.control1, 0.5);
+    const b = vec2.lerp(curve.control1, curve.control2, 0.5);
+    const c = vec2.lerp(curve.control2, curve.to, 0.5);
+    const d = vec2.lerp(a, b, 0.5);
+    const e = vec2.lerp(b, c, 0.5);
+    const middle = vec2.lerp(d, e, 0.5);
+    walk(from, { control1: a, control2: d, to: middle }, tolerance, depth + 1, into);
+    walk(middle, { control1: e, control2: c, to: curve.to }, tolerance, depth + 1, into);
+}
+/**
+ * Every subpath as a run of points, each loop closed.
+ *
+ * A subpath that was left open is closed by the straight run back to where it
+ * started, since a path with an open loop has no inside until it has one.
+ */
+export function flattenPath(path, options = {}) {
+    const tolerance = options.tolerance ?? TOLERANCE;
+    const loops = [];
+    for (const subpath of path) {
+        if (subpath.curves.length === 0)
+            continue;
+        const points = [subpath.start];
+        let from = subpath.start;
+        for (const curve of subpath.curves) {
+            walk(from, curve, tolerance, 0, points);
+            from = curve.to;
+        }
+        const last = points[points.length - 1];
+        if (last.x !== points[0].x || last.y !== points[0].y)
+            points.push(points[0]);
+        loops.push(points);
+    }
+    return loops;
+}
+/** Which side of the run from one point to another a third point falls on,
+ * positive to the left of it. */
+function leftOf(from, to, point) {
+    return (to.x - from.x) * (point.y - from.y) - (point.x - from.x) * (to.y - from.y);
+}
+/** How many times the loops wind round a point, counted along the ray heading
+ * in the positive x direction. */
+export function windingAt(loops, point) {
+    let winding = 0;
+    for (const loop of loops) {
+        for (let at = 1; at < loop.length; at++) {
+            const from = loop[at - 1];
+            const to = loop[at];
+            if (from.y <= point.y) {
+                if (to.y > point.y && leftOf(from, to, point) > 0)
+                    winding += 1;
+            }
+            else if (to.y <= point.y && leftOf(from, to, point) < 0) {
+                winding -= 1;
+            }
+        }
+    }
+    return winding;
+}
+/**
+ * Whether a path holds a point, under the nonzero rule.
+ *
+ * A point sitting on the edge itself has no answer this can be right about, and
+ * what comes back for one is whichever side the tolerance put it on.
+ */
+export function containsPoint(path, point, options = {}) {
+    return windingAt(flattenPath(path, options), point) !== 0;
+}

package/dist/figure/intersect.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where two cubics cross.
+ *
+ * Two curves whose boxes miss each other cannot cross, so a pair is halved by
+ * de Casteljau's construction and only the halves whose boxes still overlap are
+ * followed down, until both are smaller than the tolerance. A box is bigger
+ * than the curve inside it, so a pair that small is kept only when the straight
+ * runs across the two pieces come within the tolerance of each other. What is
+ * left is a run of touching hits per meeting rather than one hit, so the run is
+ * joined up and answered once, and then sharpened by Newton's method on the
+ * pair, which is what takes a crossing of two straight pieces from the
+ * tolerance to the last few bits.
+ */
+import { type Vec2 } from '../values/vec2.js';
+import type { Cubic } from './path.js';
+/** One place two curves meet, as a fraction along each of them and the point
+ * itself. */
+export interface Crossing {
+    readonly alongFirst: number;
+    readonly alongSecond: number;
+    readonly point: Vec2;
+}
+export interface CrossingOptions {
+    /** How close two pieces come before they count as meeting, in the picture's
+     * own units. */
+    readonly tolerance?: number;
+}
+/**
+ * Every place two cubics cross, as a fraction along each and the point.
+ *
+ * Each segment is given the point it starts from, since a segment carries where
+ * it ends and not where it began. Two curves that lie on top of each other for
+ * a stretch have no one answer, and what comes back for them is decided by the
+ * tolerance rather than by the geometry.
+ */
+export declare function curveCrossings(fromFirst: Vec2, first: Cubic, fromSecond: Vec2, second: Cubic, options?: CrossingOptions): Crossing[];

package/dist/figure/intersect.js

@@ -0,0 +1,309 @@
+/**
+ * Where two cubics cross.
+ *
+ * Two curves whose boxes miss each other cannot cross, so a pair is halved by
+ * de Casteljau's construction and only the halves whose boxes still overlap are
+ * followed down, until both are smaller than the tolerance. A box is bigger
+ * than the curve inside it, so a pair that small is kept only when the straight
+ * runs across the two pieces come within the tolerance of each other. What is
+ * left is a run of touching hits per meeting rather than one hit, so the run is
+ * joined up and answered once, and then sharpened by Newton's method on the
+ * pair, which is what takes a crossing of two straight pieces from the
+ * tolerance to the last few bits.
+ */
+import { vec2 } from '../values/vec2.js';
+/** How close two pieces come before they count as meeting. It decides which
+ * meetings are told apart rather than how sharp one is, since Newton's method
+ * supplies the sharpness afterwards. */
+const TOLERANCE = 1e-6;
+/** How many pairs the search may open before it answers with where it had got
+ * to, which is what stops two curves lying on top of each other for a stretch
+ * from halving forever. */
+const BUDGET = 500_000;
+/** How deep the halving goes, which a tolerance of zero would otherwise leave
+ * unbounded. */
+const DEPTH = 60;
+/** Below this the two tangents are parallel, Newton's step divides by nothing,
+ * and the answer stays the one the halving gave. */
+const PARALLEL = 1e-12;
+/** How far Newton is allowed to move a cluster before its step is read as a
+ * jump to a different crossing and thrown away. */
+const REACH = 1e-3;
+/** A segment written as its four points, since a segment carries where it ends
+ * and not where it began. */
+function hullOf(from, curve) {
+    return [from, curve.control1, curve.control2, curve.to];
+}
+/** The box round the four points, which holds the curve because a cubic never
+ * leaves the hull of the points it is written from. */
+function boxOf(hull) {
+    let lowX = hull[0].x;
+    let highX = hull[0].x;
+    let lowY = hull[0].y;
+    let highY = hull[0].y;
+    for (let at = 1; at < 4; at++) {
+        const point = hull[at];
+        if (point.x < lowX)
+            lowX = point.x;
+        if (point.x > highX)
+            highX = point.x;
+        if (point.y < lowY)
+            lowY = point.y;
+        if (point.y > highY)
+            highY = point.y;
+    }
+    return { lowX, highX, lowY, highY };
+}
+function spread(box) {
+    return Math.max(box.highX - box.lowX, box.highY - box.lowY);
+}
+/** Whether two boxes miss, with the tolerance added on both sides so two curves
+ * touching at exactly one point are not lost to rounding. */
+function apart(a, b, slack) {
+    return (a.lowX - slack > b.highX ||
+        b.lowX - slack > a.highX ||
+        a.lowY - slack > b.highY ||
+        b.lowY - slack > a.highY);
+}
+/** How far a point sits from a straight run between two points. */
+function offSegment(point, from, to) {
+    const run = vec2.sub(to, from);
+    const square = vec2.dot(run, run);
+    const along = square === 0 ? 0 : held(vec2.dot(vec2.sub(point, from), run) / square);
+    return vec2.distance(point, vec2.add(from, vec2.scale(run, along)));
+}
+/**
+ * How far apart two pieces are, taken between the straight runs across them.
+ *
+ * A piece no bigger than the tolerance leaves its own chord by a fraction of
+ * that, so the chords answer for the curves here, and this is what tells a
+ * meeting from two boxes that merely overlap without their curves coming close.
+ */
+function chordGap(first, second) {
+    const a = first[0];
+    const b = first[3];
+    const c = second[0];
+    const d = second[3];
+    const ab = vec2.sub(b, a);
+    const cd = vec2.sub(d, c);
+    const under = ab.x * cd.y - ab.y * cd.x;
+    if (under !== 0) {
+        const ac = vec2.sub(c, a);
+        const alongFirst = (ac.x * cd.y - ac.y * cd.x) / under;
+        const alongSecond = (ac.x * ab.y - ac.y * ab.x) / under;
+        if (alongFirst >= 0 && alongFirst <= 1 && alongSecond >= 0 && alongSecond <= 1)
+            return 0;
+    }
+    return Math.min(offSegment(a, c, d), offSegment(b, c, d), offSegment(c, a, b), offSegment(d, a, b));
+}
+/** A segment cut in half, both pieces drawing what the whole drew. */
+function halves(hull) {
+    const a = vec2.lerp(hull[0], hull[1], 0.5);
+    const b = vec2.lerp(hull[1], hull[2], 0.5);
+    const c = vec2.lerp(hull[2], hull[3], 0.5);
+    const d = vec2.lerp(a, b, 0.5);
+    const e = vec2.lerp(b, c, 0.5);
+    const middle = vec2.lerp(d, e, 0.5);
+    return [
+        [hull[0], a, d, middle],
+        [middle, e, c, hull[3]],
+    ];
+}
+function pointAt(hull, 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 * hull[0].x + b * hull[1].x + c * hull[2].x + d * hull[3].x, a * hull[0].y + b * hull[1].y + c * hull[2].y + d * hull[3].y);
+}
+/** Which way the curve is heading, which is the derivative of a cubic and so a
+ * quadratic over the differences between neighbouring points. */
+function slopeAt(hull, along) {
+    const u = 1 - along;
+    const a = 3 * u * u;
+    const b = 6 * u * along;
+    const c = 3 * along * along;
+    return vec2(a * (hull[1].x - hull[0].x) + b * (hull[2].x - hull[1].x) + c * (hull[3].x - hull[2].x), a * (hull[1].y - hull[0].y) + b * (hull[2].y - hull[1].y) + c * (hull[3].y - hull[2].y));
+}
+/** A fraction pulled back onto the segment, so a crossing at an end lands on
+ * the end exactly rather than a hair outside it. */
+function held(along) {
+    return along < 0 ? 0 : along > 1 ? 1 : along;
+}
+function gapBetween(first, second, alongFirst, alongSecond) {
+    return vec2.distance(pointAt(first, alongFirst), pointAt(second, alongSecond));
+}
+/**
+ * One cluster moved onto the crossing itself, by Newton's method on the pair of
+ * curves: the step that takes the difference between the two points to zero is
+ * the two tangents solved as a two by two system.
+ *
+ * A tangency has no such step, since the tangents are parallel there and the
+ * system has no answer, so the halving's own reading is what stands.
+ */
+function sharpened(first, second, start) {
+    let alongFirst = start.alongFirst;
+    let alongSecond = start.alongSecond;
+    let gap = gapBetween(first, second, alongFirst, alongSecond);
+    for (let step = 0; step < 12; step++) {
+        const apartBy = vec2.sub(pointAt(first, alongFirst), pointAt(second, alongSecond));
+        const heading = slopeAt(first, alongFirst);
+        const other = slopeAt(second, alongSecond);
+        const under = other.x * heading.y - heading.x * other.y;
+        if (Math.abs(under) < PARALLEL)
+            break;
+        const moveFirst = (apartBy.x * other.y - other.x * apartBy.y) / under;
+        const moveSecond = (apartBy.x * heading.y - heading.x * apartBy.y) / under;
+        if (Math.abs(moveFirst) > REACH || Math.abs(moveSecond) > REACH)
+            break;
+        const nextFirst = held(alongFirst + moveFirst);
+        const nextSecond = held(alongSecond + moveSecond);
+        const nextGap = gapBetween(first, second, nextFirst, nextSecond);
+        if (nextGap > gap)
+            break;
+        alongFirst = nextFirst;
+        alongSecond = nextSecond;
+        gap = nextGap;
+        if (gap === 0)
+            break;
+    }
+    return { alongFirst, alongSecond, point: pointAt(first, alongFirst) };
+}
+/**
+ * A run of hits reported as the places they gather at.
+ *
+ * Every hit carries the stretch of each curve it was found in, and two hits
+ * whose stretches touch on both curves are the same meeting: the stretch
+ * between them was never thrown away, so the curves stayed within the tolerance
+ * across it. A gap in the run is the curves moving apart by more than the
+ * tolerance, which is two meetings rather than one.
+ */
+function clustered(hits) {
+    const inOrder = [...hits].sort((a, b) => a.firstLow - b.firstLow);
+    const groups = [];
+    for (const hit of inOrder) {
+        const joined = groups.find((group) => hit.firstLow <= group.firstHigh &&
+            hit.firstHigh >= group.firstLow &&
+            hit.secondLow <= group.secondHigh &&
+            hit.secondHigh >= group.secondLow);
+        if (joined) {
+            joined.firstHigh = Math.max(joined.firstHigh, hit.firstHigh);
+            joined.firstLow = Math.min(joined.firstLow, hit.firstLow);
+            joined.secondHigh = Math.max(joined.secondHigh, hit.secondHigh);
+            joined.secondLow = Math.min(joined.secondLow, hit.secondLow);
+            joined.sumFirst += (hit.firstLow + hit.firstHigh) / 2;
+            joined.sumSecond += (hit.secondLow + hit.secondHigh) / 2;
+            joined.sum = vec2.add(joined.sum, hit.point);
+            joined.count += 1;
+            continue;
+        }
+        groups.push({
+            firstLow: hit.firstLow,
+            firstHigh: hit.firstHigh,
+            secondLow: hit.secondLow,
+            secondHigh: hit.secondHigh,
+            sumFirst: (hit.firstLow + hit.firstHigh) / 2,
+            sumSecond: (hit.secondLow + hit.secondHigh) / 2,
+            sum: hit.point,
+            count: 1,
+        });
+    }
+    return groups.map((group) => ({
+        alongFirst: group.sumFirst / group.count,
+        alongSecond: group.sumSecond / group.count,
+        point: vec2.scale(group.sum, 1 / group.count),
+    }));
+}
+/**
+ * Every place two cubics cross, as a fraction along each and the point.
+ *
+ * Each segment is given the point it starts from, since a segment carries where
+ * it ends and not where it began. Two curves that lie on top of each other for
+ * a stretch have no one answer, and what comes back for them is decided by the
+ * tolerance rather than by the geometry.
+ */
+export function curveCrossings(fromFirst, first, fromSecond, second, options = {}) {
+    const tolerance = options.tolerance ?? TOLERANCE;
+    const firstHull = hullOf(fromFirst, first);
+    const secondHull = hullOf(fromSecond, second);
+    const stack = [
+        {
+            first: firstHull,
+            firstLow: 0,
+            firstHigh: 1,
+            second: secondHull,
+            secondLow: 0,
+            secondHigh: 1,
+            depth: 0,
+        },
+    ];
+    const hits = [];
+    let opened = 0;
+    const record = (pair) => {
+        const alongFirst = (pair.firstLow + pair.firstHigh) / 2;
+        const alongSecond = (pair.secondLow + pair.secondHigh) / 2;
+        hits.push({
+            alongFirst,
+            alongSecond,
+            point: pointAt(firstHull, alongFirst),
+            firstLow: pair.firstLow,
+            firstHigh: pair.firstHigh,
+            secondLow: pair.secondLow,
+            secondHigh: pair.secondHigh,
+        });
+    };
+    while (stack.length > 0) {
+        const pair = stack.pop();
+        opened += 1;
+        const firstBox = boxOf(pair.first);
+        const secondBox = boxOf(pair.second);
+        if (apart(firstBox, secondBox, tolerance))
+            continue;
+        if (opened >= BUDGET) {
+            record(pair);
+            break;
+        }
+        const cutFirst = spread(firstBox) > tolerance;
+        const cutSecond = spread(secondBox) > tolerance;
+        if (!cutFirst && !cutSecond) {
+            if (chordGap(pair.first, pair.second) <= tolerance)
+                record(pair);
+            continue;
+        }
+        if (pair.depth >= DEPTH) {
+            record(pair);
+            continue;
+        }
+        const firstMid = (pair.firstLow + pair.firstHigh) / 2;
+        const secondMid = (pair.secondLow + pair.secondHigh) / 2;
+        const firstParts = cutFirst
+            ? halves(pair.first).map((hull, side) => ({
+                hull,
+                low: side === 0 ? pair.firstLow : firstMid,
+                high: side === 0 ? firstMid : pair.firstHigh,
+            }))
+            : [{ hull: pair.first, low: pair.firstLow, high: pair.firstHigh }];
+        const secondParts = cutSecond
+            ? halves(pair.second).map((hull, side) => ({
+                hull,
+                low: side === 0 ? pair.secondLow : secondMid,
+                high: side === 0 ? secondMid : pair.secondHigh,
+            }))
+            : [{ hull: pair.second, low: pair.secondLow, high: pair.secondHigh }];
+        for (const left of firstParts) {
+            for (const right of secondParts) {
+                stack.push({
+                    first: left.hull,
+                    firstLow: left.low,
+                    firstHigh: left.high,
+                    second: right.hull,
+                    secondLow: right.low,
+                    secondHigh: right.high,
+                    depth: pair.depth + 1,
+                });
+            }
+        }
+    }
+    return clustered(hits).map((crossing) => sharpened(firstHull, secondHull, crossing));
+}

package/dist/figure/morph.js

@@ -7,21 +7,7 @@
  * 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 },
-    ];
-}
+import { pointOn, splitCurve } from './path.js';
 /**
  * A subpath rewritten to hold exactly this many segments, drawing the same shape.
  *
@@ -49,7 +35,7 @@ function withCurves(subpath, wanted) {
         let start = subpath.start;
         for (let at = 0; at < cutAt; at++)
             start = curves[at].to;
-        const [first, second] = halves(start, curves[cutAt], 0.5);
+        const [first, second] = splitCurve(start, curves[cutAt], 0.5);
         curves = [...curves.slice(0, cutAt), first, second, ...curves.slice(cutAt + 1)];
     }
     return { start: subpath.start, curves, closed: subpath.closed };

package/dist/figure/path.d.ts

@@ -48,6 +48,14 @@ export declare function arc(centre: Vec2, radius: number, fromAngle: number, toA
 /** 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;
+/**
+ * One piece cut into two at a fraction, both pieces drawing what the whole
+ * drew, by de Casteljau's construction.
+ *
+ * The piece's own start is passed in because a piece carries where it ends and
+ * not where it began.
+ */
+export declare function splitCurve(from: Vec2, curve: Cubic, along: number): [Cubic, Cubic];
 /** 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;

package/dist/figure/path.js

@@ -121,6 +121,25 @@ export function pointOn(from, curve, 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);
 }
+/**
+ * One piece cut into two at a fraction, both pieces drawing what the whole
+ * drew, by de Casteljau's construction.
+ *
+ * The piece's own start is passed in because a piece carries where it ends and
+ * not where it began.
+ */
+export function splitCurve(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 },
+    ];
+}
 /** 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) {

package/dist/index.d.ts

@@ -20,9 +20,18 @@ export { mat3 } from './values/mat3.js';
 export type { Mat3 } from './values/mat3.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, straight, transformPath } from './figure/path.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, splitCurve, straight, transformPath } from './figure/path.js';
 export type { Cubic, Path, Subpath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
+export { areaOf } from './figure/area.js';
+export { differenceOf, intersectionOf, unionOf } from './figure/boolean.js';
+export type { BooleanOptions } from './figure/boolean.js';
+export { containsPoint, flattenPath, windingAt } from './figure/inside.js';
+export type { FlattenOptions } from './figure/inside.js';
+export { cutPath } from './figure/cut.js';
+export type { Cut, CutOptions } from './figure/cut.js';
+export { curveCrossings } from './figure/intersect.js';
+export type { Crossing, CrossingOptions } from './figure/intersect.js';
 export type { Colour, Fill, Mark, PathMark, Stroke, TextMark } from './figure/mark.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export type { Extent, ExtentChoice, Fit } from './figure/extent.js';

package/dist/index.js

@@ -14,8 +14,13 @@ export { vec3 } from './values/vec3.js';
 export { interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
-export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, splitCurve, straight, transformPath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
+export { areaOf } from './figure/area.js';
+export { differenceOf, intersectionOf, unionOf } from './figure/boolean.js';
+export { containsPoint, flattenPath, windingAt } from './figure/inside.js';
+export { cutPath } from './figure/cut.js';
+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';

package/package.json

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