@itwin/core-geometry 4.4.0-dev.2 → 4.4.0-dev.20

package/lib/esm/topology/HalfEdgeGraphSearch.d.ts

@@ -1,125 +1,130 @@
-/** @packageDocumentation
- * @module Topology
- */
 import { HalfEdge, HalfEdgeGraph, HalfEdgeMask, HalfEdgeToBooleanFunction, NodeToNumberFunction } from "./Graph";
 import { SignedDataSummary } from "./SignedDataSummary";
-/**
- * Interface for an object that executes boolean tests on edges.
- */
+/** Interface for an object that executes boolean tests on edges. */
 export interface HalfEdgeTestObject {
     testEdge(h: HalfEdge): boolean;
 }
-/**
- */
+/** Class to test match of half edge mask. */
 export declare class HalfEdgeMaskTester {
     private _targetMask;
     private _targetValue;
     /**
-     *
+     * Constructor
      * @param mask mask to test in `testEdge` function
      * @param targetValue value to match for true return
      */
     constructor(mask: HalfEdgeMask, targetValue?: boolean);
-    /** Return true if the value of the targetMask matches the targetValue */
+    /** Return true if the value of the targetMask matches the targetValue. */
     testEdge(edge: HalfEdge): boolean;
 }
+/** Class for different types of searches for HalfEdgeGraph. */
 export declare class HalfEdgeGraphSearch {
     /**
-     * * for each node of face, set the mask push to allNodesStack
-     * * push the faceSeed on onePerFaceStack[]
-     */
-    private static pushAndMaskAllNodesInFace;
-    /**
-     * Search an array of faceSeed nodes for the face with the most negative area.
-     * @param oneCandidateNodePerFace array containing one node from each face to be considered.
-     * @returns node on the minimum area face, or undefined if no such face (e.g., all faces have zero area).
-     */
-    static findMinimumAreaFace(oneCandidateNodePerFace: HalfEdgeGraph | HalfEdge[], faceAreaFunction?: NodeToNumberFunction): HalfEdge | undefined;
-    /**
-     * static method for face area computation -- useful as function parameter in collect FaceAreaSummary.
-     * * This simply calls `node.signedFaceArea ()`
+     * Static method for face area computation -- useful as function parameter in `collectFaceAreaSummary`.
+     * * This simply calls `node.signedFaceArea()`
      * @param node instance for signedFaceArea call.
      */
     static signedFaceArea(node: HalfEdge): number;
     /**
-     *
-     * Return a summary structure data about face (or other numeric quantity if the caller's areaFunction returns other value)
-     * * The default areaFunction computes area of polygonal face.
+     * Return a summary of face data (e.g., area) as computed by the callback on the faces of the graph.
      * * Callers with curved edge graphs must supply their own area function.
-     * @param source graph or array of nodes to examine
-     * @param collectAllNodes flag to pass to the SignedDataSummary constructor to control collection of nodes.
-     * @param areaFunction function to all to obtain area (or other numeric value)
+     * @param source graph or array of nodes to examine.
+     * @param collectAllNodes flag to pass to the `SignedDataSummary` constructor to control collection of nodes.
+     * @param areaFunction function to obtain area (or other numeric value). Default computes polygonal face area.
      */
     static collectFaceAreaSummary(source: HalfEdgeGraph | HalfEdge[], collectAllNodes?: boolean, areaFunction?: NodeToNumberFunction): SignedDataSummary<HalfEdge>;
     /**
-     * * Test if the graph is triangulated.
-     * * Return false if:
-     *   * Positive area face with more than 3 edges
-     *   * more than 1 negative area face with `allowMultipleNegativeAreaFaces` false
+     * Search the graph for the face with the most negative area.
+     * @param oneCandidateNodePerFace graph or an array containing one node from each face to be considered.
+     * @returns node on the negative area face with largest absolute area, or `undefined` if no negative area face.
+     */
+    static findMinimumAreaFace(oneCandidateNodePerFace: HalfEdgeGraph | HalfEdge[], faceAreaFunction?: NodeToNumberFunction): HalfEdge | undefined;
+    /**
+     * Test if the graph is triangulated.
+     * * Return `false` if:
+     *   * number of positive area faces with more than 3 edges is larger than `numPositiveExceptionsAllowed`.
+     *   * graph has more than 1 negative area face when `allowMultipleNegativeAreaFaces` is `false`.
      * * 2-edge faces are ignored.
      */
     static isTriangulatedCCW(source: HalfEdgeGraph | HalfEdge[], allowMultipleNegativeAreaFaces?: boolean, numPositiveExceptionsAllowed?: number): boolean;
     /**
-     * Search to all accessible faces from given seed.
-     * * The returned array contains one representative node in each face of the connected component.
-     * * If (nonnull) parity mask is given, on return:
-     *    * It is entirely set or entirely clear around each face
-     *    * It is entirely set on all faces that are an even number of face-to-face steps away from the seed.
-     *    * It is entirely clear on all faces that are an odd number of face-to-face steps away from the seed.
-     * @param seedEdge first edge to search.
+     * Process a face during graph traversal.
+     * @param faceSeed a node in the face.
+     * @param mask mask to set on each node of the face.
+     * @param allNodeStack array appended with each node of the face.
+     * @param onePerFaceStack array appended with `faceSeed`.
+     */
+    private static pushAndMaskAllNodesInFace;
+    /**
+     * Traverse (via Depth First Search) to all accessible faces from the given seed.
+     * @param faceSeed first node to start the traverse.
      * @param visitMask mask applied to all faces as visited.
-     * @param parityMask mask to apply (a) to first face, (b) to faces with alternating parity during the search.
+     * @param parityEdgeTester function to test if an edge is adjacent to two faces of opposite parity, e.g., a boundary
+     * edge that separates an "interior" face and an "exterior" face. If `parityEdgeTester` is not supplied and `parityMask`
+     * is supplied, the default parity rule is to alternate parity state in a "bullseye" pattern starting at the seed face,
+     * with each successive concentric ring of faces at constant topological distance from the seed face receiving the
+     * opposite parity state of the previous ring.
+     * @param parityMask mask to apply to the first face and faces that share the same parity as the first face, as
+     * determined by the parity rule. If this is `NULL_MASK`, there is no record of parity. If (non-null) parity mask
+     * is given, on return it is entirely set or entirely clear around each face.
+     * @returns an array that contains one representative node in each face of the connected component.
      */
     private static parityFloodFromSeed;
     /**
-     * * Search the given faces for the one with the minimum area.
-     * * If the mask in that face is OFF, toggle it on (all half edges of) all the faces.
+     * * Correct the parity mask in the faces of a component.
+     * * It is assumed that the parity mask is applied _consistently_ throughout the supplied faces, but maybe
+     * not _correctly_.
+     * * A consistently applied parity mask is "correct" if it is set on the negative area ("exterior") face of
+     * a connected component.
+     * * This method finds a face with negative area and toggles the mask throughout the input faces if this face
+     * lacks the parity mask.
      * * In a properly merged planar subdivision there should be only one true negative area face per component.
-     * @param graph parent graph
-     * @param parityMask mask which was previously set with alternating parity, but with an arbitrary start face.
-     * @param faces array of faces to search.
      */
     private static correctParityInSingleComponent;
-    /** Apply correctParityInSingleComponent to each array in components. (Quick exit if mask in NULL_MASK) */
+    /** Apply `correctParityInSingleComponent` to each array in components (quick exit if `parityMask` is `NULL_MASK`). */
     private static correctParityInComponentArrays;
     /**
-     * Collect arrays gathering faces by connected component.
-     * @param graph graph to inspect
-     * @param parityEdgeTester (optional) function to test if an edge is a parity change (e.g., a boundary edge).
-     * @param parityMask (optional, along with parityEdgeTester) mask to apply indicating parity.  If this is Mask.NULL_MASK, there is no record of parity.
+     * Collect connected components of the graph (via Depth First Search).
+     * @param graph graph to inspect.
+     * @param parityEdgeTester (optional) function to test if an edge is adjacent to two faces of opposite parity,
+     * e.g., a boundary edge that separates an "interior" face and an "exterior" face. If `parityEdgeTester` is not
+     * supplied and `parityMask` is supplied, the default parity rule is to alternate parity state in a "bullseye"
+     * pattern starting at the seed face, with each successive concentric ring of faces at constant topological
+     * distance from the seed face receiving the opposite parity state of the previous ring.
+     * @param parityMask (optional) mask to apply to the first face and faces that share the same parity as the
+     * first face, as determined by the parity rule. If this is `NULL_MASK`, there is no record of parity. If
+     * (non-null) parity mask is given, on return it is entirely set or entirely clear around each face.
+     * @returns the components of the graph, each component represented by an array of nodes, one node per face
+     * of the component. In other words, entry [i][j] is a HalfEdge in the j_th face loop of the i_th component.
      */
     static collectConnectedComponentsWithExteriorParityMasks(graph: HalfEdgeGraph, parityEdgeTester: HalfEdgeTestObject | undefined, parityMask?: HalfEdgeMask): HalfEdge[][];
     /**
-     * Test if (x,y) is inside (1), on an edge (0) or outside (-1) a face.
-     * @param seedNode any node on the face loop
-     * @param x x coordinate of test point.
-     * @param y y coordinate of test point.
+     * Test if test point (xTest,yTest) is inside/outside a face or on an edge.
+     * @param seedNode any node on the face loop.
+     * @param xTest x coordinate of the test point.
+     * @param yTest y coordinate of the test point.
+     * @returns 0 if ON, 1 if IN, -1 if OUT.
      */
-    static pointInOrOnFaceXY(seedNode: HalfEdge, x: number, y: number): number | undefined;
+    static pointInOrOnFaceXY(seedNode: HalfEdge, xTest: number, yTest: number): number | undefined;
     /**
-     * Announce nodes that are "extended face boundary" by conditions (usually mask of node and mate) in test functions.
-     * * After each node, the next candidate in reached by looking "around the head vertex loop" for the next boundary.
-     *   * "Around the vertex" from nodeA means
-     *      * First look at nodeA.faceSuccessor;
-     *      * Then look at vertexPredecessor around that vertex loop.
-     * * Each accepted node is passed to announceNode, and marked with the visit mask.
-     * * The counter of the announceEdge function is zero for the first edge, then increases with each edge.
+     * Collect boundary edges starting from `seed`.
+     * * If `seed` is not a boundary node or is already visited, the function exists early.
      * @param seed start node.
-     * @param isBoundaryEdge
-     * @param announceEdge
+     * @param visitMask mask to set on processed nodes.
+     * @param isBoundaryEdge function to test if an edge in a boundary edge.
+     * @param announceEdgeInBoundary callback invoked on each edge in the boundary loop in order. The counter is zero
+     * for the first edge, and incremented with each successive edge.
      */
-    static collectExtendedBoundaryLoopFromSeed(seed: HalfEdge, visitMask: HalfEdgeMask, isBoundaryEdge: HalfEdgeToBooleanFunction, announceEdge: (edge: HalfEdge, counter: number) => void): void;
+    static collectExtendedBoundaryLoopFromSeed(seed: HalfEdge, visitMask: HalfEdgeMask, isBoundaryEdge: HalfEdgeToBooleanFunction, announceEdgeInBoundary: (edge: HalfEdge, counter: number) => void): void;
     /**
-     * Collect arrays of nodes "around the boundary" of a graph with extraneous (non-boundary) edges.
-     * * The "boundary" is nodes that do NOT have the exterior mask, but whose mates DO have the exterior mask.
-     * * After each node, the next candidate in reached by looking "around the head vertex loop" for the next boundary.
-     *   * "Around the vertex" from nodeA means
-     *      * First look at nodeA.faceSuccessor;
-     *      * Then look at vertexPredecessor around that vertex loop.
-     * * Each accepted node is passed to announceNode, and marked with the visit mask.
-     * @param seed start node.
-     * @param isBoundaryNode
-     * @param announceNode
+     * Collect boundary edges in the graph.
+     * * A boundary edge is defined by `exteriorMask` being set on only its "exterior" edge mate.
+     * * Each boundary edge is identified in the output by its edge mate that lacks `exteriorMask`.
+     * * Each inner array is ordered in the output so that its boundary edges form a connected path. If `exteriorMask`
+     * is preset consistently around each "exterior" face, these paths are loops.
+     * @param graph the graph to query
+     * @param exteriorMask mask preset on exactly one side of boundary edges
+     * @returns array of boundary loops, each loop an array of the unmasked mates of boundary edges
      */
     static collectExtendedBoundaryLoopsInGraph(graph: HalfEdgeGraph, exteriorMask: HalfEdgeMask): HalfEdge[][];
 }

