flo-mat 4.1.4 → 5.0.1

package/src/floyd-warshall/get-graph.ts

@@ -1,59 +1,66 @@
 import type { CpNode } from "../cp-node/cp-node.js";
-import { getAllOnCircle } from "../cp-node/fs/get-all-on-circle.js";
+import type { Circle } from "../geometry/circle.js";
 import { getMatDistanceToNext$ } from "../cp-node/fs/get-distance-to-next.js";
-import { isOnSameCircle } from "../cp-node/fs/is-on-same-circle.js";
 import { isVertexSpecial } from "../cp-node/fs/is-vertex-special.js";
-import { getHoleCloserPairs } from "./get-hole-closer-pairs.js";
 
 
+/**
+ * Returns the adjacency matrix (MAT edge lengths, `Infinity` if not adjacent)
+ * of the given special vertices (leaves, 3-prongs, ...) seen as the vertices of
+ * a graph with the MAT branches between them as edges.
+ *
+ * * for each vertex every MAT edge leaving it is walked once, up to the next
+ *   special vertex; if that vertex is one of the given ones the walked length
+ *   is its distance (the minimum over all such walks if there are several)
+ *
+ * @param specialVertices the special `CpNode`s (one per vertex)
+ */
 function getGraph(
-        specialVertices: CpNode[],
-        holeClosers: CpNode[]) {
-
-    const pairs = getHoleCloserPairs(holeClosers);
+        specialVertices: CpNode[]) {
 
     const V = specialVertices.length;
 
+    // the column of each given vertex, identified by its circle (all `CpNode`s
+    // on a vertex share the same `Circle` object)
+    const columnOf = new Map<Circle, number>(
+        specialVertices.map((cpNode, j) => [cpNode.pointOnShape.circle, j])
+    );
+
     const graph: number[][] = [];
     for (let i=0; i<V; i++) {
         const cpNodeA = specialVertices[i];
 
-        const row: number[] = [];
-        for (let j=0; j<V; j++) {
-            const cpNodeB = specialVertices[j];
-            if (i === j) {
-                row.push(0);
-                continue;
-            }
-
-            let minD = Infinity;
-            for (const toChild of getAllOnCircle(cpNodeA)) {
-                let d = getMatDistanceToNext$(toChild);
-                let child = toChild.next;
-                while (true) {
-                    if (isOnSameCircle(child, cpNodeB)) {
-                        break;  // Found path from A to B
-                    }
-                    if (child.isHoleClosing) {
-                        // Hole closer found - don't go around loop 
-                        child = getHoleCloserNext(pairs, child);
-                        continue;
-                    }
-                    if (isVertexSpecial(child)) {
-                        // we only find the immediate next special ones
-                        d = Infinity;
-                        break;  // Next special vertex found but it's not B
-                    }
-
-                    d += getMatDistanceToNext$(child);
-                    child = child.next;
+        const row: number[] = new Array(V).fill(Infinity);
+        row[i] = 0;
+
+        // walk each edge leaving the vertex up to the next special vertex
+        let toChild = cpNodeA;
+        do {
+            let d = getMatDistanceToNext$(toChild);
+            let child = toChild.next;
+            while (true) {
+                const j = columnOf.get(child.pointOnShape.circle);
+                if (j !== undefined) {
+                    // Found a path from A to one of the given vertices
+                    if (j !== i && d < row[j]) { row[j] = d; }
+                    break;
+                }
+                if (child.isHoleClosing) {
+                    // Hole closer found - skip it (don't go around loop)
+                    child = child.holeCloserTwin!.next;
+                    continue;
+                }
+                if (isVertexSpecial(child)) {
+                    // we only find the immediate next special ones
+                    break;  // Next special vertex found but it's not a given one
                 }
 
-                if (d < minD) { minD = d; }
+                d += getMatDistanceToNext$(child);
+                child = child.next;
             }
 
-            row.push(minD);
-        }
+            toChild = toChild.nextOnCircle;
+        } while (toChild !== cpNodeA);
 
         graph.push(row);
     }
@@ -62,12 +69,4 @@ function getGraph(
 }
 
 
-function getHoleCloserNext(
-        pairs: Map<CpNode,CpNode>,
-        holeCloser: CpNode) {
-
-    return pairs.get(holeCloser)!.next;
-}
-
-
 export { getGraph }

package/src/geometry/get-bounding-box-.ts

@@ -1,8 +1,11 @@
-import { getBoundingBox } from "flo-bezier3";
+import { getBoundingBox, getBoundingBoxTight } from "flo-bezier3";
 import { memoize } from "flo-memoize";
 
 
+/** The (loose, axis-aligned) bounding box of a bezier curve - memoized on its control points. */
 const getBoundingBox$ = memoize(getBoundingBox);
+/** The tight (rotated) bounding box of a bezier curve - memoized on its control points. */
+const getBoundingBoxTight$ = memoize(getBoundingBoxTight);
 
 
-export { getBoundingBox$ }
+export { getBoundingBox$, getBoundingBoxTight$ }

package/src/geometry/get-closest-square-distance-to-rect.ts

@@ -1,7 +1,7 @@
-import { squaredDistanceBetween } from 'flo-vector2d';
-
-
 /**
+ * Returns the closest squared distance from the point `p` to the given 
+ * axis-aligned box `[[minX, minY], [maxX, maxY]]`, i.e. `0` if `p` is inside.
+ * 
  * @internal
  */
 function getClosestSquareDistanceToRect(
@@ -18,17 +18,17 @@ function getClosestSquareDistanceToRect(
 
     if (xp < x0) {
         if (yp < y0) {
-            return squaredDistanceBetween(box[0], p);
+            return (x0 - xp)**2 + (y0 - yp)**2;
         } else if (yp > y1) {
-            return squaredDistanceBetween([x0,y1], p);
+            return (x0 - xp)**2 + (yp - y1)**2;
         } else {
             return (x0 - xp)**2;
         }
     } else if (xp > x1) {
         if (yp < y0) {
-            return squaredDistanceBetween([x1,y0], p);
+            return (xp - x1)**2 + (y0 - yp)**2;
         } else if (yp > y1) {
-            return squaredDistanceBetween(box[1], p);
+            return (xp - x1)**2 + (yp - y1)**2;
         } else {
             return (xp - x1)**2;
         }

package/src/geometry/get-closest-squared-distance-to-rotated-rect.ts

@@ -1,29 +1,31 @@
-import { 
-    squaredDistanceBetweenPointAndLineSegment, squaredDistanceBetween 
-} from 'flo-vector2d';
+import { squaredDistanceBetweenPointAndLineSegment, squaredDistanceBetween } from 'flo-vector2d';
+
+const { min } = Math;
 
 
 /**
+ * Returns the closest squared distance from the point `p` to the given
+ * (rotated) rectangle given by its 4 corners in order, i.e. `0` if `p` is
+ * inside the rectangle.
+ *
  * @internal
  */
 function getClosestSquaredDistanceToRotatedRect(ps: number[][], p: number[]) {
-    const ds = [0,1,2,3]
-    .map(i => squaredDistanceBetweenPointAndLineSegment(
-            p, 
-            [ps[i], ps[(i + 1) % 4]]
-        )
-    );
-    
+    const d0 = squaredDistanceBetweenPointAndLineSegment(p, [ps[0], ps[1]]);
+    const d1 = squaredDistanceBetweenPointAndLineSegment(p, [ps[1], ps[2]]);
+    const d2 = squaredDistanceBetweenPointAndLineSegment(p, [ps[2], ps[3]]);
+    const d3 = squaredDistanceBetweenPointAndLineSegment(p, [ps[3], ps[0]]);
+
     const width  = squaredDistanceBetween(ps[0], ps[1]);
     const height = squaredDistanceBetween(ps[0], ps[3]);
 
-    if (ds[0] <= height && ds[2] <= height && 
-        ds[1] <= width  && ds[3] <= width) {
+    if (d0 <= height && d2 <= height &&
+        d1 <= width  && d3 <= width) {
 
         return 0; // Inside rotated rect
     }
 
-    return Math.min(...ds);
+    return min(d0, d1, d2, d3);
 }
 
 

package/src/get-medial-points/double-double/dd-get-medial-point-coeffs-bez3.ts

@@ -1,7 +1,6 @@
 import { toPowerBasisDd } from 'flo-bezier3';
-import { twoDiff, ddMultDouble2, ddAddDd, ddMultDd, ddNegativeOf, ddMultByNeg2, ddMultBy2, ddDiffDouble } from 'double-double';
+import { ddMultDouble2, ddAddDd, ddMultDd, ddNegativeOf, ddMultByNeg2, ddMultBy2, ddDiffDouble } from 'double-double';
 
-const td = twoDiff;
 const qmd = ddMultDouble2;
 const qaq = ddAddDd;
 const qmq = ddMultDd;

package/src/index.ts

@@ -8,7 +8,7 @@ export type { PointOnShape } from './point-on-shape/point-on-shape.js';
 export type { Circle } from './geometry/circle.js';
 export type { CurvePiece } from './mat/curve-piece.js';
 export type { Timing } from './debug/debug.js';
-export type { Debug } from './debug/debug.js';
+export type { Debug, Elems } from './debug/debug.js';
 export type { MatOptions } from './find-mat/mat-options.js';
 
 export { floydWarshall } from './floyd-warshall/floyd-warshall.js';
@@ -35,7 +35,8 @@ export { getSharpCornersOnLoop } from './find-mat/get-sharp-corners.js';
 export { getFor2ProngsOnLoop } from './find-mat/get-for-2-prongs-on-loop.js';
 export { getPotentialClosestPointsOnCurveCertified } from './closest-boundary-point/get-potential-closest-points-on-curve-certified.js';
 export { getCloseBoundaryPointsCertified } from './closest-boundary-point/get-close-boundary-points-certified.js';
-export { getPartialMeta } from './find-mat/get-meta.js';
+export { cloneMat } from './mat/clone-mat.js';
+export { cloneMeta } from './mat/clone-meta.js';
 export { findAndAddHoleClosing2Prongs } from './find-2-prong/find-and-add-hole-closing-2-prongs.js';
 export { reconstructFromMats } from './reconstruct-from-mat/reconstruct-from-mat.js';
 export { getOsculatingCircle } from './point-on-shape/get-osculating-circle.js';

package/src/mat/clone-mat.ts

@@ -3,14 +3,20 @@ import { clone } from "../cp-node/fs/clone.js";
 import { cloneMeta } from "./clone-meta.js";
 
 
+/**
+ * Returns a deep clone of the given `Mat` (its `CpNode`s are cloned and its
+ * `meta` rebuilt for the clones; the boundary loops are shared).
+ *
+ * @param mat the `Mat` to clone
+ */
 function cloneMat(
         mat: Mat): Mat {
 
-    const { cpNode, meta } = mat;
+    const cpNode = clone(mat.cpNode);
 
     return {
-        cpNode: clone(cpNode),
-        meta: cloneMeta(cpNode, meta)
+        cpNode,
+        meta: cloneMeta(cpNode, mat.meta)
     }
 }
 

package/src/mat/clone-meta.ts

@@ -3,6 +3,14 @@ import type { CpNode } from '../cp-node/cp-node.js';
 import { createNewCpTrees } from './create-new-cp-trees.js';
 
 
+/**
+ * Returns a clone of the given `MatMeta` for the given (already cloned)
+ * `CpNode`, i.e. with `cpTrees` rebuilt from the clone and a fresh
+ * `lastInsertId`.
+ *
+ * @param cpNode the (cloned) `CpNode` the meta is for
+ * @param meta the `MatMeta` to clone
+ */
 function cloneMeta(
         cpNode: CpNode,
         meta: MatMeta): MatMeta {

package/src/mat/get-boundary-piece-beziers.ts

@@ -6,29 +6,27 @@ import { comparePoss } from '../point-on-shape/compare-poss.js';
 
 /**
  * Returns the ordered bezier pieces between the two given `CpNode`s.
- * 
- * @param cpNodes - An ordered pair that represents the start and end points of 
+ *
+ * * NOTE: an earlier version 'stitched' pieces together at hole closers and
+ * loop endpoints to avoid duplicate antipodal points later; this was removed
+ * (duplicates are now checked for in `find2Prong`) - see the git history
+ * before 2026-10 for that code.
+ *
+ * @param cpNodes - An ordered pair that represents the start and end points of
  * the boundary piece
- * 
+ *
  * @internal
  */
 function getBoundaryPieceBeziers(
         cpNodes: [CpNode,CpNode]): CurvePiece[] {
 
-    let cpThis = cpNodes[0]; 
+    let cpThis = cpNodes[0];
     const cpEnd  = cpNodes[1];
-    
-    const curvePieces: CurvePiece[] = [];
 
-    // NOTE❗ Currently removed stichables; we're just checking for duplicates
-    // later in `find2Prong`; KEEP for possible future use.
-    // We have to stich curves together if they're at a hole closer or at the
-    // endpoints of a loop to avoid duplicates later within the code; the map
-    // is from curves
-    // const stichables: Map<Curve, number[]> = new Map();
+    const curvePieces: CurvePiece[] = [];
 
     // As opposed to going around the circle and taking the last exit
-    let goStraight = true; 
+    let goStraight = true;
     do {
         const posThis = cpThis     .pointOnShape;
         const posNext = cpThis.next.pointOnShape;
@@ -37,31 +35,6 @@ function getBoundaryPieceBeziers(
 
         if (!goStraight) {
             goStraight = true;
-            // NOTE❗ Currently removed stichables; we're just checking for duplicates
-            // later in `find2Prong`; KEEP for possible future use.
-            // const { loop: loopThis } = curveThis;
-            // const cpPrevOnCircle = cpThis.prevOnCircle;
-            // const curvePrevOnCircle = cpPrevOnCircle.pointOnShape.curve;
-            // const { loop: loopNext } = cpPrevOnCircle.pointOnShape.curve;
-            
-
-            // if (loopThis !== loopNext) {
-            //     let idxsThis = stichables.get(curveThis);
-            //     if (idxsThis === undefined) {
-            //         idxsThis = [];
-            //         stichables.set(curveThis, idxsThis);
-            //     }
-            //     idxsThis.push(curvePieces.length - 1);  // last `CurvePiece` idx
-
-            //     let idxsNext = stichables.get(curvePrevOnCircle);
-            //     if (idxsNext === undefined) {
-            //         idxsNext = [];
-            //         stichables.set(curvePrevOnCircle, idxsNext);
-            //     }
-            //     idxsNext.push(curvePieces.length);  // upcoming `CurvePiece` idx
-            // }
-
-            // cpThis = cpPrevOnCircle;  // take last exit
             cpThis = cpThis.prevOnCircle;  // take last exit
             continue;
         }
@@ -93,91 +66,17 @@ function getBoundaryPieceBeziers(
         // so split at t = 1.
 
         if (curveThis.loop === curveNext.loop) {
-            const initialCurvePiece = {
+            curvePieces.push({
                 curve: curveThis, ts: [posThis.t, 1]
-            };
-            curvePieces.push(initialCurvePiece);
+            });
 
             // Fill in any curves skipped between the two points.
             addSkippedBeziers(curvePieces, curveThis, curveNext, posNext.t);
-
-            // NOTE❗ Currently removed stichables; we're just checking for duplicates
-            // later in `find2Prong`; KEEP for possible future use.
-            // const finalCurvePiece = curvePieces[curvePieces.length - 1];
-            // if (initialCurvePiece.curve === finalCurvePiece!.curve) {
-            //     const { ts: tsS } = initialCurvePiece;
-            //     const { ts: tsE } = finalCurvePiece!;
-
-            //     // If it is a closed loop we must join the endpoints to prevent duplicate
-            //     // antipodal points later
-            //     if (tsS[0] === tsE[1]) {
-            //         initialCurvePiece.ts[0] = tsE[0];
-
-            //         if (curvePieces.length > 1) {
-            //             curvePieces.pop();
-            //         }
-            //         // console.log('was inner closed loop')
-            //     }
-            // }
         }
 
         cpThis = cpThis.next;
     } while (cpThis !== cpEnd);
 
-    // NOTE❗ Currently removed stichables; we're just checking for duplicates
-    // later in `find2Prong`; KEEP for possible future use.
-    // if (stichables.size > 0) {
-    //     for (const [loop,idxs] of stichables.entries()) {
-    //         if (idxs.length === 2) {
-    //             const curvePieceS = curvePieces[idxs[0]]!;
-    //             const curvePieceE = curvePieces[idxs[1]]!;
-
-    //             if (curvePieceS === undefined || curvePieceE === undefined) {
-    //                 console.log(curvePieceS);
-    //                 console.log(curvePieceE);
-    //                 continue;
-    //             }
-
-    //             const { curve: curveS, ts: tsS } = curvePieceS;
-    //             const { curve: curveE, ts: tsE } = curvePieceE;
-    //             if (curveS !== curveE) {
-    //                 continue;
-    //             }
-
-    //             // If it is a closed loop we must join the endpoints to prevent duplicate
-    //             // antipodal points later
-    //             if (tsS[0] === tsE[1]) {
-    //                 curvePieceS.ts[0] = tsE[0];
-    //                 // console.log('was closed loop 1')
-    //             } else if (tsE[0] === tsS[1]) {
-    //                 curvePieceS.ts[1] = tsE[1];
-    //                 // console.log('was closed loop 2')
-    //             }
-    //             if (idxs[0] !== idxs[1]) {
-    //                 curvePieces[idxs[1]] = undefined;
-    //             }
-    //         }
-    //     }
-    // }
-
-    // NOTE❗ The below endcurve check is not enough for specific cases involving
-    // multiple hole closers; KEEP for now but must use stichables instead
-    // if (curvePieces[0]!.curve === curvePieces[curvePieces.length - 1]!.curve) {
-    //     const { ts: tsS } = curvePieces[0]!;
-    //     const { ts: tsE } = curvePieces[curvePieces.length - 1]!;
-
-    //     // If it is a closed loop we must join the endpoints to prevent duplicate
-    //     // antipodal points later
-    //     if (tsS[0] === tsE[1]) {
-    //         curvePieces[0]!.ts[0] = tsE[0];
-
-    //         if (curvePieces.length > 1) {
-    //             curvePieces.pop();
-    //         }
-    //         // console.log('was closed loop')
-    //     }
-    // }
-
     return curvePieces;
 }
 
@@ -187,9 +86,9 @@ function getBoundaryPieceBeziers(
  * Adds pieces of skipped beziers
  */
 function addSkippedBeziers(
-        curvePieces: (CurvePiece | undefined)[], 
-        curveStart: Curve, 
-        curveEnd: Curve, 
+        curvePieces: CurvePiece[],
+        curveStart: Curve,
+        curveEnd: Curve,
         t1: number) {
 
     // Walk forward through the loop until the end curve is reached.

package/src/mat/get-closeby-cp-if-exist.ts

@@ -5,10 +5,12 @@ import type { MatMeta } from './mat-meta.js';
 import { distanceBetween, toUnitVector, fromTo, dot } from 'flo-vector2d';
 import { getCpNodeNeighbors } from './get-cp-node-neighbors.js';
 
+const { cos, PI: π } = Math;
+
 
 /** @internal */
 const DEGREES = 1;
-const ANGLE_THRESHOLD = Math.cos(DEGREES * (Math.PI / 180));
+const ANGLE_THRESHOLD = cos(DEGREES * (π/180));
 
 
 /**

package/src/mat/get-largest-3-prong.ts

@@ -1,21 +1,24 @@
 import type { CpNode } from '../cp-node/cp-node.js';
 import { getAllOnLoop } from '../cp-node/fs/get-all-on-loop.js';
 import { getRealProngCount } from '../cp-node/fs/get-real-prong-count.js';
+import { getLargestOf } from './get-largest-vertex.js';
 
 
+/**
+ * Returns the `CpNode` on a 3-prong (or higher) MAT vertex with the largest
+ * maximal disk radius, or `undefined` if there is none.
+ *
+ * @param cpNode any `CpNode` on the MAT
+ */
 function getLargest3Prong(
-        cpNode: CpNode) {
+        cpNode: CpNode): CpNode | undefined {
 
     const cpNodes = getAllOnLoop(cpNode)
         .filter(cpNode => getRealProngCount(cpNode) >= 3);
 
     if (cpNodes.length === 0) { return undefined; }
 
-    return cpNodes.reduce(function(maxCpNode: CpNode, cpNode: CpNode) {
-        return maxCpNode.pointOnShape.circle.radius >= cpNode.pointOnShape.circle.radius
-            ? maxCpNode
-            : cpNode
-    }, cpNodes[0]);
+    return getLargestOf(cpNodes);
 }
 
 

package/src/mat/get-largest-vertex.ts

@@ -2,17 +2,33 @@ import type { CpNode } from '../cp-node/cp-node.js';
 import { getAllOnLoop } from '../cp-node/fs/get-all-on-loop.js';
 
 
-function getLargestVertex(
-        cpNode: CpNode) {
-
-    const cpNodes = getAllOnLoop(cpNode);
-
-    return cpNodes.reduce(function(maxCpNode: CpNode, cpNode: CpNode) {
-        return maxCpNode.pointOnShape.circle.radius >= cpNode.pointOnShape.circle.radius
+/**
+ * Returns the `CpNode` (of the given ones) with the largest maximal disk
+ * radius (the first one in case of a tie).
+ *
+ * @param cpNodes a non-empty array of `CpNode`s
+ *
+ * @internal
+ */
+function getLargestOf(cpNodes: CpNode[]): CpNode {
+    return cpNodes.reduce((maxCpNode, cpNode) =>
+        maxCpNode.pointOnShape.circle.radius >= cpNode.pointOnShape.circle.radius
             ? maxCpNode
             : cpNode
-    }, cpNodes[0]);
+    );
+}
+
+
+/**
+ * Returns the `CpNode` on the MAT with the largest maximal disk radius.
+ *
+ * @param cpNode any `CpNode` on the MAT
+ */
+function getLargestVertex(
+        cpNode: CpNode): CpNode {
+
+    return getLargestOf(getAllOnLoop(cpNode));
 }
 
 
-export { getLargestVertex }
+export { getLargestVertex, getLargestOf }