flo-mat 4.1.5 → 5.0.2

package/src/cp-node/fs/get-first-exit.ts

@@ -1,25 +1,26 @@
-import { CpNode } from "../cp-node.js";
+import type { CpNode } from "../cp-node.js";
+import { isTerminating } from "./is-terminating.js";
 
 
 /**
- * Returns the first `CpNode` (from this one by successively applying 
- * .nextOnCircle) that exits the circle.
+ * Returns the first `CpNode` *after* the given one (by successively applying 
+ * `.nextOnCircle`) that exits the circle, i.e. the first one that is not
+ * terminating - the given `CpNode` itself is never returned.
+ * 
+ * * returns `undefined` if no other `CpNode` on the circle exits (e.g. the 
+ *   other `CpNode` of a 1-prong, or the MAT is a single point)
  */
-function getFirstExit(cpNode: CpNode) {
-    // const startNode = this as CpNode;
-    const startNode = cpNode;
-    let cpNode_ = startNode;
+function getFirstExit(cpNode: CpNode): CpNode | undefined {
+    let cpNode_ = cpNode.nextOnCircle;
 
-    while (cpNode_.next === cpNode_.prevOnCircle) {
-        cpNode_ = cpNode_.next;
-
-        if (cpNode_ === startNode) {
-            // The very special case the MAT is a single point.
-            return undefined; 
+    while (cpNode_ !== cpNode) {
+        if (!isTerminating(cpNode_)) {
+            return cpNode_;
         }
+        cpNode_ = cpNode_.nextOnCircle;
     }
 
-    return cpNode_;
+    return undefined;
 }
 
 

package/src/cp-node/fs/get-implied-boundary-bezier-between.ts

@@ -1,76 +1,24 @@
 import type { CpNode } from '../cp-node.js';
-import { tangent } from 'flo-bezier3';
-import { fromTo, dot, cross, translate, lineLineIntersection, toUnitVector } from 'flo-vector2d';
-
-const { abs } = Math;
-
-
-/** @internal */
-const TOLERANCE_ADD_2PRONG = 0.01;
-/** @internal */
-const TOLERANCE_USE_LINE = 0.0001; // else cubic
-
-
+import { getBoundaryTangentLine } from '../../point-on-shape/get-boundary-tangent-line.js';
+import { getBeziersFromTangents } from '../../utils/get-beziers-from-tangents.js';
+
+
+/**
+ * Returns the bezier curves (an array of 1 or 2 lines or quadratics joined
+ * smoothly) approximating the shape boundary between the contact points of 
+ * two `CpNode`s.
+ * 
+ * @param cpNodeA 
+ * @param cpNodeB 
+ */
 function getImpliedBoundaryBezierBetween(
         cpNodeA: CpNode,
-        cpNodeB: CpNode): number[][] | undefined {
-
-    const posA = cpNodeA.pointOnShape;
-    const posB = cpNodeB.pointOnShape;
-
-    let { curve: curveA, p: pA, t: tA } = posA;
-    let { curve: curveB, p: pB, t: tB } = posB;
-
-    if (pA[0] === pB[0] && pA[1] === pB[1]) {
-        return [pA];
-    }
-
-    if (tA === 1) { tA = 0; curveA = curveA.next; }
-    if (tB === 0) { tB = 1; curveB = curveB.prev; }
-    
-    const { ps: psA } = curveA;
-    const { ps: psB } = curveB;
-
-    const lA = [pA,translate(pA)(toUnitVector(tangent(psA, tA)))];
-    const lB = [pB,translate(pB)(toUnitVector(tangent(psB, tB)))];
-
-    const mid = lineLineIntersection(lA, lB);
-
-    const c = fromTo(pA,pB);
-
-    let twisted: boolean;
-    if (!mid) {
-        twisted = true;
-    } else {
-        const a = fromTo(pA, mid);
-        const b = fromTo(pB, mid);
-        
-        twisted = dot(a,c) < 0 || dot(b,c) > 0;
-    }
-    
-    if (!twisted) {
-        // drawFs.bezier(g, [pA, mid!, pB], 'thin10 pink nofill', 0)
-        return [pA, mid!, pB];
-    } 
-        
-    const w1 = fromTo(lA[0], lA[1]);  // This is a unit vector
-    const w2 = fromTo(lB[0], lB[1]);  // This is a unit vector
-
-    const d1 = abs(cross(c, w1)) / (3*3); 
-    const d2 = abs(cross(c, w2)) / (3*3); 
-
-    if (d1 > TOLERANCE_ADD_2PRONG || d2 > TOLERANCE_ADD_2PRONG) {
-        // not within tolerance
-        return undefined;
-    } 
-
-    if (d1 > TOLERANCE_USE_LINE || d2 > TOLERANCE_USE_LINE) {
-        // approximate with cubic bezier?
-        return undefined;  // add 2-prong
-    } 
+        cpNodeB: CpNode): number[][][] {
 
-    // Within tolerance - approximate with a straight line.
-    return [pA, pB];
+    return getBeziersFromTangents(
+        getBoundaryTangentLine(cpNodeA.pointOnShape, true),
+        getBoundaryTangentLine(cpNodeB.pointOnShape, false)
+    );
 }
 
 

package/src/cp-node/fs/get-mat-curve-between.ts

@@ -1,82 +1,24 @@
 import type { CpNode } from '../cp-node.js';
-import { 
-    fromTo as fromToVec, dot, cross, rotate90Degrees, interpolate, translate,
-    lineLineIntersection
-} from 'flo-vector2d';
 import { getEdgeDirection } from './get-edge-direction.js';
-
-const { abs } = Math;
-
-
-/** @internal */
-const TOLERANCE_ADD_2PRONG = 0.01;
-/** @internal */
-const TOLERANCE_USE_LINE = 0.0001; // else cubic
+import { getBeziersFromTangents } from '../../utils/get-beziers-from-tangents.js';
 
 
 /**
- * Returns the bezier curve from the maximal disk of one `CpNode` to another
- * `CpNode`'s maximal disk.
+ * Returns the bezier curves (an array of 1 or 2 lines or quadratics joined
+ * smoothly) from the maximal disk of one `CpNode` to another `CpNode`'s 
+ * maximal disk.
  * 
  * @param cpNodeFrom 
  * @param cpNodeTo 
  */
 function getMatCurveBetween(
         cpNodeFrom: CpNode, 
-        cpNodeTo: CpNode): number[][] {
-
-    const fromCc = cpNodeFrom.pointOnShape.circle.center;
-    const fromL = getEdgeDirection(cpNodeFrom);
-
-    const toCc = cpNodeTo.pointOnShape.circle.center;
-    const toL = getEdgeDirection(cpNodeTo.prevOnCircle);
-
-    const mid = lineLineIntersection(fromL, toL);
-
-    const c = fromToVec(fromCc,toCc);
-
-    let twisted: boolean;
-    if (!mid) {
-        twisted = true;
-    } else {
-        const a = fromToVec(fromCc, mid);
-        const b = fromToVec(toCc,   mid);
-        
-        twisted = dot(a,c) < 0 || dot(b,c) > 0;
-    }
-    
-    if (!twisted) {
-        return [fromCc, mid!, toCc];
-    } 
-        
-    const r = rotate90Degrees(c);
-    const w1 = fromToVec(fromL[0], fromL[1]); // This is a unit vector
-    const w2 = fromToVec(toL[0],  toL[1]);  // This is a unit vector
-
-    const d1 = abs(cross(c, w1)) / (3*3); 
-    const d2 = abs(cross(c, w2)) / (3*3); 
-
-    if (d1 > TOLERANCE_ADD_2PRONG || d2 > TOLERANCE_ADD_2PRONG) {
-        // FUTURE - not within tolerance - must add additional 2-prong
-        return [fromCc, toCc];
-    } 
-
-    if (d1 > TOLERANCE_USE_LINE || d2 > TOLERANCE_USE_LINE) {
-        // approximate with cubic bezier
-        const m1 = interpolate(fromCc,toCc,1/3);
-        const m2 = interpolate(fromCc,toCc,2/3);
-        const v1 = translate(r, m1);
-        const v2 = translate(r, m2);
-        const l1 = [m1,v1];
-        const l2 = [m2,v2];
-        const mid1 = lineLineIntersection(fromL, l1)!;
-        const mid2 = lineLineIntersection(toL,   l2)!;
-
-        return [fromCc, mid1, mid2, toCc];
-    } 
+        cpNodeTo: CpNode): number[][][] {
 
-    // Within tolerance - approximate with a straight line.
-    return [fromCc, toCc];
+    return getBeziersFromTangents(
+        getEdgeDirection(cpNodeFrom),
+        getEdgeDirection(cpNodeTo.prevOnCircle)
+    );
 }
 
 

package/src/cp-node/fs/get-mat-curves-between.ts

@@ -2,6 +2,14 @@ import { CpNode } from '../cp-node.js';
 import { getMatCurveBetween } from './get-mat-curve-between.js';
 
 
+/**
+ * Returns the (flattened) array of bezier curves (lines or quadratics) 
+ * representing the medial axis from one `CpNode` to another by following
+ * `next` repeatedly.
+ * 
+ * @param cpNodeS 
+ * @param cpNodeE 
+ */
 function getMatCurvesBetween(
         cpNodeS: CpNode,
         cpNodeE: CpNode) {
@@ -9,8 +17,7 @@ function getMatCurvesBetween(
     let cpNode = cpNodeS;
     const pss: number[][][] = [];
     while (cpNode !== cpNodeE) {
-        const ps = getMatCurveBetween(cpNode, cpNode.next);
-        pss.push(ps);
+        pss.push(...getMatCurveBetween(cpNode, cpNode.next));
 
         cpNode = cpNode.next;
     }

package/src/cp-node/fs/get-real-prong-count.ts

@@ -1,19 +1,23 @@
 import { CpNode } from "../cp-node.js";
-import { getAllOnCircle } from "./get-all-on-circle.js";
 import { isTerminating } from "./is-terminating.js";
 
 
 /**
- * Returns the number of contact points (up to planar coordinates) on the 
- * maximal disk circle implied by this `CpNode`. 
- * 
+ * Returns the number of contact points (up to planar coordinates) on the
+ * maximal disk circle implied by this `CpNode`, i.e. the number of
+ * non-terminating `CpNode`s on its circle.
+ *
  * See also `getProngCount`.
  */
 function getRealProngCount(cpNode: CpNode) {
-    const nonTerminatingCpNodes = getAllOnCircle(cpNode)
-    .filter(cpNode => !isTerminating(cpNode));
+    let count = 0;
+    let cpNode_ = cpNode;
+    do {
+        if (!isTerminating(cpNode_)) { count++; }
+        cpNode_ = cpNode_.nextOnCircle;
+    } while (cpNode_ !== cpNode);
 
-    return nonTerminatingCpNodes.length;
+    return count;
 }
 
 

package/src/cp-node/fs/get-salience.ts

@@ -6,8 +6,18 @@ import { sum } from '../../utils/sum.js';
 
 
 /**
+ * Returns the salience of the given `CpNode`: the ratio of the boundary length
+ * from its contact point forward to the next contact point on its circle to
+ * the straight distance between those two points.
+ *
+ * * `Infinity` if that stretch of boundary passes a hole closer
+ * * `0` if the two contact points coincide with no boundary in between (the
+ *   terminating `CpNode` of a 1-prong) - the other `CpNode` of a 1-prong,
+ *   whose stretch is the entire boundary, gives `Infinity`
+ *
  * See https://research.gold.ac.uk/id/eprint/31944/
- * @param cpNode 
+ *
+ * @param cpNode
  */
 function getSalience(cpNode: CpNode) {
     const cpNode1 = cpNode;
@@ -21,7 +31,10 @@ function getSalience(cpNode: CpNode) {
 
     const s = sum(pss.map(ps => totalLength(ps)));
 
-    return hasHoleCloser ? Infinity : s/d;
+    if (hasHoleCloser) { return Infinity; }
+    if (s === 0) { return 0; }  // (avoids `0/0` for the 1-prong case)
+
+    return s/d;
 }
 
 

package/src/cp-node/fs/is-fully-terminating.ts

@@ -1,28 +1,16 @@
 import type { CpNode } from "../cp-node.js";
-import { getAllOnCircle } from "./get-all-on-circle.js";
+import { getRealProngCount } from "./get-real-prong-count.js";
 import { isTerminating } from "./is-terminating.js";
-import { isTrivial } from "./is-trivial.js";
 
 
 /**
- * Like `isTerminating` but only returns true if all `CpNode`s on the circle
- * (except this.prevOnCircle) is terminating.
+ * Like `isTerminating` but only returns `true` if all `CpNode`s on the circle
+ * (except possibly the one leading back, i.e. `this.prevOnCircle`) are
+ * terminating - i.e. the `CpNode` is terminating and its vertex has at most
+ * one real prong.
  */
 function isFullyTerminating(cpNode: CpNode) {
-    if (!isTerminating(cpNode)) {
-        return false;
-    }
-
-    if (isTrivial(cpNode)) {
-        return true;
-    }
-
-    while (cpNode.prev === cpNode.prevOnCircle) {
-        cpNode = cpNode.prev;
-    }
-
-    return getAllOnCircle(cpNode.prevOnCircle, true)
-        .every(isTerminating);
+    return isTerminating(cpNode) && getRealProngCount(cpNode) <= 1;
 }
 
 

package/src/cp-node/fs/is-on-same-loop.ts

@@ -1,4 +1,4 @@
-import type { CpNode } from "flo-mat";
+import { CpNode } from "../cp-node.js";
 
 
 function isOnSameLoop(
@@ -12,4 +12,4 @@ function isOnSameLoop(
 }
 
 
-export { isOnSameLoop }
+export { isOnSameLoop }

package/src/cp-node/fs/is-special.ts

@@ -2,13 +2,18 @@ import type { CpNode } from "../cp-node.js";
 import { getRealProngCount } from "./get-real-prong-count.js";
 
 
-function isSpecial(
-        cpNode: CpNode) {
-
+/**
+ * Returns `true` if the given `CpNode` is on a 'special' MAT vertex, i.e. one
+ * that is not a plain 2-prong: a leaf, a 3-prong (or higher) or a hole-closer.
+ * 
+ * * these are the vertices that must be kept when simplifying the MAT and
+ *   the vertices of the MAT seen as a graph
+ */
+function isSpecial(cpNode: CpNode) {
     return (
-        (getRealProngCount(cpNode) !== 2) &&
-        !cpNode.isHoleClosing
-    )
+        getRealProngCount(cpNode) !== 2 ||
+        cpNode.isHoleClosing
+    );
 }
 
 

package/src/cp-node/fs/is-vertex.ts

@@ -1,4 +1,4 @@
-import { CpNode } from "../cp-node.js";
+import type { CpNode } from "../cp-node.js";
 import { getAllOnCircle } from "./get-all-on-circle.js";
 
 

package/src/cp-node/fs/traverse-edges.ts

@@ -4,10 +4,14 @@ import { getAllOnLoop } from './get-all-on-loop.js';
 
 
 /**
- * Traverses all edges (depth first) of the given MAT tree starting at the given 
- * vertex (represented by a `CpNode`).
- * @param cpNode Any `CpNode` representing the start vertex.
- * @param traverseEdgesCallback A callback function for each CpNode representing the vertex at the 
+ * Traverses all edges of the given MAT tree exactly once each, calling the
+ * callback for one of the two `CpNode`s representing each edge.
+ *
+ * * the edges are visited in boundary order starting from the given `CpNode`
+ *   (not depth first)
+ *
+ * @param cpNode Any `CpNode` on the MAT.
+ * @param traverseEdgesCallback A callback function for each CpNode representing the vertex at the
  * start of an edge.
  */
 function traverseEdges(

package/src/cp-node/stringification/from-stringifyable.ts

@@ -1,75 +1,75 @@
-import type { PointOnShape } from "../../point-on-shape/point-on-shape.js";
-import type { CpNode } from "../cp-node";
-import type { CpNodeStringifyable } from "./cp-node-stringifyable";
-import type { Mutable } from "../../utils/mutable.js";
-import { EDGES } from "./cp-node-stringifyable";
-import { getAllOnCircle } from "../fs/get-all-on-circle.js";
-import { loopFromStringifyable } from './loop-from-stringifyable.js';
-
-
-function fromStringifyable(
-        cpNodesStringifyable: CpNodeStringifyable) {
-
-    const { cpNodes: _cpNodes, loops: _loops } = cpNodesStringifyable;
-    const loops = _loops.map(loopFromStringifyable);
-    const loopsByIdx = new Map(loops.map(loop => [loop.idx, loop]));
-
-    //--------------------------------------------------------------------------
-    // First pass: build all CpNode objects with proper `cp`.
-    // Edges still hold number ids at this point.
-    //--------------------------------------------------------------------------
-    const cpNodes: CpNode[] = _cpNodes.map(cpNode_ => {
-        const { id, pointOnShape, isHoleClosing, isIntersection } = cpNode_;
-        const { circle, order, order2 } = pointOnShape;
-        const { curveIdx, loopIdx, p, pDd, t, isSource } = pointOnShape;
-
-        const curve = loopsByIdx.get(loopIdx)!.curves[curveIdx];
-
-        const pointOnShape_: PointOnShape = {
-            circle,
-            curve, p, pDd, t, isSource,
-            order, order2
-        };
-
-        return {
-            ...cpNode_,
-            id, isHoleClosing, isIntersection,
-            pointOnShape: pointOnShape_
-        } as CpNode;
-    });
-
-    //--------------------------------------------------------------------------
-    // Second pass: replace number id edges with real CpNode references.
-    //--------------------------------------------------------------------------
-    const nodeMap = new Map<number, CpNode>(cpNodes.map(n => [n.id, n]));
-
-    for (const cpNode of cpNodes) {
-        for (const edge of EDGES) {
-            const id = cpNode[edge] as unknown as number | undefined;
-            if (id === undefined) { continue; }
-
-            // @ts-ignore
-            cpNode[edge] = nodeMap.get(id)!;
-        }
-    }
-
-    //--------------------------------------------------------------------------
-    // Third pass: one shared `Circle` object per on-circle ring, as when the
-    // MAT was built (the JSON gave every contact point its own copy).
-    //--------------------------------------------------------------------------
-    const done = new Set<CpNode>();
-    for (const cpNode of cpNodes) {
-        if (done.has(cpNode)) { continue; }
-
-        const { circle } = cpNode.pointOnShape;
-        for (const cp of getAllOnCircle(cpNode)) {
-            done.add(cp);
-            (cp.pointOnShape as Mutable<PointOnShape>).circle = circle;
-        }
-    }
-
-    return cpNodes[0];
-}
-
-
-export { fromStringifyable }
+import type { PointOnShape } from "../../point-on-shape/point-on-shape.js";
+import type { CpNode } from "../cp-node.js";
+import type { CpNodeStringifyable } from "./cp-node-stringifyable.js";
+import type { Mutable } from "../../utils/mutable.js";
+import { EDGES } from "./cp-node-stringifyable.js";
+import { getAllOnCircle } from "../fs/get-all-on-circle.js";
+import { loopFromStringifyable } from './loop-from-stringifyable.js';
+
+
+function fromStringifyable(
+        cpNodesStringifyable: CpNodeStringifyable) {
+
+    const { cpNodes: _cpNodes, loops: _loops } = cpNodesStringifyable;
+    const loops = _loops.map(loopFromStringifyable);
+    const loopsByIdx = new Map(loops.map(loop => [loop.idx, loop]));
+
+    //--------------------------------------------------------------------------
+    // First pass: build all CpNode objects with proper `cp`.
+    // Edges still hold number ids at this point.
+    //--------------------------------------------------------------------------
+    const cpNodes: CpNode[] = _cpNodes.map(cpNode_ => {
+        const { id, pointOnShape, isHoleClosing, isIntersection } = cpNode_;
+        const { circle, order, order2 } = pointOnShape;
+        const { curveIdx, loopIdx, p, pDd, t, isSource } = pointOnShape;
+
+        const curve = loopsByIdx.get(loopIdx)!.curves[curveIdx];
+
+        const pointOnShape_: PointOnShape = {
+            circle,
+            curve, p, pDd, t, isSource,
+            order, order2
+        };
+
+        return {
+            ...cpNode_,
+            id, isHoleClosing, isIntersection,
+            pointOnShape: pointOnShape_
+        } as CpNode;
+    });
+
+    //--------------------------------------------------------------------------
+    // Second pass: replace number id edges with real CpNode references.
+    //--------------------------------------------------------------------------
+    const nodeMap = new Map<number, CpNode>(cpNodes.map(n => [n.id, n]));
+
+    for (const cpNode of cpNodes) {
+        for (const edge of EDGES) {
+            const id = cpNode[edge] as unknown as number | undefined;
+            if (id === undefined) { continue; }
+
+            // @ts-ignore
+            cpNode[edge] = nodeMap.get(id)!;
+        }
+    }
+
+    //--------------------------------------------------------------------------
+    // Third pass: one shared `Circle` object per on-circle ring, as when the
+    // MAT was built (the JSON gave every contact point its own copy).
+    //--------------------------------------------------------------------------
+    const done = new Set<CpNode>();
+    for (const cpNode of cpNodes) {
+        if (done.has(cpNode)) { continue; }
+
+        const { circle } = cpNode.pointOnShape;
+        for (const cp of getAllOnCircle(cpNode)) {
+            done.add(cp);
+            (cp.pointOnShape as Mutable<PointOnShape>).circle = circle;
+        }
+    }
+
+    return cpNodes[0];
+}
+
+
+export { fromStringifyable }

package/src/cp-node/stringification/to-stringifyable.ts

@@ -5,9 +5,9 @@ import { loopToStringifyable } from "./loop-to-stringifyable.js";
 
 
 /**
- * Returns a deep clone of this `CpNode`. Can be used to copy the MAT 
- * since cloning a single `CpNode` necessarily implies cloning all 
- * `CpNode`s on the same MAT tree.
+ * Returns a plain, acyclic representation of the entire MAT the given `CpNode`
+ * is part of (the `CpNode` edges replaced by ids and the boundary loops
+ * included) suitable for `JSON.stringify`; `fromStringifyable` reverses it.
  */
 function toStringifyable(
         cpNode: CpNode): CpNodeStringifyable {

package/src/debug/debug.ts

@@ -1,8 +1,10 @@
+import type { Curve } from 'flo-boolean';
+
 
 /** @internal */
 interface Debug {
     /** Generated by debug object for later inspection */
-    elems: {};
+    elems: Elems;
     timing: Timing;
 
     /**
@@ -14,6 +16,28 @@ interface Debug {
 }
 
 
+/**
+ * Elements generated during `findMats` for later inspection (only available
+ * if debug has been enabled via `enableDebugForMat(true)`).
+ *
+ * The arrays are reset at the start of each `findMats` call and accumulate
+ * over all MATs found in that call, one entry per boundary bezier curve in the
+ * order the curves are encountered.
+ */
+interface Elems {
+    /** The loose (axis-aligned) bounding box of each boundary bezier curve */
+    readonly looseBoundingBoxes: number[][][];
+    /** The tight (rotated) bounding box of each boundary bezier curve */
+    readonly tightBoundingBoxes: number[][][];
+    /** The bounding hull of each boundary bezier curve */
+    readonly boundingHulls: number[][][];
+    /** The curves whose end point forms a quite sharp corner with the next curve */
+    readonly sharpCorners: Curve[];
+    /** The curves whose end point forms a quite dull corner with the next curve */
+    readonly dullCorners: Curve[];
+}
+
+
 /** @internal */
 interface Timing {
     holeClosers: number;
@@ -35,18 +59,31 @@ interface Directives {
 }
 
 
+/** Returns a fresh (empty) set of debug `Elems`. */
+function createEmptyElems(): Elems {
+    return {
+        looseBoundingBoxes: [],
+        tightBoundingBoxes: [],
+        boundingHulls: [],
+        sharpCorners: [],
+        dullCorners: []
+    };
+}
+
+
 function enableDebugForMat(debugOn: boolean) {
     if (!debugOn) { 
-        (window as any)._debug_ = undefined; 
+        (globalThis as any)._debug_ = undefined; 
         return;
     }
 
-    let debug: Debug = (window as any)._debug_;
+    let debug: Debug = (globalThis as any)._debug_;
 
     debug = { 
         ...debug, 
         elems: { 
-            ...debug?.elems
+            ...debug?.elems,
+            ...createEmptyElems()
         },
         timing: {
             ...debug?.timing,
@@ -71,10 +108,9 @@ function enableDebugForMat(debugOn: boolean) {
         }
     };
 
-    (window as any)._debug_ = debug;
+    (globalThis as any)._debug_ = debug;
 }
 
 
-export type { Debug, Timing, Directives }
-export { enableDebugForMat }
-
+export type { Debug, Elems, Timing, Directives }
+export { enableDebugForMat, createEmptyElems }