flo-mat 4.0.2 → 4.1.0

package/src/get-medial-points/double-double/error-bound-calc.txt

@@ -0,0 +1,72 @@
+
+//--------------------------------------------------------------------------
+// `var` -> a variable
+// `$var` -> the double precision approximation to `var`
+// `_var` -> the absolute value of $var (a prefix underscore on a variable means absolute value)
+// `var_` -> the error in var (a postfix underscore means error bound but should still be multiplied by 3*γ²)
+// `_var_` -> means both absolute value and absolute error bound
+// recall: `a*b`, where both `a` and `b` have errors |a| and |b| we get for the
+//   * error bound of (a*b) === a_|b| + |a|b_ + |a*b|   (when either of a and b is double)
+//   * error bound of (a*b) === a_|b| + |a|b_ + 2|a*b|  (when both a and b is double-double)
+//   * error bound of (a+b) === a_ + b_ + |a+b|         (when a and/or b is double or double-double)
+// * the returned errors need to be multiplied by 3γ² to get the true error
+// * can use either `$var` or `var[var.length-1]` (the approx value) in error calculations
+//   due to multiplication by 3*γ² and not 3*u²
+//--------------------------------------------------------------------------
+// examples: (all?)
+// ----------------
+// let qmd === ddMultDouble2, etc.
+//
+// ---------------
+// 1. double-double X by double
+// ---------------
+// qmd(a,b);  // both `a` and `b` is error-free
+// use: error bound of (a*b) === a_|b| + |a|b_ + |a*b| (by definition)
+//                           === 0|b| + |a|0 + |a*b|
+//                           === |a*b|
+//
+// ---------------
+// 2a. double-double +/- double-double
+// ---------------
+// qdq(a,b);  // error in a === |a|, thus call the error _a_, same with b
+// use: error bound of (a+b) === a_ + b_ + |a+b| (by definition)
+//                           === _a_ + _b_ + |a+b|
+//
+// ---------------
+// 2b. double-double +/- double-double
+// ---------------
+// qaq(a,b);  // error in a === 2|a|, thus the error is 2*_a, same with b
+// use: error bound of (a+b) === a_ + b_ + |a+b| (by definition)
+//                           === 2*_a + 2*_b + |a+b|
+//                           === 2*(_a + _b) + |a+b| OR
+//                           === a_ + b_ + |a+b|
+//
+// ---------------
+// 3a. double-double X double-double
+// ---------------
+// qmq(a,b);  // both `a` and `b` error-free
+// use: error bound of (a*b) === a_|b| + |a|b_ + |a*b| (by definition)
+//                           === 0|b| + |a|0 + 2|a*b|
+//                           === 2|a*b| 
+//
+// ---------------
+// 3b. double-double X double-double
+// ---------------
+// qmq(a,b);  // both `a` and `b` not error-free
+// use: error bound of (a*b) === a_|b| + |a|b_ + 2|a*b| (by definition)
+//
+// ---------------
+// 3b. double-double X double-double
+// ---------------
+// qmq(a,b);  // both `a` not error-free and `b` error-free
+// use: error bound of (a*b) === a_|b| + |a|b_ + 2|a*b| (by definition)
+//                           === a_|b| + 2|a*b| 
+//
+// ---------------
+// 4a. double-double +/- double
+// ---------------
+// qad(a,b);  // both `a` and `b` error-free
+// use: error bound of (a+b) === a_ + b_ + |a+b| (by definition)
+//                           === 0 + 0 + |a+b|
+//                           === |a+b| 
+//--------------------------------------------------------------------------

package/src/index.ts

@@ -7,14 +7,10 @@ export type { CpNode  } from './cp-node/cp-node.js';
 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 { DrawElemFunctions } from './debug/functions/draw-elem/draw-elem.js';
-export type { ITiming } from './debug/debug.js';
-export type { DebugElems } from './debug/debug-elem-types.js';
+export type { Timing } from './debug/debug.js';
 export type { Debug } from './debug/debug.js';
