flo-mat 4.1.5 → 5.0.2

package/src/mat/simplify-mat.ts

@@ -1,116 +1,254 @@
-import type { Mat } from './mat.js';
-import type { CpNode } from '../cp-node/cp-node.js';
-import { hausdorffDistanceOneSided } from 'flo-bezier3';
-import { removeVertex } from '../vertex/remove-vertex.js';
-import { getBranches } from './get-branches.js';
-import { getMatCurveToNext } from '../cp-node/fs/get-mat-curve-to-next.js';
-import { getMatCurveBetween } from '../cp-node/fs/get-mat-curve-between.js';
-import { createNewCpTrees } from './create-new-cp-trees.js';
-import { clone } from '../cp-node/fs/clone.js';
-import { findFirst } from '../cp-node/fs/find-first.js';
-import { isTerminating } from '../cp-node/fs/is-terminating.js';
-import { isVertex } from '../cp-node/fs/is-vertex.js';
-import { getProngCount } from '../cp-node/fs/get-prong-count.js';
-
-const { max } = Math;
-
-
-// FUTURE could be made faster by binary "search" on hausdorff curves?
-/**
- * Returns a new simplified MAT of the given one by replacing the piecewise
- * quad beziers composing the MAT with fewer ones to within a given tolerance.
- * 
- * @param cpNode a representation of the MAT
- * @param anlgeTolerance tolerance given as the degrees difference of the unit
- * direction vectors at the interface between curves. A tolerance of zero means
- * perfect smoothness is required - defaults to 15
- * @param hausdorffTolerance the approximate maximum Hausdorff Distance tolerance -
- * defaults to `2**-3`
- * @param maxIterations the max iterations of the Hausdorff Distance calculation,
- * defaults to `50`
- */
-function simplifyMat(
-        mat: Mat,
-        hausdorffTolerance = 2**-3,
-        maxIterations = 50): Mat {
-
-    let cpNode = clone(mat.cpNode);
-
-    // Start from a leaf
-    while (!isTerminating(cpNode)) { cpNode = cpNode.next; }
-
-    const branches = getBranches(cpNode);
-
-    const canDeletes: Set<CpNode> = new Set();
-    for (let k=0; k<branches.length; k++) {
-        const branch = branches[k];
-
-        // Try to remove some
-        let j = 0;
-        while (j < branch.length) {
-            const i = j;
-            while (true) {
-                j++;
-
-                if (j === branch.length) { break; }
-
-                const hd = getTotalHausdorffDistance(i, j, branch, maxIterations);
-
-                if (hd > hausdorffTolerance) {
-                    break;
-                } else {
-                    canDeletes.add(branch[j]);
-                }
-            }
-
-            if (i+1 === j) {
-                continue;  // no simplification occured
-            }
-        }
-    }
-
-    // cpNode = findFirst(cpNode_ => isTerminating(cpNode_) ? cpNode_ : undefined, cpNode)!;
-    cpNode = findFirst(isTerminating, cpNode)!;
-
-    for (const cpNode of canDeletes) {
-        if (!isVertex(cpNode =>
-                (getProngCount(cpNode) !== 2) &&
-                !cpNode.isHoleClosing
-            )(cpNode)) {
-
-            removeVertex(cpNode, mat.meta);
-        }
-    }
-
-
-    return {
-        cpNode,
-        meta: {
-            ...mat.meta,
-            cpTrees: createNewCpTrees(cpNode)
-        }
-    }
-}
-
-
-function getTotalHausdorffDistance(
-        i: number, 
-        j: number, 
-        branch: CpNode[],
-        hausdorffSpacing: number) {
-
-    const hds: number[] = [];
-    const longCurve = getMatCurveBetween(branch[i], branch[j].next);
-    for (; i<j+1; i++) {
-        hds.push(hausdorffDistanceOneSided(
-            getMatCurveToNext(branch[i]),
-            longCurve,
-            hausdorffSpacing
-        ));
-    }
-
-    return max(...hds);
-}
-
-
-export { simplifyMat }
+import type { Mat } from './mat.js';
+import type { MatMeta } from './mat-meta.js';
+import type { CpNode } from '../cp-node/cp-node.js';
+import { evalDeCasteljau } from 'flo-bezier3';
+import { removeVertex } from '../vertex/remove-vertex.js';
+import { getBranches } from './get-branches.js';
+import { getMatCurveToNext } from '../cp-node/fs/get-mat-curve-to-next.js';
+import { getMatCurveBetween } from '../cp-node/fs/get-mat-curve-between.js';
+import { createNewCpTrees } from './create-new-cp-trees.js';
+import { clone } from '../cp-node/fs/clone.js';
+import { isTerminating } from '../cp-node/fs/is-terminating.js';
+import { isSpecial } from '../cp-node/fs/is-special.js';
+import { getProngCount } from '../cp-node/fs/get-prong-count.js';
+import { distanceToCurves, hausdorffDistanceOneSidedExceeds } from './hausdorff-distance-one-sided-exceeds.js';
+
+const { abs } = Math;
+
+
+/**
+ * Spans of at least this many edges whose worst vertex lies within
+ * `END_FRACTION` of either end are additionally split at their middle - this
+ * guards against the degenerate case where each split peels off only a few
+ * edges at an end (making the recursion depth, and the total work, quadratic
+ * in the branch length) at the cost of at most one extra curve per occurrence.
+ *
+ * @internal
+ */
+const MIN_EDGES_FOR_BALANCED_SPLIT = 32;
+/** @internal */
+const END_FRACTION = 1/8;
+
+
+/**
+ * Returns a new simplified MAT of the given one by replacing the piecewise
+ * quad beziers composing the MAT with fewer ones to within a given tolerance.
+ *
+ * * the vertices of the simplified MAT are a subset of those of the given one
+ * (so the endpoints of each new curve are endpoints of existing ones) and all
+ * 'special' vertices (leaves, 3-prongs and higher, hole-closers) are kept
+ * * each branch is simplified Douglas-Peucker style: the single curve from the
+ * start to the end of a span of edges is tried and, if some edge deviates from
+ * it by more than the tolerance, the span is split at the vertex of worst
+ * deviation and both halves are tried in turn; this is `O(n log n)` (in the
+ * number of edges `n` of a branch) Hausdorff distance checks as opposed to the
+ * `O(n²)` of greedily extending spans one vertex at a time
+ * * the deviation of an edge from the single curve is checked first by cheap
+ * sampled *lower* bounds (which already find most splits) and only then by
+ * the certified `hausdorffDistanceOneSidedExceeds`
+ * * the tolerance is a certified upper bound on the one-sided Hausdorff
+ * distance from the original MAT curves to the simplified ones (up to
+ * floating point roundoff)
+ *
+ * @param mat the MAT to simplify (it is not modified)
+ * @param hausdorffTolerance the maximum one-sided Hausdorff distance (in
+ * coordinate units) from the original to the simplified MAT - defaults to
+ * `2**-3`
+ * @param maxIterations the max bisections of each Hausdorff distance check
+ * (see `hausdorffDistanceOneSidedExceeds`) after which the check conservatively
+ * fails (so that the span is split rather than accepted) - defaults to `1000`;
+ * lower values trade simplification quality for a bound on the time spent on
+ * curves that are only just within tolerance
+ */
+function simplifyMat(
+        mat: Mat,
+        hausdorffTolerance = 2**-3,
+        maxIterations = 1000): Mat {
+
+    let cpNode = clone(mat.cpNode);
+    // The clone gets its own `cpTrees` (removing vertices below must not
+    // touch the trees of the given `mat`) - they are kept up to date by
+    // `removeVertex`.
+    const meta: MatMeta = { ...mat.meta, cpTrees: createNewCpTrees(cpNode) };
+
+    // Start from a leaf (which is never removed so it can be returned)
+    while (!isTerminating(cpNode)) { cpNode = cpNode.next; }
+
+    const branches = getBranches(cpNode);
+
+    const toRemove: CpNode[] = [];
+    for (let k=0; k<branches.length; k++) {
+        simplifyBranch(branches[k], hausdorffTolerance, maxIterations, toRemove);
+    }
+
+    for (const cpNode of toRemove) {
+        removeVertex(cpNode, meta);
+    }
+
+    return { cpNode, meta };
+}
+
+
+/**
+ * Simplifies the given branch by adding the `CpNode`s of the vertices that
+ * can be removed to `toRemove`.
+ *
+ * * edge `k` of the branch runs from `branch[k]` to `branch[k].next`; vertex
+ * `k` (for `0 < k < branch.length`) is the interior vertex `branch[k]` between
+ * edges `k-1` and `k`
+ * * a span of edges `i..j` is simplified to the single curve from the start
+ * of edge `i` to the end of edge `j`, removing the interior vertices `i+1..j`
+ *
+ * @internal
+ */
+function simplifyBranch(
+        branch: CpNode[],
+        tolerance: number,
+        maxIterations: number,
+        toRemove: CpNode[]): void {
+
+    const n = branch.length;  // the number of edges
+    if (n < 2) { return; }
+
+    // the MAT curves of the edges of the branch - computed once per branch
+    const curves = branch.map(getMatCurveToNext);
+    const vertexPoints = branch.map(cpNode => cpNode.pointOnShape.circle.center);
+
+    // The spans still to be processed; interior vertices that cannot be
+    // removed must be kept so the branch is pre-split there: the 'special'
+    // ones (e.g. hole-closers) and those whose circle carries more than 2
+    // `CpNode`s (e.g. a 2-prong having a terminating sharp corner contact,
+    // which `getBranch` passes through but `removeVertex` cannot remove).
+    const spans: [number,number][] = [];
+    let a = 0;
+    for (let k=1; k<n; k++) {
+        if (isSpecial(branch[k]) || getProngCount(branch[k]) !== 2) {
+            spans.push([a, k-1]);
+            a = k;
+        }
+    }
+    spans.push([a, n-1]);
+
+    while (spans.length > 0) {
+        const [i, j] = spans.pop()!;
+        if (j <= i) { continue; }  // a single edge - nothing to remove
+
+        const longCurves = getMatCurveBetween(branch[i], branch[j].next);
+
+        //------------------------------------------------------------------
+        // 1. Cheap pass: sampled lower bounds on the deviation of each edge -
+        //    the interior vertices and the piece midpoints.
+        //------------------------------------------------------------------
+        let worstD = 0;
+        let worstV = -1;
+        for (let k=i; k<=j; k++) {
+            if (k > i) {
+                const d = distanceToCurves(vertexPoints[k], longCurves);
+                if (d > worstD) { worstD = d; worstV = k; }
+            }
+            const pieces = curves[k];
+            for (let m=0; m<pieces.length; m++) {
+                const d = distanceToCurves(evalDeCasteljau(pieces[m], 0.5), longCurves);
+                if (d > worstD) {
+                    worstD = d;
+                    worstV = getSplitVertexForEdge(i, j, k, m, pieces.length);
+                }
+            }
+        }
+
+        if (worstD > tolerance) {
+            split(spans, i, j, worstV);
+            continue;
+        }
+
+        //------------------------------------------------------------------
+        // 2. Certified pass - split at the first edge found to exceed the
+        //    tolerance.
+        //------------------------------------------------------------------
+        let splitV = -1;
+        outer: for (let k=i; k<=j; k++) {
+            const pieces = curves[k];
+            for (let m=0; m<pieces.length; m++) {
+                if (hausdorffDistanceOneSidedExceeds(pieces[m], longCurves, tolerance, maxIterations)) {
+                    splitV = getSplitVertexForEdge(i, j, k, m, pieces.length);
+                    break outer;
+                }
+            }
+        }
+
+        if (splitV !== -1) {
+            split(spans, i, j, splitV);
+            continue;
+        }
+
+        //------------------------------------------------------------------
+        // 3. Accept the span.
+        //------------------------------------------------------------------
+        for (let k=i+1; k<=j; k++) {
+            toRemove.push(branch[k]);
+        }
+    }
+}
+
+
+/**
+ * Returns the vertex (in `(i,j]`) at which to split the span of edges `i..j`
+ * given that piece `m` (of `numPieces`) of edge `k` deviates too much: one of
+ * the edge's two endpoint vertices - the one on the side of the piece if the
+ * edge has 2 pieces, else the one nearer the middle of the span (for a more
+ * balanced recursion).
+ *
+ * @internal
+ */
+function getSplitVertexForEdge(
+        i: number,
+        j: number,
+        k: number,
+        m: number,
+        numPieces: number): number {
+
+    const canUseStart = k > i;
+    const canUseEnd = k + 1 <= j;
+
+    if (!canUseStart) { return k + 1; }
+    if (!canUseEnd) { return k; }
+
+    if (numPieces === 2) {
+        return m === 0 ? k : k + 1;
+    }
+
+    const mid = (i + 1 + j)/2;  // middle of the interior vertices `i+1..j`
+
+    return abs(k - mid) <= abs(k + 1 - mid) ? k : k + 1;
+}
+
+
+/**
+ * Splits the span of edges `i..j` at the vertex `v` (in `(i,j]`) and pushes
+ * the resulting spans (for very long spans with `v` near an end also split at
+ * the middle - see `MIN_EDGES_FOR_BALANCED_SPLIT`).
+ *
+ * @internal
+ */
+function split(
+        spans: [number,number][],
+        i: number,
+        j: number,
+        v: number): void {
+
+    const numEdges = j - i + 1;
+    if (numEdges >= MIN_EDGES_FOR_BALANCED_SPLIT) {
+        const margin = numEdges*END_FRACTION;
+        if (v - i < margin || j + 1 - v < margin) {
+            const vMid = (i + j + 1) >>> 1;  // an interior vertex near the middle
+            const [v1, v2] = v < vMid ? [v, vMid] : [vMid, v];
+            spans.push([v2, j], [v1, v2-1], [i, v1-1]);
+            return;
+        }
+    }
+
+    spans.push([v, j], [i, v-1]);
+}
+
+
+export { simplifyMat }

