flo-mat 3.0.11 → 3.0.13

package/src/cp-node/fs/cp-node-comparator.ts

@@ -2,6 +2,12 @@ import type { CpNode } from "../cp-node.js";
 import { compareCps } from "../../contact-point/contact-point.js";
 
 
+/**
+ * Primarily for internal use.
+ * 
+ * Compares the order of two `CpNode`s. The order is cyclic and depends
+ * on a `CpNode`'s relative position along the shape boundary.
+ */
 function cpNodeComparator(
         a: CpNode,
         b: CpNode) {

package/src/cp-node/fs/enhance-cp-node.ts

@@ -7,6 +7,10 @@ import { isSharp } from "./is-sharp.js";
 import { isTerminating } from "./is-terminating.js";
 
 
+/**
+ * For debugging
+ * @param cpNode 
+ */
 function enhanceCpNode(cpNode: CpNode) {
     const cp = cpNode.cp;
     const pos = cp.pointOnShape;

package/src/cp-node/fs/get-all-on-circle.ts

@@ -2,10 +2,10 @@ import type { CpNode } from "../cp-node.js";
 
 
 /**
- * Returns all the `CpNode`s on the same circle.
- * 
- * @param cpNode 
- * @param exclThis 
+ * Return this (except if exclThis is truthy) and the the other CpNodes 
+ * around the maximal disk vertex circle in an anti-clockwise order.
+ * @param exclThis If true the returned array does not include this 
+ * `CpNode`.
  */
 function getAllOnCircle(
         cpNode: CpNode,

package/src/cp-node/fs/get-all-on-loop.ts

@@ -1,6 +1,10 @@
 import type { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns all `CpNode`s on the MAT that this `CpNode` is part of 
+ * starting from the current one and going anti-clockwise around the shape.
+ */
 function getAllOnLoop(
         cpNode: CpNode) {
 

package/src/cp-node/fs/get-boundary-bezier-parts-to-next.ts

@@ -4,13 +4,14 @@ import type { Curve  } from '../../curve/curve.js';
 
 
 /**
- * Returns the boundary beziers pieces between this `CpNode` and the next
- * one.
+ * Returns the ordered `BezierPiece`s from this `CpNode` to the next `CpNode` 
+ * on the boundary.
  * 
- * * returns `undefined` if the next `CpNode` is on a different loop,
- * as this is a hole-closer and there are no boundary beziers between them.
+ * * returns `[]` if (and only if) the next `CpNode` is on a different loop;
+ * this differs from "returns `[]` if (and only if) the next `CpNode` is a
+ * hole-closer" as half of hole-closers are on the same loop.
  * 
- * @param cpNode 
+ * @param cpNode
  */
 function getBoundaryBezierPartsToNext(
         cpNode: CpNode): BezierPiece[] {

package/src/cp-node/fs/get-boundary-beziers-to-next.ts

@@ -4,14 +4,10 @@ import { getBoundaryBezierPartsToNext } from './get-boundary-bezier-parts-to-nex
 
 
 /**
-//  * Returns the boundary beziers between this `CpNode` and the next
-//  * one.
-//  * 
-//  * * returns `[]` if the next `CpNode` is on a different loop,
-//  * as this is a hole-closer and there are no boundary beziers between them.
-//  * 
-//  * @param cpNode 
-//  */
+ * Returns the ordered bezier curves from this `CpNode` to the next `CpNode` 
+ * on the boundary.
+ * @param cpNode
+ */
 function getBoundaryBeziersToNext(
         cpNode: CpNode): number[][][] {
 

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

@@ -1,6 +1,12 @@
 import { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns the children of this `CpNode` when seen as a MAT edge. Only 
+ * children in a 'forward' direction are returned. These include all edges 
+ * except the 'backward' edge given by `prevOnCircle`, even terminating
+ * edges.
+ */
 function getChildren(cpNode: CpNode) {
     const children: CpNode[] = [];
 

package/src/cp-node/fs/get-edge-direction.ts

@@ -7,6 +7,12 @@ import { isPosSharpCorner } from '../../point-on-shape/is-pos-sharp-corner.js';
 import { Curve } from '../../curve/curve.js';
 
 
+/**
+ * @internal
+ * Returns a line segment of unit length starting in the given Vertex center and
+ * pointing in the direction of the medial axis (viewed as a rooted tree).
+ * @param cpNode 
+ */
 function getEdgeDirection(cpNode: CpNode) {
     const circleCenter = cpNode.cp.circle.center;
 

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

@@ -1,6 +1,10 @@
 import { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns the first `CpNode` (from this one by successively applying 
+ * .nextOnCircle) that exits the circle.
+ */
 function getFirstExit(cpNode: CpNode) {
     // const startNode = this as CpNode;
     const startNode = cpNode;

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

@@ -12,6 +12,12 @@ const TOLERANCE_ADD_2PRONG = 0.01;
 const TOLERANCE_USE_LINE = 0.0001; // else cubic
 
 
+/**
+ * Returns the bezier curve from the maximal disk of one `CpNode` to another
+ * `CpNode`'s maximal disk.
+ * @param cpNodeFrom 
+ * @param cpNodeTo 
+ */
 function getMatCurveBetween(
         cpNodeFrom: CpNode, 
         cpNodeTo: CpNode): number[][] {

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

@@ -3,6 +3,12 @@ import { CpNode } from '../cp-node.js';
 import { getMatCurveBetween } from './get-mat-curve-between.js';
 
 
+/**
+ * Returns the bezier curve from the maximal disk of the given `CpNode` to the 
+ * next `CpNode`'s maximal disk and thus directly represents a piece of the 
+ * medial axis.
+ * @param cpNode 
+ */
 function getMatCurveToNext(cpNode: CpNode) {
     return getMatCurveBetween(cpNode, cpNode.next);
 }

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

@@ -1,6 +1,14 @@
 import { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns the number of contact points on the maximal disk circle implied
+ * by this `CpNode`. 
+ * 
+ * Note, however, that even one-prongs and sharp corners will return 2 (see
+ * `isTerminating` for more details); if this is not desired use 
+ * `getRealProngCount` instead which will return 1 in these cases.
+ */
 function getProngCount(cpNode: CpNode) {
     const startCpNode = cpNode;
     let cpNode_ = startCpNode;

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

@@ -3,6 +3,12 @@ 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`. 
+ * 
+ * See also `getProngCount`.
+ */
 function getRealProngCount(cpNode: CpNode) {
     const nonTerminatingCpNodes = getAllOnCircle(cpNode)
     .filter(cpNode => !isTerminating(cpNode));

package/src/cp-node/fs/get-vertex-forward-children.ts

@@ -2,6 +2,14 @@ import { CpNode } from "../cp-node.js";
 import { isTerminating } from "./is-terminating.js";
 
 
+/**
+ * Similar to `getChildren` but returns the child nodes of the tree when 
+ * `CpNode` is seen as a MAT vertex point (as opposed to edge). In this 
+ * way the dual graph of the tree can easily be traversed - see e.g. 
+ * `traverseVertices`. Generally, however, traversing the edges is 
+ * preferred as it returns the entire Medial Axis (by utilizing 
+ * `getMatCurveToNext` on each returned edge).
+ */
 function getVertexForwardChildren(cpNode: CpNode) {
     const children: CpNode[] = [];
 

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

@@ -4,11 +4,8 @@ import { isTerminating } from "./is-terminating.js";
 
 
 /**
- * Returns `true` if this `CpNode` is fully terminating, meaning that all
- * `CpNode`s (except `CpNode.prevOnCircle`) on the same circle are terminating,
- * `false` otherwise.
- * 
- * @param cpNode 
+ * Like isTerminating() but only returns true if all cpNodes on the circle
+ * (except this.prevOnCircle) is terminating.
  */
 function isFullyTerminating(cpNode: CpNode) {
     const otherOnCircle = getAllOnCircle(cpNode.prevOnCircle, true);

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

@@ -2,6 +2,12 @@ import { CpNode } from "../cp-node.js";
 import { getAllOnCircle } from "./get-all-on-circle.js";
 
 
+/**
+ * Returns true if the 2 given `CpNode`s are on the same maximal disk 
+ * circle.
+ * @param cpNode1 A `CpNode`.
+ * @param cpNode2 Another `CpNode`
+ */
 function isOnSameCircle(
         cpNode1: CpNode,
         cpNode2: CpNode) {

package/src/cp-node/fs/is-one-prong.ts

@@ -1,6 +1,14 @@
 import { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns true if this `CpNode`'s maximal disk has only one contact point
+ * on the shape boundary (up to planar coordinates). These includes sharp 
+ * corners.
+ * 
+ * Note, however, that two `CpNode`s are stored for each such point to
+ * preserve symmetry - see `isTerminating` for more details.
+ */
 // TODO2 - remove - or replace with `getRealProngCount === 1`
 function isOneProng(cpNode: CpNode) {
     const cp1 = cpNode;

package/src/cp-node/fs/is-order-correct.ts

@@ -1,16 +1,13 @@
+import type { CpNode } from "../cp-node.js";
 import { LlRbTree } from "flo-ll-rb-tree";
 import { compareCps, ContactPoint } from "../../contact-point/contact-point.js";
-import { CpNode } from "../cp-node.js";
 
 
 function isOrderCorrect(
-        // isHoleClosing: boolean,
         cpTree: LlRbTree<CpNode>,
         cp: ContactPoint,
         next: CpNode): boolean {
 
-    // if (isHoleClosing) { return true; }
-
     // TODO2
     const c = compareCps(cp,next.cp);
     if (c < 0) { return true; }

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

@@ -1,6 +1,13 @@
 import { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns true if this `CpNode` represents a sharp corner, i.e. the 
+ * limiting case of a two-prong having zero radius. 
+ * 
+ * Note that two `CpNode`s are stored for each sharp corner, one being
+ * terminating and one not. See `isTerminating` for more details.
+ */
 function isSharp(cpNode: CpNode) {
     return cpNode.cp.circle.radius === 0;
 }

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

@@ -1,4 +1,4 @@
-import { CpNode } from "../cp-node.js";
+import type { CpNode } from "../cp-node.js";
 import { getRealProngCount } from "./get-real-prong-count.js";
 
 
@@ -7,8 +7,7 @@ function isSpecial(
 
     return (
         (getRealProngCount(cpNode) !== 2) &&
-        !cpNode.isHoleClosing/* && cpNode.cp.circle.radius !== 0*/
-        // !cpNode.isHoleClosing && cpNode.cp.circle.radius !== 0 // TODO2
+        !cpNode.isHoleClosing
     )
 }
 

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

@@ -1,6 +1,28 @@
 import type { CpNode } from "../cp-node.js";
 
 
+/**
+ * Returns `true` if this `CpNode` is terminating, i.e. implies a leaf MAT
+ * vertex.
+ * 
+ * The following are some instances where this is the case:
+ * 
+ * * Sharp corners.
+ * 
+ * * Half of Hole-closers, i.e. `CpNode`s whose next `CpNode` is on a different
+ * loop
+ * 
+ * * Maximal disks with a single contact point. 
+ *   Note, however, that even in these cases there are two contact points stored
+ *   (sitting 'on top' of each other) for the maximal disk. It can be seen as a
+ *   limiting case of a two-prong where the distance between two of the contact
+ *   points tend to zero. One point (represented by a `CpNode` of course) will
+ *   be terminating with the other point being its `next`, whereas the other
+ *   point will *not* be terminating and 'points' back into the shape.
+ * 
+ * * Some 3-prongs may also become terminating if the Scale Axis Transform is
+ * applied to the shape.
+ */
 function isTerminating(cpNode: CpNode) {
     return cpNode === cpNode.next.prevOnCircle;
 }

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

@@ -2,6 +2,15 @@ import { CpNode } from "../cp-node.js";
 import { isTerminating } from "./is-terminating.js";
 
 
+/**
+ * @internal
+ * 
+ * Traverses the shape from the given `CpNode` going around the shortest path
+ * so that only a piece of the shape is traversed and returns the visited 
+ * `CpNode`s (starting from the given `CpNode`).
+ * 
+ * @param cpStart The `CpNode` from where to start the traversal.
+ */
 function traverseCp(
         cpStart: CpNode) {
 

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

@@ -3,6 +3,13 @@ import { isTerminating } from './is-terminating.js';
 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 
+ * start of an edge.
+ */
 function traverseEdges(
         cpNode: CpNode,
         traverseEdgesCallback: (cpNode: CpNode) => void) {

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

@@ -5,6 +5,15 @@ import { isTerminating } from './is-terminating.js';
 import { getVertexForwardChildren } from './get-vertex-forward-children.js';
 
 
+/**
+ * Traverses the MAT tree and calls the given callback function for each vertex
+ * (represented by a `CpNode`) on the MAT.
+ * 
+ * It is usually preferable to use `traverseEdges` as it allows for the 
+ * traversal of all the smooth curves representing the MAT.
+ * @param cpNode Any `CpNode` representing the start vertex.
+ * @param traverseVerticesCallback A callback function taking a single `CpNode` as parameter.
+ */
 function traverseVertices(
         cpStart: CpNode, 
         traverseVerticesCallback: (cpNode: CpNode) => void) {

package/src/find-2-prong/add-2-prong.ts

@@ -70,7 +70,6 @@ function add2Prong(
 
 function closeHole(
         meta: MatMeta,
-        // cpTrees: Map<Loop, LlRbTree<CpNode>>,
         cpNodes: CpNode[]) {
 
     const { cpTrees } = meta;
@@ -88,6 +87,8 @@ function closeHole(
         cpNodeB,
         meta.lastInsertId
     )!;
+    cpNodeB2.holeCloserTwin = cpNodeB;
+    cpNodeB.holeCloserTwin = cpNodeB2;
 
     const cpNodeB1 = insertCpNode(
         true,
@@ -97,6 +98,8 @@ function closeHole(
         cpNodeA.prev,
         meta.lastInsertId
     )!;
+    cpNodeB1.holeCloserTwin = cpNodeA;
+    cpNodeA.holeCloserTwin = cpNodeB1;
 
     // Connect graph
     cpNodeB1.prevOnCircle = cpNodeB2;

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

@@ -31,7 +31,8 @@ const { ceil, log2, max, sqrt, abs, sin, cos } = Math;
  *   "The starting point of this algorithm is a choice of a circle Br(x)
  *    centered at an interior point x which contains two boundary portions c and
  *    d of dΩ as in Fig. 19."
- * In fact, we (and they) start by fixing one point on the boundary beforehand. 
+ * In fact, we (and they) start by fixing one point on the boundary beforehand.
+ * 
  * @param loops A shape represented by path loops
  * @param maxCoordinate The extreme coordinate value of the shape
  * @param squaredDiagonalLength The squared diagonal length of the shape 
@@ -45,7 +46,7 @@ function find2Prong(
         isHoleClosing: boolean,
         for1Prong: boolean,
         angle: number,
-        y: PointOnShape): { circle: Circle,    zs: PointOnShape[] } | undefined {
+        y: PointOnShape): { circle: Circle, zs: PointOnShape[] } | undefined {
 
     const { loops, maxCoordinate, squaredDiagonalLength } = meta;
 
@@ -145,7 +146,7 @@ function find2Prong(
             } 
         }
 
-        // Find the point on the line connecting y with x that is  
+        // Find the point on the line connecting y with x that is
         // equidistant from y and z. This will be our next x.
         const nextX = findEquidistantPointOnLineDd(x, y.p, z.p);
         const error = abs(sqrt(xy) - sqrt(xz));

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

@@ -127,7 +127,7 @@ const matOptionRanges: Partial<{ [K in keyof MatOptions]: MatOptionMeta }> = {
         range: [1, Number.POSITIVE_INFINITY],
     },
     simplifyTolerance: {
-        range: [2**-10,1024],
+        range: [2**-20,2**20],
         scaleByMaxCoordinate: true
     },
     minBezLength: {

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

@@ -1,4 +1,4 @@
-import { CpNode } from "../cp-node/cp-node.js";
+import type { CpNode } from "../cp-node/cp-node.js";
 import { getAllOnCircle } from "../cp-node/fs/get-all-on-circle.js";
 import { getMatDistanceToNext$ } from "../cp-node/fs/get-distance-to-next.js";
 import { isOnSameCircle } from "../cp-node/fs/is-on-same-circle.js";
@@ -36,7 +36,7 @@ function getGraph(
                     }
                     if (child.isHoleClosing) {
                         // Hole closer found - don't go around loop 
-                        child = holeCloserNext(pairs, child);
+                        child = getHoleCloserNext(pairs, child);
                         continue;
                     }
                     if (isVertexSpecial(child)) {
@@ -62,7 +62,7 @@ function getGraph(
 }
 
 
-function holeCloserNext(
+function getHoleCloserNext(
         pairs: Map<CpNode,CpNode>,
         holeCloser: CpNode) {
 

package/src/floyd-warshall/get-hole-closer-pairs.ts

@@ -1,6 +1,14 @@
-import { CpNode } from "../cp-node/cp-node.js";
+import type { CpNode } from "../cp-node/cp-node.js";
 
 
+/**
+ * 
+ * @param holeClosers 
+ * @returns 
+ */
+// TODO - this function is currently O(n^2) but could be made O(n).
+// TODO - only `pointOnShape.p` is checked but `pointOnShape.t` should also be checked
+// or better yet, `CpNode.cp.order` and `CpNode.cp.order2`, etc.
 function getHoleCloserPairs(
         holeClosers: CpNode[]): Map<CpNode,CpNode> {
 

package/src/mat/add-to-cp-tree.ts

@@ -22,10 +22,9 @@ function addToCpTree(
         isHoleClosing: boolean,
         circle: Circle, 
         orders: number[],
-        // cpTrees: Map<Loop,LlRbTree<CpNode>>,
         meta: MatMeta,
         poss: PointOnShape[],
-        neighbors? : CpNode[]): { anyFailed: boolean, cpNodes: (CpNode | undefined) [] } {
+        neighbors?: CpNode[]): { anyFailed: boolean, cpNodes: (CpNode | undefined) [] } {
 
     const { cpTrees } = meta;
 

package/src/vertex/remove-vertex.ts

@@ -7,6 +7,11 @@ import { getProngCount } from '../cp-node/fs/get-prong-count.js';
 import { removeCpNode } from '../cp-node/fs/remove-cp-node.js';
 
 
+/**
+ * Removes a cpNode from the MAT.
+ * @param cpTree The tree graph holding the `CpNodes` of the MAT.
+ * @param cpNode The `CpNode` to remove.
+ */
 function removeVertex(
         cpNode: CpNode,
         meta: MatMeta): void {

package/src/cp-node/fs/create-cp-node.ts

@@ -1,21 +0,0 @@
-// import { ContactPoint } from '../../contact-point/contact-point.js';
-// import { CpNode } from '../cp-node.js';
-
-
-// function createCpNode(
-//         cp: ContactPoint,
-//         isHoleClosing  : boolean,
-//         isIntersection : boolean,
-//         prev           : CpNode = undefined!,
-//         next           : CpNode = undefined!,
-//         prevOnCircle   : CpNode = undefined!,
-//         nextOnCircle   : CpNode = undefined!): CpNode {
-
-//     return {
-//         cp, isHoleClosing, isIntersection,
-//         prev, next, prevOnCircle, nextOnCircle
-//     }
-// }
-
-
-// export { createCpNode }