-export type { DebugElemKey } from './debug/debug-elem-types.js';
 export type { MatOptions } from './find-mat/mat-options.js';
 
-export { drawBeziersAsSinglePath } from './debug/functions/draw/draw-beziers-as-single-path.js';
 export { floydWarshall } from './floyd-warshall/floyd-warshall.js';
 export { CpNodeFs } from './cp-node/cp-node-fs.js';
 export { isVertexSpecial } from './cp-node/fs/is-vertex-special.js';
@@ -23,13 +19,9 @@ export { trimMat } from './mat/trim-mat.js';
 export { toScaleAxis } from './sat/to-scale-axis.js';
 export { getBranches } from './mat/get-branches.js';
 export { enableDebugForMat } from './debug/debug.js';
-export { drawBranch } from './debug/functions/draw-elem/draw-branch.js';
-export { drawMat } from './debug/functions/draw-elem/draw-mat.js';
-export { debugElemNames, emptyDebugElems } from './debug/debug-elem-types.js';
 export { getShapeBounds } from './svg/get-shape-bounds.js';
 export { getBoundaryPieceBeziers } from './mat/get-boundary-piece-beziers.js';
 export { simplifyMat } from './mat/simplify-mat.js';
-export { drawElemFs, drawElemFsDetailed } from './debug/functions/draw-elem/draw-elem.js';
 export { sweepLine } from './sweep-line/sweep-line.js';
 export { getClosestSquareDistanceToRect } from './geometry/get-closest-square-distance-to-rect.js';
 export { getImpliedBoundaryBezierBetween } from './cp-node/fs/get-implied-boundary-bezier-between.js';
@@ -41,8 +33,10 @@ 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, getPointToCpNode } from './find-mat/get-meta.js';
+export { getPartialMeta } from './find-mat/get-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';
 
 
 // CpNodeFs functions
@@ -80,4 +74,6 @@ export { getHoleClosers } from './cp-node/fs/get-hole-closers.js';
 export { getInitialDegAngleBetweenMatCurves } from './cp-node/fs/get-angle-between-mat-curves.js';
 export { getAllVertices } from './cp-node/fs/get-all-vertices.js';
 export { isTrivial } from './cp-node/fs/is-trivial.js';
-export { scaleCircle } from './geometry/circle.js';
+export { scaleCircle } from './geometry/circle.js';
+export { isOnSameLoop } from './cp-node/fs/is-on-same-loop.js';
+export { getAllOnLoop_ByLoop } from './cp-node/fs/get-all-on-loop-by-loop.js';

package/src/point-on-shape/point-on-shape.ts

@@ -28,6 +28,9 @@ interface PrePointOnShape {
 
     /** The (cached) point on the shape boundary. */
     readonly p: number[];
+
+    /** The (cached) double-double precision point on the shape boundary. */
+    readonly pDd: number[][];
 }
 
 

package/src/point-on-shape/to-p.ts

@@ -10,9 +10,9 @@ import { evalDeCasteljauDd } from "flo-bezier3";
  */
 function toP(
         ps: number[][],
-        t: number): number[] {
+        t: number): number[][] {
 
-    return evalDeCasteljauDd(ps, [0,t]).map(c => c[0] + c[1]);
+    return evalDeCasteljauDd(ps, [0,t]);
 }
 
 

package/src/reconstruct-from-mat/get-cp-nodess-for-sat.ts

@@ -0,0 +1,24 @@
+import type { CpNode } from "../cp-node/cp-node.js";
+import type { Mat } from '../mat/mat.js';
+import { isOnSameLoop } from "../cp-node/fs/is-on-same-loop.js";
+import { getAllOnLoop_ByLoop } from "../cp-node/fs/get-all-on-loop-by-loop.js";
+import { isFullyTerminating } from "../cp-node/fs/is-fully-terminating.js";
+
+
+function getCpNodessForSat(
+        sat: Mat): CpNode[][] {
+
+    let { cpNode } = sat;
+
+    while (!isFullyTerminating(cpNode)) {
+        cpNode = cpNode.next;
+    }
+    if (!isOnSameLoop(cpNode, cpNode.next)) {
+        cpNode = cpNode.holeCloserTwin!;
+    }
+
+    return getAllOnLoop_ByLoop(cpNode);
+}
+
+
+export { getCpNodessForSat }

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

