@altpsyche/maths 0.9.0 → 0.9.1

package/dist/figure/boolean.js

@@ -10,12 +10,20 @@
  * 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.
+ *
+ * A piece lying along the other path's own edge is decided by which way the two
+ * run rather than by which side it is on, because a point on an edge is the one
+ * place the winding count has no answer for. Two paths walking a shared stretch
+ * the same way have their solid on the same side of it, so the stretch is on the
+ * edge of a union and of an overlap and is kept once. Walking it opposite ways
+ * puts their solids on opposite sides, so the stretch is inside a union and
+ * outside an overlap, and a difference keeps the first path's copy of it.
  */
 import { vec2 } from '../values/vec2.js';
-import { pointOn } from './path.js';
+import { pointOn, slopeOn } from './path.js';
 import { cutPath } from './cut.js';
 import { curveCrossings } from './intersect.js';
-import { flattenPath, windingAt } from './inside.js';
+import { flattenPath, nearestEdge, 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. */
@@ -83,6 +91,22 @@ function cutsBetween(first, second, tolerance) {
     }
     return [forFirst, forSecond];
 }
+function place(point) {
+    return `(${point.x.toFixed(6)}, ${point.y.toFixed(6)})`;
+}
+/**
+ * What a run of pieces that will not close stops with.
+ *
+ * Handing it back as a loop anyway is the one failure a caller cannot see: the
+ * shape drawn is wrong and nothing about it says so. Every input is closed
+ * loops, so a run that will not close is this code being wrong rather than the
+ * caller, and stopping is what makes that visible on the frame it happens.
+ */
+function refuse(pieces, start, end, tolerance) {
+    throw new Error(`the pieces kept do not close into a loop: ${pieces} of them run from ${place(start)} ` +
+        `to ${place(end)}, which is ${vec2.distance(end, start).toFixed(6)} apart against a ` +
+        `tolerance of ${tolerance}`);
+}
 /**
  * The kept pieces joined into loops, by taking each end to the piece that
  * starts where it finishes.
@@ -116,7 +140,7 @@ function stitch(pieces, tolerance) {
                 }
             }
             if (next < 0)
-                break;
+                refuse(curves.length, start, end, tolerance);
             used[next] = true;
             curves.push(pieces[next].curve);
             end = pieces[next].curve.to;
@@ -125,10 +149,40 @@ function stitch(pieces, tolerance) {
     }
     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);
+/**
+ * Where each piece stands against the other path, read at its middle.
+ *
+ * The middle stands for the whole piece because the cutting has already put a
+ * break wherever the two paths meet, so a piece after it is wholly one thing.
+ */
+function sidesAgainst(pieces, other, tolerance) {
+    return pieces.map((piece) => {
+        const middle = pointOn(piece.from, piece.curve, 0.5);
+        const edge = nearestEdge(other, middle);
+        if (edge && edge.gap <= tolerance) {
+            return vec2.dot(slopeOn(piece.from, piece.curve, 0.5), edge.heading) >= 0 ? 'along' : 'against';
+        }
+        return windingAt(other, middle) !== 0 ? 'inside' : 'outside';
+    });
+}
+/** Whether the first path's piece belongs to the answer. */
+function keepsFirst(keep, side) {
+    if (side === 'along')
+        return keep !== 'difference';
+    if (side === 'against')
+        return keep === 'difference';
+    if (keep === 'intersection')
+        return side === 'inside';
+    return side === 'outside';
+}
+/** Whether the second path's piece belongs to the answer. A shared stretch is
+ * never taken from here, since the first path's copy of it is already in. */
+function keepsSecond(keep, side) {
+    if (side === 'along' || side === 'against')
+        return false;
+    if (keep === 'union')
+        return side === 'outside';
+    return side === 'inside';
 }
 function combine(first, second, keep, options) {
     const tolerance = options.tolerance ?? TOLERANCE;
@@ -141,21 +195,17 @@ function combine(first, second, keep, options) {
     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 leftSide = sidesAgainst(leftPieces, flattenPath(right, { tolerance }), tolerance);
+    const rightSide = sidesAgainst(rightPieces, flattenPath(left, { tolerance }), tolerance);
     const kept = [];
     for (let at = 0; at < leftPieces.length; at++) {
-        if (leftInside[at] === (keep === 'intersection'))
+        if (keepsFirst(keep, leftSide[at]))
             kept.push(leftPieces[at]);
     }
     for (let at = 0; at < rightPieces.length; at++) {
-        if (keep === 'difference') {
-            if (rightInside[at])
-                kept.push(reversed(rightPieces[at]));
+        if (!keepsSecond(keep, rightSide[at]))
             continue;
-        }
-        if (rightInside[at] === (keep === 'intersection'))
-            kept.push(rightPieces[at]);
+        kept.push(keep === 'difference' ? reversed(rightPieces[at]) : rightPieces[at]);
     }
     return stitch(kept, tolerance);
 }

package/dist/figure/inside.d.ts

@@ -30,6 +30,20 @@ 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;
+/** The nearest straight run of a flattening to a point: how far off it is, and
+ * which way that run goes. */
+export interface Edge {
+    readonly gap: number;
+    readonly heading: Vec2;
+}
+/**
+ * Which edge of a flattening a point sits nearest, and which way it runs.
+ *
+ * This is what tells a piece lying along another path's edge from one merely
+ * near it, which the winding count cannot answer because a point on the edge
+ * itself is the one place the count has no answer for.
+ */
+export declare function nearestEdge(loops: readonly (readonly Vec2[])[], point: Vec2): Edge | null;
 /**
  * Whether a path holds a point, under the nonzero rule.
  *

package/dist/figure/inside.js

@@ -18,6 +18,15 @@ 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 many points a whole flattening may hold before it is refused.
+ *
+ * Halving is the only bound the depth gives, and sixteen million points for one
+ * piece is a machine out of memory rather than a fine flattening. A circle of
+ * radius 1 wants 4096 of these at a tolerance of a millionth, so the room here
+ * is a thousandfold.
+ */
+const POINTS = 1_000_000;
 /** 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
@@ -37,6 +46,10 @@ function walk(from, curve, tolerance, depth, into) {
         into.push(curve.to);
         return;
     }
+    if (into.length >= POINTS) {
+        throw new Error(`a tolerance of ${tolerance} asks for more than ${POINTS} straight runs to stand for one ` +
+            `curve, which is finer than this flattens`);
+    }
     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);
@@ -95,6 +108,29 @@ export function windingAt(loops, point) {
     }
     return winding;
 }
+/**
+ * Which edge of a flattening a point sits nearest, and which way it runs.
+ *
+ * This is what tells a piece lying along another path's edge from one merely
+ * near it, which the winding count cannot answer because a point on the edge
+ * itself is the one place the count has no answer for.
+ */
+export function nearestEdge(loops, point) {
+    let nearest = null;
+    for (const loop of loops) {
+        for (let at = 1; at < loop.length; at++) {
+            const from = loop[at - 1];
+            const to = loop[at];
+            const run = vec2.sub(to, from);
+            const square = vec2.dot(run, run);
+            const along = square === 0 ? 0 : Math.min(1, Math.max(0, vec2.dot(vec2.sub(point, from), run) / square));
+            const gap = vec2.distance(point, vec2.add(from, vec2.scale(run, along)));
+            if (!nearest || gap < nearest.gap)
+                nearest = { gap, heading: run };
+        }
+    }
+    return nearest;
+}
 /**
  * Whether a path holds a point, under the nonzero rule.
  *

package/dist/figure/intersect.d.ts

@@ -29,8 +29,8 @@ export interface CrossingOptions {
  * 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.
+ * it ends and not where it began. Two curves covering the same stretch answer
+ * with the two ends of that stretch, so a caller reading the answer as places to
+ * cut at gets the stretch marked off rather than chopped into slivers.
  */
 export declare function curveCrossings(fromFirst: Vec2, first: Cubic, fromSecond: Vec2, second: Cubic, options?: CrossingOptions): Crossing[];

package/dist/figure/intersect.js

@@ -16,10 +16,15 @@ import { vec2 } from '../values/vec2.js';
  * 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 many pairs the search may make before it answers with where it had got to.
+ *
+ * It counts pairs made rather than pairs looked at, because each one looked at
+ * makes up to four more: counting the ones looked at leaves the pile of pairs
+ * waiting growing four times faster than it drains, and a tolerance small enough
+ * ran the machine out of memory before the count was ever reached.
+ */
+const BUDGET = 200_000;
 /** How deep the halving goes, which a tolerance of zero would otherwise leave
  * unbounded. */
 const DEPTH = 60;
@@ -117,8 +122,8 @@ function pointAt(hull, 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. */
+/** Which way the curve is heading, read off the four points the search already
+ * holds rather than off a piece, so following a pair down allocates nothing. */
 function slopeAt(hull, along) {
     const u = 1 - along;
     const a = 3 * u * u;
@@ -215,18 +220,121 @@ function clustered(hits) {
         point: vec2.scale(group.sum, 1 / group.count),
     }));
 }
