flo-mat 4.1.5 → 5.0.1

package/__tests__/helpers/expect-point-close.ts

@@ -0,0 +1,42 @@
+import { expect } from '@jest/globals';
+
+
+/** Asserts two points (or any equal-length number arrays) are nearly equal. */
+function expectPointClose(
+        actual: number[],
+        expected: number[],
+        digits = 9): void {
+
+    expect(actual.length).toBe(expected.length);
+    for (let i=0; i<actual.length; i++) {
+        expect(actual[i]).toBeCloseTo(expected[i], digits);
+    }
+}
+
+
+/** Asserts two bezier curves are nearly equal (same order and control points). */
+function expectBezierClose(
+        actual: number[][],
+        expected: number[][],
+        digits = 9): void {
+
+    expect(actual.length).toBe(expected.length);
+    for (let i=0; i<actual.length; i++) {
+        expectPointClose(actual[i], expected[i], digits);
+    }
+}
+
+
+/** Asserts consecutive beziers in the array join up end-to-start. */
+function expectBeziersConnected(
+        pss: number[][][],
+        digits = 9): void {
+
+    for (let i=1; i<pss.length; i++) {
+        const prev = pss[i-1];
+        expectPointClose(pss[i][0], prev[prev.length-1], digits);
+    }
+}
+
+
+export { expectPointClose, expectBezierClose, expectBeziersConnected }