@@ -0,0 +1,226 @@
+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 { 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';
+
+
+const { max, abs, round, log2 } = Math;
+
+
+// let ii = 0;
+
+
+/**
+ * * used for debugging only
+ * 
+ * @param mats 
+ * 
+ * @internal
+ */
+function reconstructFromMats(
+        mats: Mat[],
+        minNumAccurateBits: number | undefined = undefined) {
+
+    const maxPO2 = max(...mats.map(mat => mat.meta.maxCoordPowerOf2));
+    const recoverBoundary_ = recoverBoundary(maxPO2, minNumAccurateBits);
+
+    // Really only required if getSats was called on the `Mat`s
+    const cpNodessPerSat = mats
+        .map(removeSatInducedTrivial3Prongs)
+        .map(getCpNodessForSat);
+
+    const r = mapDeep(3, cpNodessPerSat, recoverBoundary_, true);
+    // ii;//?
+
+    return r;
+}
+
+
+const FROM = 0;
+const TO = 1;
+
+/**
+ * 
+ * @param cpNode 
+ * 
+ * @internal
+ */
+function recoverBoundary(
+        maxPO2: number,
+        minNumAccurateBits: number | undefined) {
+
+    return function (cpNode: CpNode) {
+        const cpNode_ = cpNode.next;
+
+        const pos = cpNode.pointOnShape; 
+        const pos_ = cpNode_.pointOnShape;
+
+        const { curve, circle, p } = pos;
+        const { curve: curve_, p: p_ } = pos_;
+
+        if (p[0] === p_[0] && p[1] === p_[1]) {
+            return undefined;
+        }
+
+        if (curve.loop !== curve_.loop) {
+            // It is a hole-closer going over to the other loop
+            // return undefined;
+            return undefined;
+        }
+
+        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) {
+        //     ii++;
+        //     circle.center;//?
+        //     circle.radius;//?
+        //     d;            //?
+        //     p;//?
+        //     pos.isSource;//?
+        //     getRealProngCount(cpNode);//?
+        // }
+        // if (!closeTo(2**28)(circle.radius, d) && getRealProngCount(cpNode) !== 3) {
+        //     ii++;
+        //     circle.center;//?
+        //     circle.radius;//?
+        //     d;            //?
+        //     p;//?
+        //     pos.isSource;//?
+        //     getRealProngCount(cpNode);//?
+        // }
+        if (minNumAccurateBits !== undefined) {
+            const TOL = 2**(maxPO2 - minNumAccurateBits);
+
+            if (abs(circle.radius - d) > TOL) {
+                throw new Error(
+                    `Medial circle radius must be about the same (2**${round(log2(TOL))}) ` +
+                    `as distance from medial circle center to point on shape, ` + 
+                    `found: medial radius ${circle.radius}, distance: ${d}`
+                );
+            }
+        }
+
+        return getBoundaryPiece(cpNode);
+    }
+}
+
+
+/** @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.
+ * 
+ * @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);
+
+    return [p,v];
+}
+
+
+export { reconstructFromMats }

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

@@ -0,0 +1,62 @@
+import type { Mutable } from '../utils/mutable.js';
+import type { Mat } from '../mat/mat.js';
+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.
+ * 
+ * These are 3-prongs that are induced by the SAT construction, and do
+ * not correspond to actual 3-prongs in the shape.
+ * 
+ * @param sat the SAT
+ */
+function removeSatInducedTrivial3Prongs(
+        sat: Mat): Mat {
+
+    let { cpNode } = sat;
+
+    let cpStart = cpNode;
+    do {
+        if (isFullyTerminating(cpNode) ||
+            // cpNode.isHoleClosing ||  // hole-closers are fully terminating
+            cpNode.next !== cpNode.nextOnCircle) {
+
+            cpNode = cpNode.next;
+            continue;
+        }
+
+        //-----------------------------
+        // Delete the trivial 3-prong
+        //-----------------------------
+        // console.log('Removing SAT-induced trivial 3-prong');
+
+        const next = cpNode.next;
+        const nextNext = next.next;
+        const nextNextOC = cpNode.next.nextOnCircle;
+
+        //-------------------------------------------------------------
+        // In-place update of links to remove the trivial 3-prong node
+        //-------------------------------------------------------------
+        (cpNode as Mutable<typeof cpNode>).next = nextNext;
+        (cpNode as Mutable<typeof cpNode>).nextOnCircle = nextNextOC;
+        (nextNext as Mutable<typeof nextNext>).prev = cpNode;
+        (nextNextOC as Mutable<typeof nextNextOC>).prevOnCircle = cpNode;
+        //-------------------------------------------------------------
+
+        if (cpStart === next) {
+            cpStart = cpNode;  // ...otherwise the loop will never terminate
+        }
+
+        cpNode = cpNode.next;
+    } while (cpNode !== cpStart)
+
+    // ...otherwise the caller will have a reference to a node that has been removed from the graph
+    (sat as Mutable<Mat>).cpNode = cpNode;
+
+    return sat;
+}
+
+
+export { removeSatInducedTrivial3Prongs }

package/src/sat/add-debug-info.ts

@@ -12,8 +12,7 @@ function addDebugInfo(
 
     if (typeof _debug_ === 'undefined') { return; }
 
-    const timing = _debug_.generated.timing;
-    timing.sats = performance.now() - timingStart;
+    _debug_.timing.sats = performance.now() - timingStart;
 }
 
 

package/src/svg/get-loop-bounds.ts

@@ -12,12 +12,20 @@ type Extreme = {
 };
 
 
-function toPrePoint(extreme: Extreme): PrePointOnShape {
+function toPrePoint(
+        extreme: Extreme): PrePointOnShape {
+
+    const { curve, t } = extreme;
+    const { ps } = curve;
+
+    const pDd = toP(ps, t);
+    const p = pDd.map(c => c[0] + c[1]);
+
     return {
-        curve: extreme.curve,
+        curve,
         t: extreme.t,
         isSource: true,
-        p: toP(extreme.curve.ps, extreme.t)
+        p, pDd
     };
 }
 

package/src/utils/clip.ts

@@ -0,0 +1,13 @@
+
+const { max, min } = Math;
+
+function clip(
+        v: number,
+        vMin: number,
+        vMax: number): number {
+
+    return max(vMin, min(vMax, v));
+}
+
+
+export { clip }

package/src/utils/map-deep.ts

@@ -0,0 +1,75 @@
+
+type Depth = 1 | 2 | 3 | 4 | 5 | 6;
+
+type NestedArray<T, D extends Depth> =
+    D extends 1 ? T[] :
+    D extends 2 ? T[][] :
+    D extends 3 ? T[][][] :
+    D extends 4 ? T[][][][] :
+    D extends 5 ? T[][][][][] :
+    T[][][][][][];
+
+type PrevDepth<D extends Depth> =
+    D extends 6 ? 5 :
+    D extends 5 ? 4 :
+    D extends 4 ? 3 :
+    D extends 3 ? 2 :
+    D extends 2 ? 1 :
+    never;
+
+type LeafAtDepth<A, D extends Depth> =
+    D extends 1
+        ? A extends (infer T)[] ? T : never
+        : A extends (infer T)[] ? LeafAtDepth<T, PrevDepth<D>> : never;
+
+type LeafValue<T, FilterUndefined extends boolean> =
+    FilterUndefined extends true ? Exclude<T, undefined> : T;
+
+
+/**
+ * Returns the result of mapping the array to the given depth and, optionally,
+ * filtering out `undefined` leaf values.
+ * 
+ * @param tss 
+ * @param f 
+ * @param filterUndefined 
+ */
+function mapDeep<D extends Depth, A extends NestedArray<unknown, D>, U, F extends boolean = false>(
+        depth: D,
+        tss: A,
+        f: (t: LeafAtDepth<A, D>) => U,
+        filterUndefined?: F): NestedArray<LeafValue<U, F>, D> {
+
+    if (!Number.isInteger(depth) || depth < 1) {
+        throw new Error('depth must be an integer >= 1');
+    }
+
+    function mapRec(d: number, arr: unknown): unknown {
+        const a = arr as unknown[];
+
+        if (d === 1) {
+            const ts_: U[] = [];
+            for (let i=0; i<a.length; i++) {
+                const v = f(a[i] as LeafAtDepth<A, D>);
+                if (!filterUndefined || v !== undefined) {
+                    ts_.push(v);
+                }
+            }
+
+            return ts_;
+        }
+
+        const tss_: unknown[] = [];
+        for (let i=0; i<a.length; i++) {
+            tss_.push(mapRec(d - 1, a[i]));
+        }
+
+        return tss_;
+    }
+
+    return mapRec(depth, tss as unknown) as NestedArray<LeafValue<U, F>, D>;
+}
+
+
+export { mapDeep }
+

package/src/utils/map-map.ts

@@ -0,0 +1,33 @@
+
+/**
+ * Returns the result of mapping the array to depth 2 and applying a filter
+ * to the inner results which defaults to filtering out `undefined`.
+ * 
+ * @param tss 
+ * @param f 
+ * @param filter 
+ */
+function mapmap<T,U>(
+        tss: T[][],
+        f: (t: T) => U,
+        filter: (u: U) => boolean = u => u !== undefined): U[][] {
+
+    const tss_: U[][] = [];
+    for (let i=0; i<tss.length; i++) {
+        const ts = tss[i];
+        const ts_: U[] = [];
+        for (let j=0; j<ts.length; j++) {
+            const v = f(ts[j]);
+            if (filter(v)) {
+                ts_.push(f(ts[j]));
+            }
+        }
+        tss_.push(ts_);
+    }
+
+    return tss_;
+}
+
+
+export { mapmap }
+

package/wallaby.mjs

@@ -1,18 +1,18 @@
 
 export default function(wallaby) {
     return {
+        autoDetect: ['jest'],
+
         files: [
             'package.json',
             'src/**/*.ts',
-            'test/helpers/*.ts'
+            '__tests__/helpers/*.ts'
         ],
 
         tests: [
-            'test/**/*.spec.ts'
+            '__tests__/**/*.spec.ts'
         ],
 
-        testFramework: 'mocha',
-
         compilers: {
             "**/*.+(t)s?": wallaby.compilers.typeScript()
         },

package/node/debug/debug-elem-types.d.ts

@@ -1,26 +0,0 @@
-import { Mat } from '../mat/mat.js';
-import { CpNode } from '../cp-node/cp-node.js';
-type DebugElemKey = keyof typeof emptyDebugElems;
-declare const emptyDebugElems: {
-    readonly oneProng: CpNode[];
-    readonly twoProng: CpNode[];
-    readonly threeProng: CpNode[];
-    readonly looseBoundingBox: number[][][];
-    readonly tightBoundingBox: number[][][];
-    readonly boundingHull: number[][][];
-    readonly vertex: CpNode[];
-    readonly mat: Mat[];
-    readonly maxVertex: CpNode[];
-    readonly leaves: CpNode[][];
-    readonly cull: number[][];
-    readonly cpNode: CpNode[];
-    readonly branch: CpNode[][];
-    readonly holeCloser: CpNode[];
-};
-declare const debugElemNames: Array<keyof typeof emptyDebugElems>;
-/** @internal */
-type DebugElems = typeof emptyDebugElems;
-type DebugElem = {
-    [T in keyof DebugElems]: DebugElems[T][number];
-};
-export { DebugElems, DebugElemKey, DebugElem, emptyDebugElems, debugElemNames, };