flo-mat 4.1.4 → 5.0.1

package/src/find-3-prong/find-3-prong.ts

@@ -1,51 +1,54 @@
-import type { CpNode } from '../cp-node/cp-node.js';
-import type { ThreeProngInfo } from './three-prong-info.js';
-import { find3ProngForDelta3s } from './find-3-prong-for-delta3s.js';
-import { getBoundaryPieceBeziers } from '../mat/get-boundary-piece-beziers.js';
-
-
-/**
- * Find and return a 3-prong from the given boundary piece.
- * 
- * @param δs A boundary piece
- * @param maxCoordPowerOf2 The maximum coordinate power of 2 value used to
- * calculate floating point tolerances.
- * 
- * @internal
- */ 
-function find3Prong(
-        δs: [CpNode, CpNode][],
-        maxCoordPowerOf2: number): ThreeProngInfo {
-
-    // FUTURE if `δs.length > (some threshold (say 4 or 5))` then add two-prongs
-    // to reduced the number of permutations required
-    // if (δs.length > 3) { console.log(δs.length); }
-
-    const curvePiecess = δs.map(getBoundaryPieceBeziers);
-
-    // The best candidate amongst the different 'permutations' of the given δs.
-    let threeProng: ThreeProngInfo;
-
-    let smallestError = Infinity;
-    for (let i=1; i<δs.length - 1; i++) {
-        for (let k=0; k<3; k++) {
-            const r = find3ProngForDelta3s(
-                δs, i, k, curvePiecess, maxCoordPowerOf2
-            );
-
-            if (r === undefined) { continue; }
-
-            const { error, threeProngInfo } = r;
-
-            if (error < smallestError) {
-                smallestError = error;
-                threeProng = threeProngInfo;
-            }
-        }
-    }
-
-    return threeProng!;
-}
-
-
-export { find3Prong }
+import type { CpNode } from '../cp-node/cp-node.js';
+import type { ThreeProngInfo } from './three-prong-info.js';
+import { find3ProngForDelta3s } from './find-3-prong-for-delta3s.js';
+import { getBoundaryPieceBeziers } from '../mat/get-boundary-piece-beziers.js';
+
+
+/**
+ * Find and return a 3-prong from the given boundary piece.
+ * 
+ * @param δs A boundary piece
+ * @param maxCoordPowerOf2 The maximum coordinate power of 2 value used to
+ * calculate floating point tolerances.
+ * 
+ * @internal
+ */ 
+
+function find3Prong(
+        δs: [CpNode, CpNode][],
+        maxCoordPowerOf2: number): ThreeProngInfo {
+
+    // FUTURE if `δs.length > (some threshold (say 4 or 5))` then add two-prongs
+    // to reduced the number of permutations required
+    // if (δs.length > 3) { console.log(δs.length); }
+
+    const curvePiecess = δs.map(getBoundaryPieceBeziers);
+    // all the curve pieces of all the boundary pieces (for culling against)
+    const allCurvePieces = curvePiecess.flat();
+
+    // The best candidate amongst the different 'permutations' of the given δs.
+    let threeProng: ThreeProngInfo;
+
+    let smallestError = Infinity;
+    for (let i=1; i<δs.length - 1; i++) {
+        for (let k=0; k<3; k++) {
+            const r = find3ProngForDelta3s(
+                δs, i, k, curvePiecess, allCurvePieces, maxCoordPowerOf2
+            );
+
+            if (r === undefined) { continue; }
+
+            const { error, threeProngInfo } = r;
+
+            if (error < smallestError) {
+                smallestError = error;
+                threeProng = threeProngInfo;
+            }
+        }
+    }
+
+    return threeProng!;
+}
+
+
+export { find3Prong }

package/src/find-3-prong/find-and-add-3-prongs.ts

@@ -36,12 +36,31 @@ function findAndAdd3Prongs(
     }
 
     const addedCpNodes: CpNode[][] = [];