package/__tests__/mat/hausdorff-distance-one-sided-exceeds.spec.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from '@jest/globals';
+import { hausdorffDistanceOneSided, closestPointOnBezier, evalDeCasteljau } from 'flo-bezier3';
+import { hausdorffDistanceOneSidedExceeds, distanceToCurves } from '../../src/mat/hausdorff-distance-one-sided-exceeds.js';
+
+
+/**
+ * The one-sided Hausdorff distance from `A` to the piecewise curve `B`
+ * approximated by dense sampling of `A` (a lower bound, accurate to within
+ * the sample spacing times the speed of `A`).
+ */
+function sampledHausdorffDistanceOneSided(
+        A: number[][],
+        B: number[][][],
+        samples = 4096): number {
+
+    let worst = 0;
+    for (let i=0; i<=samples; i++) {
+        const p = evalDeCasteljau(A, i/samples);
+        let best = Infinity;
+        for (const qs of B) {
+            best = Math.min(best, closestPointOnBezier(qs, p).d);
+        }
+        worst = Math.max(worst, best);
+    }
+
+    return worst;
+}
+
+
+// a handful of 'from' curves of all orders
+const As: number[][][] = [
+    [[0,0], [100,0]],                           // a line
+    [[0,0], [50,30], [100,0]],                  // a quadratic
+    [[0,0], [30,40], [70,-40], [100,0]],        // a cubic with an inflection
+    [[0,0], [10,80], [90,80], [100,0]],         // a 'tall' cubic
+    [[0,0], [100,0], [0,0]],                    // a degenerate (folded) quadratic
+];
+
+// a handful of 'to' curves
+const Bs: number[][][] = [
+    [[0,1], [100,1]],                           // a line (offset by 1)
+    [[0,0], [50,10], [100,0]],                  // a quadratic
+    [[0,0], [50,-10], [100,0]],                 // a quadratic bending the other way
+    [[-10,5], [40,60], [110,-20]],              // a quadratic not sharing endpoints
+    [[0,0], [30,10], [70,10], [100,0]],         // a cubic
+];
+
+// relative margin beyond which the answers must certainly agree
+const MARGIN = 2**-10;
+
+
+describe('hausdorffDistanceOneSidedExceeds', function() {
+    test('agrees with the computed one-sided Hausdorff distance (single curve B)', function() {
+        let checks = 0;
+        for (const A of As) {
+            for (const B of Bs) {
+                // a very accurate reference value
+                const hd = hausdorffDistanceOneSided(A, B, 2**-30, 10_000);
+                expect(hd).toBeGreaterThan(0);
+
+                // tolerances on both sides of the reference value (a large
+                // iteration budget is given since certifying a distance that
+                // is *just* within tolerance requires resolving the curve to
+                // within the margin - e.g. the folded quadratic is at a
+                // uniform distance of 1 from the first line)
+                for (const f of [1/4, 1/2, 1 - 2*MARGIN, 1 + 2*MARGIN, 2, 4]) {
+                    const tolerance = f*hd;
+                    const exceeds = hausdorffDistanceOneSidedExceeds(A, [B], tolerance, 1_000_000);
+                    expect(exceeds).toBe(hd > tolerance);
+                    checks++;
+                }
+            }
+        }
+        expect(checks).toBe(As.length*Bs.length*6);
+    });
+
+    test('agrees with a densely sampled one-sided Hausdorff distance (piecewise B)', function() {
+        // piecewise 'to' curves - two quads joined at a point, and two
+        // disconnected pieces
+        const Bss: number[][][][] = [
+            [[[0,0], [25,20], [50,10]], [[50,10], [75,0], [100,0]]],
+            [[[0,2], [40,2]], [[60,-2], [100,-2]]],
+            [[[0,0], [30,10], [50,0]], [[50,0], [70,-10], [100,0]]],
+        ];
+
+        for (const A of As) {
+            for (const Bs of Bss) {
+                const hd = sampledHausdorffDistanceOneSided(A, Bs);
+                expect(hd).toBeGreaterThan(0);
+
+                // the sampled value is a lower bound accurate to about
+                // `speed/4096` which is ~0.05 here, so stay well clear of it
+                expect(hausdorffDistanceOneSidedExceeds(A, Bs, hd*(1 - 2**-3), 1000)).toBe(true);
+                expect(hausdorffDistanceOneSidedExceeds(A, Bs, hd*(1 + 2**-3), 1000)).toBe(false);
+            }
+        }
+    });
+
+    test('decides trivially for a point or line to a line', function() {
+        const B = [[[0,1], [100,1]]];
+        expect(hausdorffDistanceOneSidedExceeds([[50,0]], B, 0.5)).toBe(true);
+        expect(hausdorffDistanceOneSidedExceeds([[50,0]], B, 1.5)).toBe(false);
+        expect(hausdorffDistanceOneSidedExceeds([[0,0], [100,0]], B, 0.5)).toBe(true);
+        expect(hausdorffDistanceOneSidedExceeds([[0,0], [100,0]], B, 1.5)).toBe(false);
+        // a line to a line not parallel to it - the max is at an endpoint
+        expect(hausdorffDistanceOneSidedExceeds([[0,0], [100,0]], [[[0,0], [100,10]]], 9.9)).toBe(true);
+        expect(hausdorffDistanceOneSidedExceeds([[0,0], [100,0]], [[[0,0], [100,10]]], 10.1)).toBe(false);
+    });
+
+    test('is conservative when the iteration budget is exhausted', function() {
+        // the endpoints of `A` lie on `B` but the middle is 10 away; the
+        // initial upper bound is half the control polygon length (~54) so
+        // with no bisections allowed a tolerance of 30 cannot be certified
+        // either way and the check must fail
+        const A = [[0,0], [50,20], [100,0]];
+        const B = [[[0,0], [100,0]]];
+        expect(hausdorffDistanceOneSidedExceeds(A, B, 30, 0)).toBe(true);
+        // with a budget it decides correctly
+        expect(hausdorffDistanceOneSidedExceeds(A, B, 30, 50)).toBe(false);
+        expect(hausdorffDistanceOneSidedExceeds(A, B, 9.9, 50)).toBe(true);
+    });
+
+    test('distanceToCurves is the minimum over the pieces', function() {
+        const Bs = [[[0,0], [100,0]], [[0,10], [100,10]]];
+        expect(distanceToCurves([50,2], Bs)).toBeCloseTo(2, 12);
+        expect(distanceToCurves([50,8], Bs)).toBeCloseTo(2, 12);
+        expect(distanceToCurves([150,0], Bs)).toBeCloseTo(50, 12);
+    });
+});