package/src/mat/trim-mat.ts

@@ -7,14 +7,16 @@ import { clone } from '../cp-node/fs/clone.js';
 /**
  * Trims the given Medial Axis Transform so that only cycles remain. Similar to
  * toScaleAxis(mat, Infinity).
- * 
- * @param mat The MAT to trim.
+ *
+ * * returns `undefined` if the MAT has no cycles (i.e. the shape has no holes)
+ *
+ * @param mat The MAT to trim (it is not modified).
  */
-function trimMat(mat: Mat): Mat {
+function trimMat(mat: Mat): Mat | undefined {
     // FUTURE - clone entire `Mat` instead (the function already exists)
     const cpNode = cullNonCycles(clone(mat.cpNode));
 
-    if (!cpNode) { return undefined!; }
+    if (!cpNode) { return undefined; }
 
     return {
         cpNode,

package/src/point-on-shape/get-boundary-tangent-line.ts

@@ -0,0 +1,36 @@
+import type { PointOnShape } from './point-on-shape.js';
+import { tangent } from 'flo-bezier3';
+import { translate } from 'flo-vector2d';
+
+
+/**
+ * Returns a line segment starting at the given point on the shape boundary and
+ * being tangent to the boundary at that point.
+ * 
+ * * the returned line is of the form `[p, p + tangent]` where `p` is the
+ * point on the shape (the tangent is not normalized)
+ * * if the point falls on the boundary between two curves then the curve
+ * the point starts (if `fromElseTo` is `true`) or ends (if `fromElseTo` is 
+ * `false`) is used
+ * 
+ * @param pos the point on the shape
+ * @param fromElseTo `true` if the tangent is to be taken as leaving the point,
+ * `false` if it is to be taken as arriving at the point
+ * 
+ * @internal
+ */
+function getBoundaryTangentLine(
+        pos: PointOnShape,
+        fromElseTo: boolean): number[][] {
+
+    let { curve, t } = pos;
+    const { p } = pos;
+
+    if (fromElseTo && t === 1) { t = 0; curve = curve.next; }
+    if (!fromElseTo && t === 0) { t = 1; curve = curve.prev; }
+
+    return [p, translate(p, tangent(curve.ps, t))];
+}
+
+
+export { getBoundaryTangentLine }

package/src/point-on-shape/get-osculating-circle.ts

@@ -5,12 +5,14 @@ const { sqrt } = Math;
 
 
 /**
- * Returns the osculating circle at this point of the curve.
- * 
- * @param minCurvature if not `Infinity` then the circle radius will be limited
- * to this value
+ * Returns the osculating circle at this point of the curve as
+ * `[center, radius]`.
+ *
+ * @param maxOsculatingCircleRadius the circle radius will be limited to this
+ * value (i.e. the curvature is taken to be at least its reciprocal)
  * @param pos the `PointOnShape` identifying the point
- * @param useMaxRadius
+ * @param norm the (not necessarily unit) normal at the point pointing towards
+ * the center of the circle
  */
 function getOsculatingCircle(
         maxOsculatingCircleRadius: number, 

package/src/point-on-shape/get-pos-corner.ts

@@ -1,7 +1,7 @@
 import type { Corner } from "../corner/corner.js";
 import type { Curve } from "flo-boolean";
 import { memoize } from 'flo-memoize';
-import { getCorner } from "../corner/get-corner.js";
+import { getCorner$ } from "../corner/get-corner.js";
 
 
 /**
@@ -12,7 +12,7 @@ const getPosCorner$ = memoize(function(
 
     const { t, curve } = pos;
 
-    return getCorner(
+    return getCorner$(
         t === 1 ? curve.ps : curve.prev.ps,
         t === 1 ? curve.next.ps : curve.ps,
     );

package/src/reconstruct-from-mat/reconstruct-from-mat.ts

@@ -1,15 +1,13 @@
 import type { BezierPiece } from 'flo-bezier3';
 import type { Mat } from '../mat/mat.js';
 import type { CpNode } from '../cp-node/cp-node.js';
-import {
-    toUnitVector, distanceBetween, fromTo as fromToVec, dot, rotate90Degrees,
-    cross, interpolate, translate, lineLineIntersection
-} from 'flo-vector2d';
-import { tangent as getTangent } from 'flo-bezier3';
+import { distanceBetween } from 'flo-vector2d';
 import { mapDeep } from '../utils/map-deep.js';
 import { removeSatInducedTrivial3Prongs } from './remove-sat-induced-trivial-3prongs.js';
 import { getCpNodessForSat } from './get-cp-nodess-for-sat.js';
-import { getRealProngCount } from '../cp-node/fs/get-real-prong-count.js';
+import { clone } from '../cp-node/fs/clone.js';
+import { getBoundaryTangentLine } from '../point-on-shape/get-boundary-tangent-line.js';
+import { getBeziersFromTangents } from '../utils/get-beziers-from-tangents.js';
 
 
 const { max, abs, round, log2 } = Math;
@@ -29,24 +27,28 @@ function reconstructFromMats(
         mats: Mat[],
         minNumAccurateBits: number | undefined = undefined) {
 
-    const maxPO2 = max(...mats.map(mat => mat.meta.maxCoordPowerOf2));
+    let maxPO2 = -Infinity;
+    for (const mat of mats) { maxPO2 = max(maxPO2, mat.meta.maxCoordPowerOf2); }
     const recoverBoundary_ = recoverBoundary(maxPO2, minNumAccurateBits);
 
+    // `removeSatInducedTrivial3Prongs` relinks nodes in place so work on 
+    // clones - the given `Mat`s must not be modified. (Only 
+    // `meta.maxCoordPowerOf2` is used from the metas so they can be shared.)
     // Really only required if getSats was called on the `Mat`s
     const cpNodessPerSat = mats
+        .map(mat => ({ cpNode: clone(mat.cpNode), meta: mat.meta }))
         .map(removeSatInducedTrivial3Prongs)
         .map(getCpNodessForSat);
 
     const r = mapDeep(3, cpNodessPerSat, recoverBoundary_, true);
     // ii;//?
 
-    return r;
+    // Flatten the (1 or 2) beziers per boundary piece into a single array of
+    // beziers per loop.
+    return r.map(loops => loops.map(pieces => pieces.flat()));
 }
 
 
-const FROM = 0;
-const TO = 1;
-
 /**
  * 
  * @param cpNode 
@@ -78,9 +80,6 @@ function recoverBoundary(
 
         const d = distanceBetween(circle.center, p);
         
-        if (getRealProngCount(cpNode)) {
-
-        }
 
         // DON'T remove these - they tell us the accuracy of the algorithm
         // if (!closeTo(2**34)(circle.radius, d) && getRealProngCount(cpNode) === 3) {
@@ -118,108 +117,20 @@ function recoverBoundary(
 }
 
 
-/** @internal */
-const TOLERANCE_ADD_2PRONG = 0.01;
-/** @internal */
-const TOLERANCE_USE_LINE = 0.0001; // else cubic
-
-
-function getBoundaryPiece(
-        cpNode: CpNode) {
-
-    const cpNode_ = cpNode.next;
-
-    const pos = cpNode.pointOnShape; 
-    const pos_ = cpNode_.pointOnShape;
-
-    const { p } = pos;
-    const { p: p_ } = pos_;
-
-    const fromCc = p;
-    const fromL = getEdgeDirection(cpNode, FROM);
-
-    const toCc = p_;
-    const toL = getEdgeDirection(cpNode_, TO);
-
-    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];
-    } 
-
-    // Within tolerance - approximate with a straight line.
-    return [fromCc, toCc];
-}
-
-
 /**
- * Returns a line segment of unit length starting at the given point and
- * being tangent to the shape boundary.
+ * Returns the bezier curves (1 or 2 lines or quadratics) approximating the 
+ * shape boundary from the contact point of the given `CpNode` to that of the 
+ * next `CpNode`.
  * 
  * @internal
  */
-function getEdgeDirection(
-        cpNode: CpNode,
-        fromOrTo: typeof FROM | typeof TO) {
-
-    let { pointOnShape } = cpNode;
-    let { curve, t, p } = pointOnShape;
-    let { ps } = curve;
-
-    if (fromOrTo === FROM && t === 1) {
-        t = 0;
-        curve = curve.next;
-        ps = curve.ps;
-    }
-    if (fromOrTo === TO && t === 0 ) {
-        t = 1;
-        curve = curve.prev;
-        ps = curve.ps;
-    }
-
-    const tangent = getTangent(ps, t);
-    
-    const v = translate(p, tangent);
+function getBoundaryPiece(
+        cpNode: CpNode) {
 
-    return [p,v];
+    return getBeziersFromTangents(
+        getBoundaryTangentLine(cpNode.pointOnShape, true),
+        getBoundaryTangentLine(cpNode.next.pointOnShape, false)
+    );
 }
 
 

package/src/reconstruct-from-mat/remove-sat-induced-trivial-3prongs.ts

@@ -7,6 +7,10 @@ import { isFullyTerminating } from '../cp-node/fs/is-fully-terminating.js';
  * In-place removes trivial 3-prongs from the SAT graph; just to simplify
  * subsequent processing.
  * 
+ * * **mutates** the given `Mat` (its `CpNode`s are relinked and `cpNode` is
+ *   reassigned; `meta.cpTrees` is left stale) - pass a clone if the original
+ *   must be kept
+ * 
  * These are 3-prongs that are induced by the SAT construction, and do
  * not correspond to actual 3-prongs in the shape.
  *