+/** How many places the coarse sweep looks at before it decides which part of a
+ * curve a point is nearest. */
+const SWEEP = 32;
+/** How hard the curve is turning at a place, which Newton needs because the
+ * nearest point moves as the curve bends away from it. */
+function bendAt(hull, along) {
+    const u = 1 - along;
+    return vec2(6 * (u * (hull[2].x - 2 * hull[1].x + hull[0].x) + along * (hull[3].x - 2 * hull[2].x + hull[1].x)), 6 * (u * (hull[2].y - 2 * hull[1].y + hull[0].y) + along * (hull[3].y - 2 * hull[2].y + hull[1].y)));
+}
+/**
+ * Where on a curve a point sits nearest, as a fraction along it, and how far
+ * away it is there.
+ *
+ * A coarse sweep picks which part of the curve to believe, and Newton's method
+ * on the distance finishes it, since the nearest point on a cubic is a fifth
+ * degree root and solving one is more than this needs. The sweep gives up before
+ * Newton when its best is further off than the tolerance plus the most one step
+ * of the sweep can be hiding, since no refining brings it under from there.
+ */
+function nearestPlace(hull, point, tolerance) {
+    let along = 0;
+    let gap = Infinity;
+    for (let step = 0; step <= SWEEP; step++) {
+        const at = step / SWEEP;
+        const away = vec2.distance(pointAt(hull, at), point);
+        if (away < gap) {
+            gap = away;
+            along = at;
+        }
+    }
+    const reach = spread(boxOf(hull)) * 2;
+    if (gap > tolerance + reach / SWEEP)
+        return { along, gap };
+    for (let step = 0; step < 12; step++) {
+        const away = vec2.sub(pointAt(hull, along), point);
+        const heading = slopeAt(hull, along);
+        const turning = vec2.dot(heading, heading) + vec2.dot(away, bendAt(hull, along));
+        if (Math.abs(turning) < PARALLEL)
+            break;
+        const next = held(along - vec2.dot(away, heading) / turning);
+        const closer = vec2.distance(pointAt(hull, next), point);
+        if (!(closer < gap))
+            break;
+        along = next;
+        gap = closer;
+    }
+    return { along, gap };
+}
+/** How many places along a shared stretch are checked to still be on the other
+ * curve before the stretch is believed. */
+const ALONG_SHARED = 12;
+/**
+ * The two ends of the stretch two curves cover together, when they cover one.
+ *
+ * Halving into a stretch like that answers it as a spray of meetings, because
+ * every pair of small pieces along it overlaps and the budget runs out before
+ * the run is walked. So the stretch is found first, from the ends of each curve
+ * that lie on the other, and answered by where it starts and where it ends.
+ *
+ * Two curves meeting at a single point are not a stretch and are left to the
+ * halving, which places one meeting more sharply than a sweep can.
+ */
+function sharedStretch(first, second, tolerance) {
+    const ends = [];
+    for (const along of [0, 1]) {
+        const place = nearestPlace(second, pointAt(first, along), tolerance);
+        if (place.gap <= tolerance)
+            ends.push({ first: along, second: place.along });
+    }
+    for (const along of [0, 1]) {
+        const place = nearestPlace(first, pointAt(second, along), tolerance);
+        if (place.gap <= tolerance)
+            ends.push({ first: place.along, second: along });
+    }
+    if (ends.length < 2)
+        return null;
+    let low = ends[0];
+    let high = ends[0];
+    for (const end of ends) {
+        if (end.first < low.first)
+            low = end;
+        if (end.first > high.first)
+            high = end;
+    }
+    const from = pointAt(first, low.first);
+    const to = pointAt(first, high.first);
+    if (vec2.distance(from, to) <= tolerance)
+        return null;
+    for (let step = 1; step < ALONG_SHARED; step++) {
+        const along = low.first + ((high.first - low.first) * step) / ALONG_SHARED;
+        if (nearestPlace(second, pointAt(first, along), tolerance).gap > tolerance)
+            return null;
+    }
+    return [
+        { alongFirst: low.first, alongSecond: low.second, point: from },
+        { alongFirst: high.first, alongSecond: high.second, point: to },
+    ];
+}
 /**
  * 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.
+ * it ends and not where it began. Two curves covering the same stretch answer
+ * with the two ends of that stretch, so a caller reading the answer as places to
+ * cut at gets the stretch marked off rather than chopped into slivers.
  */
 export function curveCrossings(fromFirst, first, fromSecond, second, options = {}) {
     const tolerance = options.tolerance ?? TOLERANCE;
     const firstHull = hullOf(fromFirst, first);
     const secondHull = hullOf(fromSecond, second);
+    if (apart(boxOf(firstHull), boxOf(secondHull), tolerance))
+        return [];
+    const shared = sharedStretch(firstHull, secondHull, tolerance);
+    if (shared)
+        return shared;
     const stack = [
         {
             first: firstHull,
@@ -239,7 +347,7 @@ export function curveCrossings(fromFirst, first, fromSecond, second, options = {
         },
     ];
     const hits = [];
-    let opened = 0;
+    let made = 1;
     const record = (pair) => {
         const alongFirst = (pair.firstLow + pair.firstHigh) / 2;
         const alongSecond = (pair.secondLow + pair.secondHigh) / 2;
@@ -255,12 +363,11 @@ export function curveCrossings(fromFirst, first, fromSecond, second, options = {
     };
     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) {
+        if (made >= BUDGET) {
             record(pair);
             break;
         }
@@ -291,6 +398,7 @@ export function curveCrossings(fromFirst, first, fromSecond, second, options = {
                 high: side === 0 ? secondMid : pair.secondHigh,
             }))
             : [{ hull: pair.second, low: pair.secondLow, high: pair.secondHigh }];
+        made += firstParts.length * secondParts.length;
         for (const left of firstParts) {
             for (const right of secondParts) {
                 stack.push({

package/dist/figure/path.d.ts

@@ -48,6 +48,9 @@ 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;
+/** Which way a piece is heading at a fraction along it, which is the derivative
+ * of a cubic and so a quadratic over the gaps between neighbouring points. */
+export declare function slopeOn(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.

package/dist/figure/path.js

@@ -121,6 +121,15 @@ 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);
 }
+/** Which way a piece is heading at a fraction along it, which is the derivative
+ * of a cubic and so a quadratic over the gaps between neighbouring points. */
+export function slopeOn(from, curve, along) {
+    const u = 1 - along;
+    const a = 3 * u * u;
+    const b = 6 * u * along;
+    const c = 3 * along * along;
+    return vec2(a * (curve.control1.x - from.x) + b * (curve.control2.x - curve.control1.x) + c * (curve.to.x - curve.control2.x), a * (curve.control1.y - from.y) + b * (curve.control2.y - curve.control1.y) + c * (curve.to.y - curve.control2.y));
+}
 /**
  * One piece cut into two at a fraction, both pieces drawing what the whole
  * drew, by de Casteljau's construction.

package/dist/index.d.ts

@@ -20,14 +20,14 @@ 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, splitCurve, straight, transformPath } from './figure/path.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, slopeOn, 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 { containsPoint, flattenPath, nearestEdge, windingAt } from './figure/inside.js';
+export type { Edge, 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';

package/dist/index.js

@@ -14,11 +14,11 @@ 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, splitCurve, straight, transformPath } from './figure/path.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';
 export { areaOf } from './figure/area.js';
 export { differenceOf, intersectionOf, unionOf } from './figure/boolean.js';
-export { containsPoint, flattenPath, windingAt } from './figure/inside.js';
+export { containsPoint, flattenPath, nearestEdge, 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';

package/package.json

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