package/__tests__/mat/simplify-mat.spec.ts

@@ -0,0 +1,85 @@
+import { expect, test } from '@jest/globals';
+import { getPathsFromStr } from 'flo-boolean';
+import { closestPointOnBezier, evalDeCasteljau } from 'flo-bezier3';
+import { distanceBetween } from 'flo-vector2d';
+import { findMats } from '../../src/find-mat/find-mats.js';
+import { simplifyMat } from '../../src/mat/simplify-mat.js';
+import { getAllOnLoop } from '../../src/cp-node/fs/get-all-on-loop.js';
+import { getMatCurveToNext } from '../../src/cp-node/fs/get-mat-curve-to-next.js';
+import { isTerminating } from '../../src/cp-node/fs/is-terminating.js';
+import type { CpNode } from '../../src/cp-node/cp-node.js';
+
+
+/** All the bezier pieces making up the MAT. */
+function getMatBeziers(cpNode: CpNode): number[][][] {
+    return getAllOnLoop(cpNode)
+        .filter(cp => !isTerminating(cp))
+        .flatMap(getMatCurveToNext);
+}
+
+
+/**
+ * The one-sided Hausdorff distance from the curves `A` to the curves `B`,
+ * approximated by sampling points on `A`.
+ */
+function sampledHausdorffDistanceOneSided(
+        A: number[][][],
+        B: number[][][],
+        samplesPerCurve = 16): number {
+
+    let worst = 0;
+    for (const ps of A) {
+        for (let i=0; i<=samplesPerCurve; i++) {
+            const p = evalDeCasteljau(ps, i/samplesPerCurve);
+            let best = Infinity;
+            for (const qs of B) {
+                const { p: q } = closestPointOnBezier(qs, p);
+                best = Math.min(best, distanceBetween(p, q));
+            }
+            worst = Math.max(worst, best);
+        }
+    }
+
+    return worst;
+}
+
+
+test('simplifyMat', function() {
+    // A smooth blob: its MAT is a single long branch made up of very many
+    // 2-prongs, so there is a lot to simplify.
+    const loops = getPathsFromStr(
+        'M0 0 C 50 -40 150 -40 200 0 C 250 40 250 80 200 120 ' +
+        'C 150 160 50 160 0 120 C -50 80 -50 40 0 0 Z'
+    );
+    const [mat] = findMats(loops, { simplify: false, applySat: false });
+    const original = getMatBeziers(mat.cpNode);
+    const originalCount = getAllOnLoop(mat.cpNode).length;
+    const originalTreeSizes = [...mat.meta.cpTrees.values()].map(t => t.size);
+
+    const hausdorffTolerance = 2**-3;
+    const simplified = simplifyMat(mat, hausdorffTolerance);
+    const simplifiedBeziers = getMatBeziers(simplified.cpNode);
+
+    // it did simplify...
+    expect(getAllOnLoop(simplified.cpNode).length).toBeLessThan(originalCount);
+    expect(simplifiedBeziers.length).toBeLessThan(original.length);
+
+    // ...but stayed within the tolerance: no point of the original MAT is
+    // further than `hausdorffTolerance` from the simplified MAT (the tolerance
+    // is a certified bound, up to floating point roundoff)
+    const hd = sampledHausdorffDistanceOneSided(original, simplifiedBeziers);
+    expect(hd).toBeLessThanOrEqual(hausdorffTolerance * (1 + 2**-20));
+
+    // the input MAT is left intact - its linked list *and* its `cpTrees`
+    expect(getAllOnLoop(mat.cpNode).length).toBe(originalCount);
+    expect([...mat.meta.cpTrees.values()].map(t => t.size)).toEqual(originalTreeSizes);
+
+    // the simplified MAT has its own `cpTrees`, consistent with its nodes
+    expect(simplified.meta.cpTrees).not.toBe(mat.meta.cpTrees);
+    const simplifiedNodes = getAllOnLoop(simplified.cpNode);
+    for (const [loop, tree] of simplified.meta.cpTrees) {
+        const onLoop = simplifiedNodes.filter(cp => cp.pointOnShape.curve.loop === loop);
+        expect(tree.size).toBe(onLoop.length);
+        for (const cp of onLoop) { expect(tree.find(cp)?.datum).toBe(cp); }
+    }
+});