package/lib/esm/topology/HalfEdgeGraphSearch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HalfEdgeGraphSearch.d.ts","sourceRoot":"","sources":["../../../src/topology/HalfEdgeGraphSearch.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACjH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAChC;AACD;GACG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAAU;IAC9B;;;;OAIG;gBACgB,IAAI,EAAE,YAAY,EAAE,WAAW,GAAE,OAAc;IAIlE,yEAAyE;IAClE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;CAIzC;AAED,qBAAa,mBAAmB;IAE9B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAQxC;;;;OAIG;WACW,mBAAmB,CAAC,uBAAuB,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,gBAAgB,CAAC,EAAE,oBAAoB,GAAG,QAAQ,GAAG,SAAS;IAKrJ;;;;OAIG;WACW,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM;IACpD;;;;;;;;OAQG;WACW,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,eAAe,GAAE,OAAe,EACvG,YAAY,GAAE,oBAAyE,GAAG,iBAAiB,CAAC,QAAQ,CAAC;IAgBvH;;;;;;OAMG;WACW,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,8BAA8B,GAAE,OAAc,EAAE,4BAA4B,SAAI,GAAG,OAAO;IA+B9J;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAsBlC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAgB7C,0GAA0G;IAC1G,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAM7C;;;;;OAKG;WACW,iDAAiD,CAAC,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,GAAG,SAAS,EAAE,UAAU,GAAE,YAAqC,GAAG,QAAQ,EAAE,EAAE;IAcxM;;;;;OAKG;WACW,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IA4B7F;;;;;;;;;;;OAWG;WACW,mCAAmC,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,yBAAyB,EAClI,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI;IAoBzD;;;;;;;;;;;OAWG;WACW,mCAAmC,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,GAAG,QAAQ,EAAE,EAAE;CAiBlH"}
+{"version":3,"file":"HalfEdgeGraphSearch.d.ts","sourceRoot":"","sources":["../../../src/topology/HalfEdgeGraphSearch.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACjH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAKxD,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAChC;AACD,6CAA6C;AAC7C,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,YAAY,CAAU;IAC9B;;;;OAIG;gBACgB,IAAI,EAAE,YAAY,EAAE,WAAW,GAAE,OAAc;IAIlE,0EAA0E;IACnE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO;CAGzC;AACD,+DAA+D;AAC/D,qBAAa,mBAAmB;IAC9B;;;;OAIG;WACW,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM;IAGpD;;;;;;OAMG;WACW,sBAAsB,CAClC,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAClC,eAAe,GAAE,OAAe,EAChC,YAAY,GAAE,oBAAyE,GACtF,iBAAiB,CAAC,QAAQ,CAAC;IAa9B;;;;OAIG;WACW,mBAAmB,CAC/B,uBAAuB,EAAE,aAAa,GAAG,QAAQ,EAAE,EAAE,gBAAgB,CAAC,EAAE,oBAAoB,GAC3F,QAAQ,GAAG,SAAS;IAIvB;;;;;;OAMG;WACW,iBAAiB,CAC7B,MAAM,EAAE,aAAa,GAAG,QAAQ,EAAE,EAClC,8BAA8B,GAAE,OAAc,EAC9C,4BAA4B,GAAE,MAAU,GACvC,OAAO;IA6BV;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IASxC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IA2BlC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAgB7C,sHAAsH;IACtH,OAAO,CAAC,MAAM,CAAC,8BAA8B;IAM7C;;;;;;;;;;;;;OAaG;WACW,iDAAiD,CAC7D,KAAK,EAAE,aAAa,EACpB,gBAAgB,EAAE,kBAAkB,GAAG,SAAS,EAChD,UAAU,GAAE,YAAqC,GAChD,QAAQ,EAAE,EAAE;IAgBf;;;;;;OAMG;WACW,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IA2BrG;;;;;;;;OAQG;WACW,mCAAmC,CAC/C,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,YAAY,EACvB,cAAc,EAAE,yBAAyB,EACzC,sBAAsB,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAChE,IAAI;IAoBP;;;;;;;;;OASG;WACW,mCAAmC,CAAC,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,GAAG,QAAQ,EAAE,EAAE;CAkBlH"}

package/lib/esm/topology/HalfEdgeGraphSearch.js

@@ -5,14 +5,14 @@
 /** @packageDocumentation
  * @module Topology
  */
+import { Range1d } from "../geometry3d/Range";
 import { HalfEdgeGraph, HalfEdgeMask } from "./Graph";
 import { SignedDataSummary } from "./SignedDataSummary";
 import { XYParitySearchContext } from "./XYParitySearchContext";
-/**
- */
+/** Class to test match of half edge mask. */
 export class HalfEdgeMaskTester {
     /**
-     *
+     * Constructor
      * @param mask mask to test in `testEdge` function
      * @param targetValue value to match for true return
      */
@@ -20,47 +20,27 @@ export class HalfEdgeMaskTester {
         this._targetMask = mask;
         this._targetValue = targetValue;
     }
-    /** Return true if the value of the targetMask matches the targetValue */
+    /** Return true if the value of the targetMask matches the targetValue. */
     testEdge(edge) {
         return edge.isMaskSet(this._targetMask) === this._targetValue;
     }
 }
-// Search services for HalfEdgeGraph
+/** Class for different types of searches for HalfEdgeGraph. */
 export class HalfEdgeGraphSearch {
     /**
-     * * for each node of face, set the mask push to allNodesStack
-     * * push the faceSeed on onePerFaceStack[]
-     */
-    static pushAndMaskAllNodesInFace(faceSeed, mask, allNodeStack, onePerFaceStack) {
-        onePerFaceStack.push(faceSeed);
-        faceSeed.collectAroundFace((node) => {
-            node.setMask(mask);
-            allNodeStack.push(node);
-        });
-    }
-    /**
-     * Search an array of faceSeed nodes for the face with the most negative area.
-     * @param oneCandidateNodePerFace array containing one node from each face to be considered.
-     * @returns node on the minimum area face, or undefined if no such face (e.g., all faces have zero area).
-     */
-    static findMinimumAreaFace(oneCandidateNodePerFace, faceAreaFunction) {
-        const summary = HalfEdgeGraphSearch.collectFaceAreaSummary(oneCandidateNodePerFace, false, faceAreaFunction);
-        return summary.largestNegativeItem;
-    }
-    /**
-     * static method for face area computation -- useful as function parameter in collect FaceAreaSummary.
-     * * This simply calls `node.signedFaceArea ()`
+     * Static method for face area computation -- useful as function parameter in `collectFaceAreaSummary`.
+     * * This simply calls `node.signedFaceArea()`
      * @param node instance for signedFaceArea call.
      */
-    static signedFaceArea(node) { return node.signedFaceArea(); }
+    static signedFaceArea(node) {
+        return node.signedFaceArea();
+    }
     /**
-     *
-     * Return a summary structure data about face (or other numeric quantity if the caller's areaFunction returns other value)
-     * * The default areaFunction computes area of polygonal face.
+     * Return a summary of face data (e.g., area) as computed by the callback on the faces of the graph.
      * * Callers with curved edge graphs must supply their own area function.
-     * @param source graph or array of nodes to examine
-     * @param collectAllNodes flag to pass to the SignedDataSummary constructor to control collection of nodes.
-     * @param areaFunction function to all to obtain area (or other numeric value)
+     * @param source graph or array of nodes to examine.
+     * @param collectAllNodes flag to pass to the `SignedDataSummary` constructor to control collection of nodes.
+     * @param areaFunction function to obtain area (or other numeric value). Default computes polygonal face area.
      */
     static collectFaceAreaSummary(source, collectAllNodes = false, areaFunction = (node) => HalfEdgeGraphSearch.signedFaceArea(node)) {
         const result = new SignedDataSummary(collectAllNodes);
@@ -76,10 +56,19 @@ export class HalfEdgeGraphSearch {
         return result;
     }
     /**
-     * * Test if the graph is triangulated.
-     * * Return false if:
-     *   * Positive area face with more than 3 edges
-     *   * more than 1 negative area face with `allowMultipleNegativeAreaFaces` false
+     * Search the graph for the face with the most negative area.
+     * @param oneCandidateNodePerFace graph or an array containing one node from each face to be considered.
+     * @returns node on the negative area face with largest absolute area, or `undefined` if no negative area face.
+     */
+    static findMinimumAreaFace(oneCandidateNodePerFace, faceAreaFunction) {
+        const summary = HalfEdgeGraphSearch.collectFaceAreaSummary(oneCandidateNodePerFace, false, faceAreaFunction);
+        return summary.largestNegativeItem;
+    }
+    /**
+     * Test if the graph is triangulated.
+     * * Return `false` if:
+     *   * number of positive area faces with more than 3 edges is larger than `numPositiveExceptionsAllowed`.
+     *   * graph has more than 1 negative area face when `allowMultipleNegativeAreaFaces` is `false`.
      * * 2-edge faces are ignored.
      */
     static isTriangulatedCCW(source, allowMultipleNegativeAreaFaces = true, numPositiveExceptionsAllowed = 0) {
@@ -113,24 +102,41 @@ export class HalfEdgeGraphSearch {
         return true;
     }
     /**
-     * Search to all accessible faces from given seed.
-     * * The returned array contains one representative node in each face of the connected component.
-     * * If (nonnull) parity mask is given, on return:
-     *    * It is entirely set or entirely clear around each face
-     *    * It is entirely set on all faces that are an even number of face-to-face steps away from the seed.
-     *    * It is entirely clear on all faces that are an odd number of face-to-face steps away from the seed.
-     * @param seedEdge first edge to search.
+     * Process a face during graph traversal.
+     * @param faceSeed a node in the face.
+     * @param mask mask to set on each node of the face.
+     * @param allNodeStack array appended with each node of the face.
+     * @param onePerFaceStack array appended with `faceSeed`.
+     */
+    static pushAndMaskAllNodesInFace(faceSeed, mask, allNodeStack, onePerFaceStack) {
+        onePerFaceStack.push(faceSeed);
+        faceSeed.collectAroundFace((node) => {
+            node.setMask(mask);
+            allNodeStack.push(node);
+        });
+    }
+    /**
+     * Traverse (via Depth First Search) to all accessible faces from the given seed.
+     * @param faceSeed first node to start the traverse.
      * @param visitMask mask applied to all faces as visited.
-     * @param parityMask mask to apply (a) to first face, (b) to faces with alternating parity during the search.
+     * @param parityEdgeTester function to test if an edge is adjacent to two faces of opposite parity, e.g., a boundary
+     * edge that separates an "interior" face and an "exterior" face. If `parityEdgeTester` is not supplied and `parityMask`
+     * is supplied, the default parity rule is to alternate parity state in a "bullseye" pattern starting at the seed face,
+     * with each successive concentric ring of faces at constant topological distance from the seed face receiving the
+     * opposite parity state of the previous ring.
+     * @param parityMask mask to apply to the first face and faces that share the same parity as the first face, as
+     * determined by the parity rule. If this is `NULL_MASK`, there is no record of parity. If (non-null) parity mask
+     * is given, on return it is entirely set or entirely clear around each face.
+     * @returns an array that contains one representative node in each face of the connected component.
      */
-    static parityFloodFromSeed(seedEdge, visitMask, parityEdgeTester, parityMask) {
+    static parityFloodFromSeed(faceSeed, visitMask, parityEdgeTester, parityMask) {
         const faces = [];
-        if (seedEdge.isMaskSet(visitMask))
-            return faces; // empty
+        if (faceSeed.isMaskSet(visitMask))
+            return faces; // empty array
         const allMasks = parityMask | visitMask;
         const stack = [];
-        // arbitrarily call the seed face exterior ... others will alternate as visited.
-        HalfEdgeGraphSearch.pushAndMaskAllNodesInFace(seedEdge, allMasks, stack, faces); // Start with exterior as mask
+        // the seed face is arbitrarily assigned the parity mask
+        HalfEdgeGraphSearch.pushAndMaskAllNodesInFace(faceSeed, allMasks, stack, faces);
         while (stack.length > 0) {
             const p = stack.pop();
             const mate = p.edgeMate;
@@ -146,113 +152,123 @@ export class HalfEdgeGraphSearch {
         return faces;
     }
     /**
-     * * Search the given faces for the one with the minimum area.
-     * * If the mask in that face is OFF, toggle it on (all half edges of) all the faces.
+     * * Correct the parity mask in the faces of a component.
+     * * It is assumed that the parity mask is applied _consistently_ throughout the supplied faces, but maybe
+     * not _correctly_.
+     * * A consistently applied parity mask is "correct" if it is set on the negative area ("exterior") face of
+     * a connected component.
+     * * This method finds a face with negative area and toggles the mask throughout the input faces if this face
+     * lacks the parity mask.
      * * In a properly merged planar subdivision there should be only one true negative area face per component.
-     * @param graph parent graph
-     * @param parityMask mask which was previously set with alternating parity, but with an arbitrary start face.
-     * @param faces array of faces to search.
      */
-    static correctParityInSingleComponent(_graph, mask, faces) {
+    static correctParityInSingleComponent(parityMask, faces) {
         const exteriorHalfEdge = HalfEdgeGraphSearch.findMinimumAreaFace(faces);
         if (!exteriorHalfEdge) {
+            // graph has all degenerate faces; do nothing
         }
-        else if (exteriorHalfEdge.isMaskSet(mask)) {
-            // all should be well .. nothing to do.
+        else if (exteriorHalfEdge.isMaskSet(parityMask)) {
+            // all should be well; nothing to do
         }
         else {
-            // TOGGLE around the face (assuming all are consistent with the seed)
             for (const faceSeed of faces) {
-                if (faceSeed.isMaskSet(mask)) {
-                    faceSeed.clearMaskAroundFace(mask);
+                if (faceSeed.isMaskSet(parityMask)) {
+                    faceSeed.clearMaskAroundFace(parityMask);
                 }
                 else {
-                    faceSeed.setMaskAroundFace(mask);
+                    faceSeed.setMaskAroundFace(parityMask);
                 }
             }
         }
     }
-    /** Apply correctParityInSingleComponent to each array in components. (Quick exit if mask in NULL_MASK) */
-    static correctParityInComponentArrays(graph, mask, components) {
-        if (mask === HalfEdgeMask.NULL_MASK)
+    /** Apply `correctParityInSingleComponent` to each array in components (quick exit if `parityMask` is `NULL_MASK`). */
+    static correctParityInComponentArrays(parityMask, components) {
+        if (parityMask === HalfEdgeMask.NULL_MASK)
             return;
         for (const facesInComponent of components)
-            HalfEdgeGraphSearch.correctParityInSingleComponent(graph, mask, facesInComponent);
+            HalfEdgeGraphSearch.correctParityInSingleComponent(parityMask, facesInComponent);
     }
     /**
-     * Collect arrays gathering faces by connected component.
-     * @param graph graph to inspect
-     * @param parityEdgeTester (optional) function to test if an edge is a parity change (e.g., a boundary edge).
-     * @param parityMask (optional, along with parityEdgeTester) mask to apply indicating parity.  If this is Mask.NULL_MASK, there is no record of parity.
+     * Collect connected components of the graph (via Depth First Search).
+     * @param graph graph to inspect.
+     * @param parityEdgeTester (optional) function to test if an edge is adjacent to two faces of opposite parity,
+     * e.g., a boundary edge that separates an "interior" face and an "exterior" face. If `parityEdgeTester` is not
+     * supplied and `parityMask` is supplied, the default parity rule is to alternate parity state in a "bullseye"
+     * pattern starting at the seed face, with each successive concentric ring of faces at constant topological
+     * distance from the seed face receiving the opposite parity state of the previous ring.
+     * @param parityMask (optional) mask to apply to the first face and faces that share the same parity as the
+     * first face, as determined by the parity rule. If this is `NULL_MASK`, there is no record of parity. If
+     * (non-null) parity mask is given, on return it is entirely set or entirely clear around each face.
+     * @returns the components of the graph, each component represented by an array of nodes, one node per face
+     * of the component. In other words, entry [i][j] is a HalfEdge in the j_th face loop of the i_th component.
      */
     static collectConnectedComponentsWithExteriorParityMasks(graph, parityEdgeTester, parityMask = HalfEdgeMask.NULL_MASK) {
+        // Illustration of the algorithm can be found at geometry/internaldocs/Graph.md
         const components = [];
         const visitMask = HalfEdgeMask.VISITED;
         const allMasks = parityMask | visitMask;
         graph.clearMask(allMasks);
         for (const faceSeed of graph.allHalfEdges) {
-            if (!faceSeed.isMaskSet(HalfEdgeMask.VISITED)) {
+            if (!faceSeed.isMaskSet(visitMask)) {
                 const newFaces = HalfEdgeGraphSearch.parityFloodFromSeed(faceSeed, visitMask, parityEdgeTester, parityMask);
+                // parityFloodFromSeed does not return an empty array because it is called on an unvisited faceSeed
                 components.push(newFaces);
             }
         }
-        HalfEdgeGraphSearch.correctParityInComponentArrays(graph, parityMask, components);
+        HalfEdgeGraphSearch.correctParityInComponentArrays(parityMask, components);
         return components;
     }
     /**
-     * Test if (x,y) is inside (1), on an edge (0) or outside (-1) a face.
-     * @param seedNode any node on the face loop
-     * @param x x coordinate of test point.
-     * @param y y coordinate of test point.
+     * Test if test point (xTest,yTest) is inside/outside a face or on an edge.
+     * @param seedNode any node on the face loop.
+     * @param xTest x coordinate of the test point.
+     * @param yTest y coordinate of the test point.
+     * @returns 0 if ON, 1 if IN, -1 if OUT.
      */
-    static pointInOrOnFaceXY(seedNode, x, y) {
-        const context = new XYParitySearchContext(x, y);
-        // walk around looking for an accepted node to start the search (seedNode is usually ok!)
+    static pointInOrOnFaceXY(seedNode, xTest, yTest) {
+        const context = new XYParitySearchContext(xTest, yTest);
+        // walk around looking for an accepted node to start the search (seedNode is usually ok)
         let nodeA = seedNode;
         let nodeB = seedNode.faceSuccessor;
         for (;; nodeA = nodeB) {
             if (context.tryStartEdge(nodeA.x, nodeA.y, nodeB.x, nodeB.y))
                 break;
             if (nodeB === seedNode) {
-                // umm.. the face is all on the x axis?
-                return context.classifyCounts();
+                // the test point and the face are all on line "y = yTest"
+                const range = Range1d.createXX(nodeB.x, nodeB.faceSuccessor.x);
+                return range.containsX(xTest) ? 0 : -1;
             }
             nodeB = nodeA.faceSuccessor;
         }
-        // nodeB is the real start node for search ... emit ends of each edge around the face,
-        //   stopping after emitting nodeB as an edge end.
-        let node = nodeB.faceSuccessor;
+        // nodeB is the real start node for search, so stop when we revisit it. For each edge, accumulate parity and hits
+        let nodeC = nodeB.faceSuccessor;
         for (;;) {
-            if (!context.advance(node.x, node.y)) {
+            if (!context.advance(nodeC.x, nodeC.y)) {
                 return context.classifyCounts();
             }
-            if (node === nodeB)
+            if (nodeC === nodeB)
                 break;
-            node = node.faceSuccessor;
+            nodeC = nodeC.faceSuccessor;
         }
         return context.classifyCounts();
     }
     /**
-     * Announce nodes that are "extended face boundary" by conditions (usually mask of node and mate) in test functions.
-     * * After each node, the next candidate in reached by looking "around the head vertex loop" for the next boundary.
-     *   * "Around the vertex" from nodeA means
-     *      * First look at nodeA.faceSuccessor;
-     *      * Then look at vertexPredecessor around that vertex loop.
-     * * Each accepted node is passed to announceNode, and marked with the visit mask.
-     * * The counter of the announceEdge function is zero for the first edge, then increases with each edge.
+     * Collect boundary edges starting from `seed`.
+     * * If `seed` is not a boundary node or is already visited, the function exists early.
      * @param seed start node.
-     * @param isBoundaryEdge
-     * @param announceEdge
+     * @param visitMask mask to set on processed nodes.
+     * @param isBoundaryEdge function to test if an edge in a boundary edge.
+     * @param announceEdgeInBoundary callback invoked on each edge in the boundary loop in order. The counter is zero
+     * for the first edge, and incremented with each successive edge.
      */
-    static collectExtendedBoundaryLoopFromSeed(seed, visitMask, isBoundaryEdge, announceEdge) {
+    static collectExtendedBoundaryLoopFromSeed(seed, visitMask, isBoundaryEdge, announceEdgeInBoundary) {
         let counter = 0;
         while (!seed.getMask(visitMask) && isBoundaryEdge(seed)) {
-            announceEdge(seed, counter++);
+            announceEdgeInBoundary(seed, counter++);
             seed.setMask(visitMask);
             const vertexBase = seed.faceSuccessor;
             let candidateAroundVertex = vertexBase;
             for (;;) {
-                if (candidateAroundVertex.getMask(visitMask))
+                if (candidateAroundVertex.getMask(visitMask)) // end of boundary loop
                     return;
                 if (isBoundaryEdge(candidateAroundVertex)) {
                     seed = candidateAroundVertex;
@@ -260,23 +276,22 @@ export class HalfEdgeGraphSearch {
                 }
                 candidateAroundVertex = candidateAroundVertex.vertexPredecessor;
                 if (candidateAroundVertex === vertexBase)
-                    break;
+                    break; // prevent infinite loop in case exteriorMask is not set on the edge mate of the boundary edge
             }
         }
     }
     /**
-     * Collect arrays of nodes "around the boundary" of a graph with extraneous (non-boundary) edges.
-     * * The "boundary" is nodes that do NOT have the exterior mask, but whose mates DO have the exterior mask.
-     * * After each node, the next candidate in reached by looking "around the head vertex loop" for the next boundary.
-     *   * "Around the vertex" from nodeA means
-     *      * First look at nodeA.faceSuccessor;
-     *      * Then look at vertexPredecessor around that vertex loop.
-     * * Each accepted node is passed to announceNode, and marked with the visit mask.
-     * @param seed start node.
-     * @param isBoundaryNode
-     * @param announceNode
+     * Collect boundary edges in the graph.
+     * * A boundary edge is defined by `exteriorMask` being set on only its "exterior" edge mate.
+     * * Each boundary edge is identified in the output by its edge mate that lacks `exteriorMask`.
+     * * Each inner array is ordered in the output so that its boundary edges form a connected path. If `exteriorMask`
+     * is preset consistently around each "exterior" face, these paths are loops.
+     * @param graph the graph to query
+     * @param exteriorMask mask preset on exactly one side of boundary edges
+     * @returns array of boundary loops, each loop an array of the unmasked mates of boundary edges
      */
     static collectExtendedBoundaryLoopsInGraph(graph, exteriorMask) {
+        // Illustration of the algorithm can be found at geometry/internaldocs/Graph.md
         const loops = [];
         const visitMask = graph.grabMask(true);
         const isBoundaryEdge = (edge) => {