+    let maxIterations: number | undefined = undefined;
+    let iterations = 0;
     do {
         if (cpStart === undefined) { continue; }
         const visitedCps = traverseCp(cpStart);
-    
+
         if (visitedCps.length <= 2) { break; }
 
+        // Each added 3-prong splits off a part of the traversed face so the
+        // number of iterations is bounded by the initial face size. If the
+        // face does not shrink (e.g. a geometrically invalid vertex causing the
+        // same 3-prong to be re-inserted again and again) fail loudly instead
+        // of looping forever.
+        if (maxIterations === undefined) {
+            maxIterations = 2*visitedCps.length + 16;
+        }
+        if (++iterations > maxIterations) {
+            const pos = cpStart.pointOnShape;
+            throw new Error(
+                `findAndAdd3Prongs: no convergence after ${iterations} iterations ` +
+                `(face with ${visitedCps.length} vertices, start CpNode id ${cpStart.id} ` +
+                `on curve ${pos.curve.idx} at t = ${pos.t}, radius ${pos.circle.radius})`
+            );
+        }
+
         const { closeBysFor3Prong, cpNodes } = findAndAdd3Prong(meta, visitedCps);
 
         addedCpNodes.push(cpNodes);

package/src/find-mat/create-initial-cp-tree.ts

@@ -41,8 +41,8 @@ function createInitialCpTree(
             const pos1: PointOnShape = { ...ppos, curve,             t: 1, circle, order: -1, order2: 0 };
             const pos2: PointOnShape = { ...ppos, curve: curve.next, t: 0, circle, order: +1, order2: 0 };
 
-            cpNode1 = insertCpNode(true, false, false, cpTree, pos1, cpNode2, undefined, /* unused */ lastInsertId)!;
-            cpNode2 = insertCpNode(true, false, false, cpTree, pos2, cpNode1, undefined, /* unused */ lastInsertId)!;
+            cpNode1 = insertCpNode(true, false, false, cpTree, pos1, cpNode2, undefined, lastInsertId)!;
+            cpNode2 = insertCpNode(true, false, false, cpTree, pos2, cpNode1, undefined, lastInsertId)!;
             
             cpNode1.prevOnCircle = cpNode2;
             cpNode2.prevOnCircle = cpNode1;

package/src/find-mat/find-mat.ts

@@ -8,7 +8,7 @@ import type { MatOptions } from './mat-options.js';
 import type { MatMeta } from '../mat/mat-meta.js';
 import { findAndAdd3ProngsOnLoop } from '../find-3-prong/find-and-add-3-prongs-on-loop.js';
 import { createInitialCpTree } from './create-initial-cp-tree.js';
-import { getPartialMeta, addDebugInfo1, addDebugInfo2, addDebugInfo3, addDebugInfo4 } from './get-meta.js';
+import { addDebugElems, addDebugInfo1, addDebugInfo2, addDebugInfo3, addDebugInfo4 } from './get-meta.js';
 import { getSharpCornersOnLoop } from './get-sharp-corners.js';
 import { getDullCornersOnLoop } from './get-dull-corners-on-loop.js';
 import { findAndAdd2ProngsOnAllLoops } from '../find-2-prong/find-and-add-2-prongs-on-all-loops.js';
@@ -16,7 +16,6 @@ import { getFor2ProngsOnLoop } from './get-for-2-prongs-on-loop.js';
 import { getFor1ProngsOnLoop } from './get-for-1-prongs-on-loop.js';
 import { findAndAddHoleClosing2Prongs } from '../find-2-prong/find-and-add-hole-closing-2-prongs.js';
 import { getShapeBounds } from '../svg/get-shape-bounds.js';
-import { checkOrdering } from '../debug/functions/check-ordering.js';
 
 
 /**
@@ -34,6 +33,7 @@ function findMat(
         } {
 
     addDebugInfo1();
+    addDebugElems(loops);
 
     const { minBezLength, maxCurviness, maxLength, angleIncrement } = options;
 
@@ -51,10 +51,9 @@ function findMat(
     const lastInsertId = { id: 0 };
     const cpTrees = createInitialCpTree(loops, sharpCornersPerLoop, lastInsertId);
 
-    const _meta = getPartialMeta(loops);
     const meta: MatMeta = {
         maxCoordPowerOf2, squaredDiagonalLength, loops, cpTrees,// pointToCpNode,
-        lastInsertId, ..._meta
+        lastInsertId
     };
 
     let cpNode: CpNode | undefined;
@@ -89,7 +88,6 @@ function findMat(
         if (_debug_.directives.stopAfterThreeProngs) { return { cpNode, meta }; }
     }
 
-    // if (cpNode !== undefined) { checkOrdering(meta, cpNode); }
 
     const mat = { cpNode, meta };
 
@@ -105,4 +103,4 @@ export { findMat }
 
 /** Curvilinear Shape Features (CSFs) */
 // const csfs = getCsfs(meta, minBezLength, loops);
-// const ligatures = getLigatures(meta, csfs);
+// const ligatures = getLigatures(meta, csfs);

package/src/find-mat/find-mats.ts

@@ -1,105 +1,83 @@
-import { beziersToSvgPathStr, simplifyPaths } from 'flo-boolean';
-import { getLoopsMetrics } from '../loop/get-max-coordinate.js';
-import { Mat } from '../mat/mat.js';
-import { simplifyMat } from '../mat/simplify-mat.js';
-import { toScaleAxis } from '../sat/to-scale-axis.js';
-import { clipOptions } from './clip-options.js';
-import { findMat  } from './find-mat.js';
-import { defaultMatOptions, MatOptions } from './mat-options.js';
-
-
-const { ceil, log2 } = Math;
-
-
-/**
- * Finds and returns the Medial Axis Transforms (MATs) from the given array of 
- * bezier loops representing shape boundaries.
- * 
- * @param bezierLoops An array of (possibly intersecting) loops with each loop 
- * representing one or more piecewise smooth closed curves (i.e. shapes). Each 
- * loop consists of an array of beziers represented by an array of control 
- * points with 2,3 or 4 elements corresponding to linear, quadratic and cubic 
- * beziers respectively. Each point is a two-element array (ordered pair), the
- * first of which is the x-coordinate and the second the y-coordinate.
- * 
- * @param maxCurviness The maximum value the 'curviness' of a curve can have 
- * before an additional MAT point is inserted in between. Defaults to 0.4. 
- * (Curviness is measured as the total angle in radians between the consecutive 
- * vectors formed by the ordered control points of th bezier curve). The value
- * is clipped in the range `[0.01,3]`.
- * 
- * @param maxLength The maximum length a curve can have before an additional MAT 
- * point is inserted. This value is scaled to a reference 1024 x 1024 
- * grid (e.g. if the shape fits in a 512 x 512 axis-aligned box the value will be 
- * halved, e.g. from 10 to 5). Together with maxCurviness it represents a 
- * tolerance for the accuracy of the MAT. Defaults to 4. The value is clipped 
- * in [1,100].
- */
-function findMats(
-        bezierLoops: number[][][][],
-        options?: MatOptions): Mat[] {
-
-    // if (typeof _debug_ !== 'undefined') { var timingStart = performance.now(); }
-    const { maxCoordinate } = getLoopsMetrics(bezierLoops);
-    const maxCoordPowerOf2 = ceil(log2(maxCoordinate));
-
-    const options_: Required<MatOptions> = clipOptions(
-        maxCoordPowerOf2, {
-        ...defaultMatOptions,
-        ...(options || {})
-    });
-
-    const {
-        applySat, simplify,
-        satScale, simplifyTolerance
-    } = options_;
-
-
-    const loopss = simplifyPaths(bezierLoops, {
-        forceOrientationNegative: true,
-    });
-
-    // console.log(loopsToSvgPathStr(bezierLoops));
-
-    const mats: Mat[] = [];
-    for (const loops of loopss) {
-        let mat = findMat(loops, maxCoordPowerOf2, options_);
-        if (mat === undefined) { continue; }
-
-        if (applySat) {
-            mat = toScaleAxis(mat, satScale);
-        }
-
-        if (simplify) {
-            mat = simplifyMat(mat, simplifyTolerance, 50)
-        }
-
-        mats.push(mat);
-    }
-    
-    // console.log(structuredClone(circumCenter.getStats()));
-    // circumCenter.resetStats();
-
-    return mats;
-}
-
-
-
-/**
- * Returns an SVG path string representation of the given bezier loops.
- * @param loops An array of loops having an array of bezier curves each given as 
- * an array of control points.
- */
-function loopsToSvgPathStr(
-        loops: number[][][][]) {
-
-    let str = '';
-    for (const loop of loops) {
-        str = str + beziersToSvgPathStr(loop) + '\n';
-    }
-
-    return str;
-}
-
-
-export { findMats }
+import { simplifyPaths } from 'flo-boolean';
+import { getLoopsMetrics } from '../loop/get-max-coordinate.js';
+import { Mat } from '../mat/mat.js';
+import { simplifyMat } from '../mat/simplify-mat.js';
+import { toScaleAxis } from '../sat/to-scale-axis.js';
+import { clipOptions } from './clip-options.js';
+import { findMat  } from './find-mat.js';
+import { resetDebugElems } from './get-meta.js';
+import { defaultMatOptions, MatOptions } from './mat-options.js';
+
+
+const { ceil, log2 } = Math;
+
+
+/**
+ * Finds and returns the Medial Axis Transforms (MATs) from the given array of 
+ * bezier loops representing shape boundaries.
+ * 
+ * @param bezierLoops An array of (possibly intersecting) loops with each loop 
+ * representing one or more piecewise smooth closed curves (i.e. shapes). Each 
+ * loop consists of an array of beziers represented by an array of control 
+ * points with 2,3 or 4 elements corresponding to linear, quadratic and cubic 
+ * beziers respectively. Each point is a two-element array (ordered pair), the
+ * first of which is the x-coordinate and the second the y-coordinate.
+ *
+ * @param options the `MatOptions` (see there for a description of each option
+ * and its default), e.g. `maxCurviness` and `maxLength` together determine the
+ * accuracy of the MAT, `simplify` and `simplifyTolerance` control the
+ * simplification of the result and `applySat` and `satScale` whether and how
+ * the Scale Axis Transform is applied. Missing options take their defaults
+ * (`defaultMatOptions`) and all values are clipped to their allowed ranges.
+ */
+function findMats(
+        bezierLoops: number[][][][],
+        options?: MatOptions): Mat[] {
+
+    // if (typeof _debug_ !== 'undefined') { var timingStart = performance.now(); }
+    resetDebugElems();
+    const { maxCoordinate } = getLoopsMetrics(bezierLoops);
+    const maxCoordPowerOf2 = ceil(log2(maxCoordinate));
+
+    const options_: Required<MatOptions> = clipOptions(
+        maxCoordPowerOf2, {
+        ...defaultMatOptions,
+        ...(options || {})
+    });
+
+    const {
+        applySat, simplify,
+        satScale, simplifyTolerance
+    } = options_;
+
+
+    const loopss = simplifyPaths(bezierLoops, {
+        forceOrientationNegative: true,
+    });
+
+
+    const mats: Mat[] = [];
+    for (const loops of loopss) {
+        let mat = findMat(loops, maxCoordPowerOf2, options_);
+        if (mat === undefined) { continue; }
+
+        if (applySat) {
+            mat = toScaleAxis(mat, satScale);
+        }
+
+        if (simplify) {
+            mat = simplifyMat(mat, simplifyTolerance)
+        }
+
+        mats.push(mat);
+    }
+    
+    // console.log(structuredClone(circumCenter.getStats()));
+    // circumCenter.resetStats();
+
+    return mats;
+}
+
+
+
+export { findMats }

package/src/find-mat/get-dull-corners-on-loop.ts

@@ -1,7 +1,7 @@
 import type { PrePointOnShape } from '../point-on-shape/point-on-shape.js';
 import type { Loop } from 'flo-boolean';
 import { controlPointLinesLength } from 'flo-bezier3';
-import { getCorner } from '../corner/get-corner.js';
+import { getCorner$ } from '../corner/get-corner.js';
 
 
 /** @internal */
@@ -20,7 +20,7 @@ function getDullCornersOnLoop(
 
             const { next, ps } = curve;
 
-            if (getCorner(ps, next.ps).isQuiteDull) {
+            if (getCorner$(ps, next.ps).isQuiteDull) {
                 const p = ps[ps.length - 1];
                 const pDd = [[0,p[0]], [0,p[1]]];
 

package/src/find-mat/get-for-1-prongs-on-loop.ts

@@ -1,9 +1,28 @@
 import type { Loop } from 'flo-boolean';
 import type { PrePointOnShape } from '../point-on-shape/point-on-shape.js';
 import { getCurvatureExtremaDd, controlPointLinesLength } from 'flo-bezier3';
+import { distanceBetween } from 'flo-vector2d';
 import { toP } from '../point-on-shape/to-p.js';
 
 
+/** 
+ * @internal
+ * Curvature maxima closer than this (in parameter space) to a curve endpoint
+ * are ignored - they are handled by the corner logic.
+ */
+const EDGE_T_TOLERANCE = 2**-20;
+/** 
+ * @internal
+ * Curvature maxima closer than this fraction of the curve's control polygon
+ * length to a curve endpoint are ignored. A curve with (near) coincident
+ * control points at an end has (near) zero speed there and its curvature
+ * blows up towards that end; the resulting "maximum" (that can be well 
+ * inside the parameter tolerance above) is an artifact and not a feature of
+ * the shape.
+ */
+const EDGE_DISTANCE_TOLERANCE = 2**-20;
+
+
 /**
  * Get points of maximum curvature.
  * 
@@ -19,24 +38,37 @@ function getFor1ProngsOnLoop(
 
         for (let i=0; i<loop.curves.length; i++) {
             const curve = loop.curves[i];
+            const { ps } = curve;
 
-            if (controlPointLinesLength(curve.ps) < minBezLength) {
+            const len = controlPointLinesLength(ps);
+            if (len < minBezLength) {
                 continue;
             }
 
-            const { ps } = curve;
+            const pS = ps[0];
+            const pE = ps[ps.length-1];
+            const edgeDistanceTolerance = len * EDGE_DISTANCE_TOLERANCE;
+
+            for (const t of getCurvatureExtremaDd(ps).maxima) {
+                // keep away from edges (in parameter space)
+                if (t < EDGE_T_TOLERANCE || t > 1 - EDGE_T_TOLERANCE) {
+                    continue;
+                }
 
-            poss.push(...getCurvatureExtremaDd(ps).maxima.map(t => {
                 const pDd = toP(ps, t);
                 const p = pDd.map(c => c[0] + c[1]);
 
-                return { curve, t, isSource: true, p, pDd }
-            }));
+                // keep away from edges (in distance)
+                if (distanceBetween(p, pS) < edgeDistanceTolerance || 
+                    distanceBetween(p, pE) < edgeDistanceTolerance) {
+                    continue;
+                }
+
+                poss.push({ curve, t, isSource: true, p, pDd });
+            }
         }
 
-        return poss
-            // keep away from edges
-            .filter(pos => pos.t > 2**-20 && pos.t < 2**-20);
+        return poss;
     }
 }
 

package/src/find-mat/get-meta.ts

@@ -1,10 +1,9 @@
 import type { Debug }   from '../debug/debug.js';
 import type { Loop } from 'flo-boolean';
-import type { Curve } from 'flo-boolean';
-import type { MatMeta } from '../mat/mat-meta.js';
-import { getBoundingHull, getBoundingBoxTight } from 'flo-bezier3';
-import { getBoundingBox$ } from '../geometry/get-bounding-box-.js';
+import { getBoundingHull } from 'flo-bezier3';
+import { getBoundingBox$, getBoundingBoxTight$ } from '../geometry/get-bounding-box-.js';
 import { getCorner } from '../corner/get-corner.js';
+import { createEmptyElems } from '../debug/debug.js';
 
 
 /** @internal */
@@ -14,38 +13,41 @@ declare const _debug_: Debug;
 let timingStart: number;
 
 
-/** @internal */
-function getPartialMeta(
-        loops: Loop[]): Omit<
-            MatMeta,
-            | 'cpTrees'
-            // | 'pointToCpNode'
-            | 'loops'
-            | 'maxCoordPowerOf2'
-            | 'squaredDiagonalLength'
-            | 'lastInsertId'
-        > {
-
-    const looseBoundingBoxes: number[][][] = [];
-    const tightBoundingBoxes: number[][][] = [];
-    const boundingHulls: number[][][] = [];
-    const sharpCorners: Curve[] = [];
-    const dullCorners: Curve[] = [];
+/**
+ * @internal
+ * Resets the generated debug `_debug_.elems` (if debug is enabled) so that
+ * they only reflect the current `findMats` call.
+ */
+function resetDebugElems() {
+    if (typeof _debug_ === 'undefined') { return; }
+
+    _debug_.elems = { ..._debug_.elems, ...createEmptyElems() };
+}
+
+
+/**
+ * @internal
+ * Adds (if debug is enabled) the loose and tight bounding boxes, the bounding
+ * hulls and the sharp and dull corners of the given loops' curves to
+ * `_debug_.elems` for later inspection by consumers.
+ */
+function addDebugElems(loops: Loop[]) {
+    if (typeof _debug_ === 'undefined') { return; }
+
+    const { 
+        looseBoundingBoxes, tightBoundingBoxes, boundingHulls,
+        sharpCorners, dullCorners
+    } = _debug_.elems;
 
     for (const loop of loops) {
         for (const curve of loop.curves) {
             const ps = curve.ps;
-            const hull = getBoundingHull(ps, true)!;
-
-            boundingHulls.push(hull);
 
-            const looseBoundingBox = getBoundingBox$(ps);
-            looseBoundingBoxes.push(looseBoundingBox);
+            boundingHulls.push(getBoundingHull(ps, true)!);
+            looseBoundingBoxes.push(getBoundingBox$(ps));
+            tightBoundingBoxes.push(getBoundingBoxTight$(ps));
 
-            const tightBoundingBox = getBoundingBoxTight(ps);
-            tightBoundingBoxes.push(tightBoundingBox);
-
-            const corner = getCorner(curve.ps, curve.next.ps);
+            const corner = getCorner(ps, curve.next.ps);
             if (corner.isQuiteSharp) {
                 sharpCorners.push(curve);
             } else if (corner.isQuiteDull) {
@@ -53,14 +55,6 @@ function getPartialMeta(
             }
         }
     }
-
-    return {
-        looseBoundingBoxes,
-        tightBoundingBoxes,
-        boundingHulls,
-        sharpCorners,
-        dullCorners
-    }
 }
 
 
@@ -102,7 +96,8 @@ function addDebugInfo4() {
 
 
 export {
-    getPartialMeta,
+    resetDebugElems,
+    addDebugElems,
     addDebugInfo1,
     addDebugInfo2,
     addDebugInfo3,

package/src/find-mat/get-sharp-corners.ts

@@ -2,7 +2,7 @@ import type { PrePointOnShape } from '../point-on-shape/point-on-shape.js';
 import type { Loop } from 'flo-boolean';
 import { controlPointLinesLength } from 'flo-bezier3';
 import { toP } from '../point-on-shape/to-p.js';
-import { getCorner } from '../corner/get-corner.js';
+import { getCorner$ } from '../corner/get-corner.js';
 
 
 /** @internal */
@@ -19,7 +19,7 @@ function getSharpCornersOnLoop(
                 continue;
             }
             
-            if (getCorner(curve.ps, curve.next.ps).isQuiteSharp) {
+            if (getCorner$(curve.ps, curve.next.ps).isQuiteSharp) {
                 const { ps } = curve;
 
                 const p = ps[ps.length - 1];

package/src/find-mat/mat-options.ts

@@ -59,7 +59,7 @@ interface MatOptions {
      * 
      * * Only applies if `simplify` is `true`
      * * Defaults to `1/16`
-     * * The value is clipped in `[2**-10,1024]`
+     * * The value is clipped in `[2**-20,2**20]`
      * * scaled to a 1024x1024 vector image size, i.e. a value of `1` on such
      * a vector image will have a `1` pixel accuracy. If the vector is, say,
      * 512x400 then the accuracy is scaled to `1/2` a pixel. This ensures
@@ -72,7 +72,7 @@ interface MatOptions {
      * 
      * * it is not recommended to change this value
      * * scaled to a 1024x1024 vector image size
-     * * Defaults to `1/16`
+     * * Defaults to `1/64`
      */
     readonly minBezLength?: number;