package/__tests__/reconstruct-from-mat/reconstruct-from-mat.spec.ts

@@ -0,0 +1,39 @@
+import { expect, test } from '@jest/globals';
+import { reconstructFromMats } from '../../src/reconstruct-from-mat/reconstruct-from-mat.js';
+import { getAllOnLoop } from '../../src/cp-node/fs/get-all-on-loop.js';
+import { getMatsWithHole } from '../get-mats-with-hole.js';
+
+
+test('reconstructFromMats - does not modify the given MATs', function() {
+    // (the fixture is SAT-processed, so SAT-induced trivial 3-prongs - which
+    // `reconstructFromMats` removes before reconstructing - may be present)
+    const mats = getMatsWithHole();
+    const before = mats.map(mat => ({
+        cpNode: mat.cpNode,
+        nodes: getAllOnLoop(mat.cpNode),
+        links: getAllOnLoop(mat.cpNode).map(cp =>
+            [cp.prev, cp.next, cp.prevOnCircle, cp.nextOnCircle]
+        )
+    }));
+
+    const piecesss = reconstructFromMats(mats);
+    expect(piecesss.length).toBe(mats.length);
+    for (const piecess of piecesss) {
+        for (const pieces of piecess) { expect(pieces.length).toBeGreaterThan(0); }
+    }
+
+    // same start node, same nodes, same links
+    mats.forEach((mat, i) => {
+        expect(mat.cpNode).toBe(before[i].cpNode);
+        const nodes = getAllOnLoop(mat.cpNode);
+        expect(nodes.length).toBe(before[i].nodes.length);
+        expect(nodes.every((cp, k) => cp === before[i].nodes[k])).toBe(true);
+        nodes.forEach((cp, k) => {
+            const [prev, next, prevOnCircle, nextOnCircle] = before[i].links[k];
+            expect(cp.prev).toBe(prev);
+            expect(cp.next).toBe(next);
+            expect(cp.prevOnCircle).toBe(prevOnCircle);
+            expect(cp.nextOnCircle).toBe(nextOnCircle);
+        });
+    });
+});

package/__tests__/specific-cases/test-svgs/achispado.svg

@@ -7,6 +7,20 @@
     <glyph glyph-name=".notdef" horiz-adv-x="500" 
 d="M15 609v-593h469v593h-469zM500 0h-500v625h500v-625z" />
 
+<glyph glyph-name="Q_V2"
+d="
+        M 600 700
+        L 570 670
+        L 551.4300900092946 724.4845356715714 
+        C 550.4300900092946 726.2165864791402 550.2961154130791 728.4486372867091 550.6621408168635 729.8146626904936 
+        C 550.0281662206479 732.9127389018469 550.7602170282167 735.6447897094158 551.4922678357857 738.3768405169847 
+        C 552.3582932395701 738.8768405169847 552.7243186433545 740.2428659207691 552.7243186433545 740.2428659207691 
+        C 554.6884202584923 744.8409421321223 558.5185472774145 748.2069675359069 562.8486742963368 750.7069675359069 
+        C 568.0448267190433 753.7069675359069 573.3749537379655 754.474916728338 578.3390553531033 753.8768405169847 
+        z
+        "
+/>
+
 <glyph glyph-name="Q_V" unicode="&#xe015;" horiz-adv-x="750"
     d="
         M 1154.0678381635485 290.68533730950645

package/__tests__/utils/get-beziers-from-tangents.spec.ts

@@ -0,0 +1,142 @@
+import { expect, test } from '@jest/globals';
+import { cross, distanceBetween, fromTo, toUnitVector, translate } from 'flo-vector2d';
+import { getBeziersFromTangents } from '../../src/utils/get-beziers-from-tangents.js';
+import { expectBezierClose, expectBeziersConnected, expectPointClose } from '../helpers/expect-point-close.js';
+
+
+const startTan = (ps: number[][]) => toUnitVector(fromTo(ps[0], ps[1]));
+const endTan   = (ps: number[][]) => toUnitVector(fromTo(ps[ps.length-2], ps[ps.length-1]));
+/** tangent line at `p` with direction `angle` radians from the x-axis (and the given length) */
+const line = (p: number[], angle: number, length = 1) =>
+    [p, translate(p, [length*Math.cos(angle), length*Math.sin(angle)])];
+
+
+/** The invariants of a twisted result: two quadratics, exact ends, smooth join. */
+function checkTwoQuadratics(pss: number[][][], p0: number[], p1: number[], d0: number[], d1: number[]) {
+    expect(pss.length).toBe(2);
+    expect(pss[0].length).toBe(3);
+    expect(pss[1].length).toBe(3);
+
+    // endpoints and end tangents are exact
+    expect(pss[0][0]).toBe(p0);
+    expect(pss[1][2]).toBe(p1);
+    expect(cross(startTan(pss[0]), toUnitVector(d0))).toBeCloseTo(0, 12);
+    expect(cross(endTan(pss[1]), toUnitVector(d1))).toBeCloseTo(0, 12);
+
+    // joined, and smoothly so
+    expectBeziersConnected(pss, 12);
+    expect(cross(endTan(pss[0]), startTan(pss[1]))).toBeCloseTo(0, 12);
+
+    // control points lie on the tangent lines a quarter chord away from the
+    // endpoints, towards the other endpoint
+    const chord = distanceBetween(p0, p1);
+    expect(distanceBetween(p0, pss[0][1])).toBeCloseTo(chord/4, 9);
+    expect(distanceBetween(p1, pss[1][1])).toBeCloseTo(chord/4, 9);
+    expect(distanceBetween(pss[0][1], p1)).toBeLessThan(distanceBetween(p0, p1) + chord/4);
+    expect(distanceBetween(pss[1][1], p0)).toBeLessThan(distanceBetween(p0, p1) + chord/4);
+}
+
+
+test('getBeziersFromTangents - not twisted: a single quadratic', function() {
+    // tangents (1,1) at [0,0] and (1,-1) at [10,0] meet at [5,5]
+    const pss = getBeziersFromTangents(line([0,0], Math.PI/4), line([10,0], -Math.PI/4));
+    expect(pss.length).toBe(1);
+    expectBezierClose(pss[0], [[0,0],[5,5],[10,0]]);
+});
+
+
+test('getBeziersFromTangents - collinear: a line', function() {
+    const pss = getBeziersFromTangents(line([0,0], 0), line([10,0], 0));
+    expect(pss).toEqual([[[0,0],[10,0]]]);
+});
+
+
+test('getBeziersFromTangents - collinear with the intersection landing on an endpoint: a line', function() {
+    // From the `getMats1` fixture (edge 3 -> 145): both tangents point along
+    // the chord [46,54] -> [81.5,18.5] but numerically the lines intersect
+    // exactly at the end point. This must not produce a degenerate quadratic
+    // `[p0, p1, p1]` (with a zero end tangent) but a line.
+    const s = Math.SQRT1_2;
+    const l0 = [[46,54], [46+s, 54-s]];
+    const l1 = [[81.5,18.5], [81.5-s, 18.5+s]];
+    const pss = getBeziersFromTangents(l0, l1);
+    expect(pss.length).toBe(1);
+    expect(pss[0].length).toBe(2);
+    expectPointClose(pss[0][0], [46,54]);
+    expectPointClose(pss[0][1], [81.5,18.5]);
+});
+
+
+test('getBeziersFromTangents - twisted (inflection): two quadratics', function() {
+    // tangents tilted to the *same* side at both ends force an S-shape
+    const cases = [
+        { p0: [0,0], p1: [10,0], a0:  0.006, a1:  0.006 },  // symmetric
+        { p0: [0,0], p1: [10,0], a0:  0.008, a1:  0.001 },  // asymmetric
+        { p0: [3,7], p1: [9,2],  a0: -0.007, a1: -0.004 },  // rotated chord
+        { p0: [0,0], p1: [10,0], a0:  0.5,   a1:  0.3   },  // strongly twisted
+        { p0: [0,0], p1: [10,0], a0:  Math.PI/2, a1: Math.PI/2 },  // tangents perpendicular to the chord
+    ];
+    for (const { p0, p1, a0, a1 } of cases) {
+        const chordAngle = Math.atan2(p1[1]-p0[1], p1[0]-p0[0]);
+        const l0 = line(p0, chordAngle + a0);
+        const l1 = line(p1, chordAngle + a1);
+        const d0 = fromTo(l0[0], l0[1]);
+        const d1 = fromTo(l1[0], l1[1]);
+
+        checkTwoQuadratics(getBeziersFromTangents(l0, l1), p0, p1, d0, d1);
+    }
+});
+
+
+test('getBeziersFromTangents - scale, tangent magnitude and orientation do not matter', function() {
+    const p0 = [0,0], p1 = [10,0];
+    const ref = getBeziersFromTangents(line(p0, 0.006), line(p1, 0.006));
+
+    const expectSame = (pss: number[][][]) => {
+        expect(pss.length).toBe(ref.length);
+        pss.forEach((ps, i) => ps.forEach((p, k) => expectPointClose(p, ref[i][k], 9)));
+    };
+    // tangent magnitude (e.g. an unnormalized bezier derivative)
+    expectSame(getBeziersFromTangents(line(p0, 0.006, 123.4), line(p1, 0.006, 0.001)));
+    // tangent orientation (either direction along the tangent line)
+    expectSame(getBeziersFromTangents(line(p0, 0.006 + Math.PI), line(p1, 0.006)));
+    expectSame(getBeziersFromTangents(line(p0, 0.006), line(p1, 0.006 + Math.PI)));
+    // scale: the same configuration scaled by 1000 (and by 1/1000) gives the
+    // same *kind* of result, scaled
+    for (const s of [1000, 1/1000]) {
+        const pss = getBeziersFromTangents(line([0,0], 0.006), line([10*s,0], 0.006));
+        expect(pss.length).toBe(ref.length);
+        pss.forEach((ps, i) => ps.forEach((p, k) => {
+            expectPointClose(p, [ref[i][k][0]*s, ref[i][k][1]*s], 9);
+        }));
+    }
+});
+
+
+test('getBeziersFromTangents - twisted but within tolerance: a line', function() {
+    // barely twisted (sine of the angle below 2**-16): a straight line will do
+    const pss = getBeziersFromTangents(line([0,0], 1e-6), line([10,0], 1e-6));
+    expect(pss.length).toBe(1);
+    expectBezierClose(pss[0], [[0,0],[10,0]]);
+    // ...at any scale
+    const pss2 = getBeziersFromTangents(line([0,0], 1e-6), line([1e6,0], 1e-6));
+    expect(pss2.length).toBe(1);
+    expect(pss2[0].length).toBe(2);
+    // ...but just above the tolerance it is two quadratics
+    expect(getBeziersFromTangents(line([0,0], 2e-5), line([10,0], 2e-5)).length).toBe(2);
+});
+
+
+test('getBeziersFromTangents - coinciding endpoints: a degenerate line', function() {
+    const p = [46,8];
+    const pss = getBeziersFromTangents([p, [47,8]], [p, [46,9]]);
+    expect(pss).toEqual([[p, p]]);
+    // the same from the two nodes of a 1-prong (identical tangent lines)
+    expect(getBeziersFromTangents([p, [47,9]], [p, [47,9]])).toEqual([[p, p]]);
+});
+
+
+test('getBeziersFromTangents - degenerate tangent: a line', function() {
+    const pss = getBeziersFromTangents([[0,0], [0,0]], line([10,0], 0.3));
+    expect(pss).toEqual([[[0,0],[10,0]]]);
+});