@itwin/ecschema-rpcinterface-tests 4.4.0-dev.16 → 4.4.0-dev.17

package/lib/dist/bundled-tests.js

@@ -250254,6 +250254,22 @@ class Sample {
             }
         }
     }
+    /** Create a point on the polar parametric curve r = cos(a * theta), aka "rose".
+     * @param theta angle
+     * @param a period multiplier. If odd, this is the petal count; if even, twice the number of petals.
+     * @param z z-coordinate for output
+    */
+    static createRosePoint3d(theta, a, z = 0) {
+        const r = Math.cos(a * theta);
+        return _geometry3d_Point3dVector3d__WEBPACK_IMPORTED_MODULE_1__.Point3d.create(r * Math.cos(theta), r * Math.sin(theta), z);
+    }
+    /** Create a point on the polar parametric curve r = cos(a * theta), aka "rose".
+     * @param theta angle
+     * @param a period multiplier. If odd, this is the petal count; if even, twice the number of petals.
+    */
+    static createRosePoint2d(theta, a) {
+        return _geometry3d_Point2dVector2d__WEBPACK_IMPORTED_MODULE_3__.Point2d.createFrom(Sample.createRosePoint3d(theta, a));
+    }
     /**
      * Create a mesh surface from samples of a smooth function over [0,1]x[0,1].
      * @param size grid size; the number of intervals on each side of the unit square domain.
@@ -254827,15 +254843,15 @@ var HalfEdgeMask;
      * * A boundary edge with interior to one side, exterior to the other, will have EXTERIOR only on the outside.
      * * An edge inserted "within a purely exterior face" can have EXTERIOR on both sides.
      * * An interior edge (such as added during triangulation) will have no EXTERIOR bits.
-     * * Visualization can be found at geometry/internaldocs/Graph.md
-     */
+    */
+    // Visualization can be found at geometry/internaldocs/Graph.md
     HalfEdgeMask[HalfEdgeMask["EXTERIOR"] = 1] = "EXTERIOR";
     /**
      * Mask commonly set (on both sides) of original geometry edges that are transition from outside to inside.
      * * At the moment of creating an edge from primary user boundary loop coordinates, the fact that an edge is BOUNDARY
      * is often clear even though there is uncertainty about which side should be EXTERIOR.
-     * * Visualization can be found at geometry/internaldocs/Graph.md
      */
+    // Visualization can be found at geometry/internaldocs/Graph.md
     HalfEdgeMask[HalfEdgeMask["BOUNDARY_EDGE"] = 2] = "BOUNDARY_EDGE";
     /**
      * Mask commonly set (on both sides) of original geometry edges, but NOT indicating that the edge is certainly a
@@ -256402,6 +256418,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   "HalfEdgeGraphSearch": () => (/* binding */ HalfEdgeGraphSearch),
 /* harmony export */   "HalfEdgeMaskTester": () => (/* binding */ HalfEdgeMaskTester)
 /* harmony export */ });
+/* harmony import */ var _geometry3d_Range__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(/*! ../geometry3d/Range */ "../../core/geometry/lib/esm/geometry3d/Range.js");
 /* harmony import */ var _Graph__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./Graph */ "../../core/geometry/lib/esm/topology/Graph.js");
 /* harmony import */ var _SignedDataSummary__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./SignedDataSummary */ "../../core/geometry/lib/esm/topology/SignedDataSummary.js");
 /* harmony import */ var _XYParitySearchContext__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(/*! ./XYParitySearchContext */ "../../core/geometry/lib/esm/topology/XYParitySearchContext.js");
@@ -256415,11 +256432,11 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
-/**
- */
+
+/** Class to test match of half edge mask. */
 class HalfEdgeMaskTester {
     /**
-     *
+     * Constructor
      * @param mask mask to test in `testEdge` function
      * @param targetValue value to match for true return
      */
@@ -256427,47 +256444,27 @@ 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. */
 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__WEBPACK_IMPORTED_MODULE_0__.SignedDataSummary(collectAllNodes);
@@ -256483,10 +256480,19 @@ 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) {
@@ -256520,24 +256526,41 @@ 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.
-     * @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.
+     * 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 parityFloodFromSeed(seedEdge, visitMask, parityEdgeTester, parityMask) {
+    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 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(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;
@@ -256553,113 +256576,123 @@ 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 === _Graph__WEBPACK_IMPORTED_MODULE_1__.HalfEdgeMask.NULL_MASK)
+    /** Apply `correctParityInSingleComponent` to each array in components (quick exit if `parityMask` is `NULL_MASK`). */
+    static correctParityInComponentArrays(parityMask, components) {
+        if (parityMask === _Graph__WEBPACK_IMPORTED_MODULE_1__.HalfEdgeMask.NULL_MASK)
             return;
         for (const facesInComponent of components)
-            HalfEdgeGraphSearch.correctParityInSingleComponent(graph, mask, 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.
+            HalfEdgeGraphSearch.correctParityInSingleComponent(parityMask, facesInComponent);
+    }
+    /**
+     * 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 = _Graph__WEBPACK_IMPORTED_MODULE_1__.HalfEdgeMask.NULL_MASK) {
+        // Illustration of the algorithm can be found at geometry/internaldocs/Graph.md
         const components = [];
         const visitMask = _Graph__WEBPACK_IMPORTED_MODULE_1__.HalfEdgeMask.VISITED;
         const allMasks = parityMask | visitMask;
         graph.clearMask(allMasks);
         for (const faceSeed of graph.allHalfEdges) {
-            if (!faceSeed.isMaskSet(_Graph__WEBPACK_IMPORTED_MODULE_1__.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__WEBPACK_IMPORTED_MODULE_2__.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__WEBPACK_IMPORTED_MODULE_2__.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 = _geometry3d_Range__WEBPACK_IMPORTED_MODULE_3__.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;
@@ -256667,23 +256700,22 @@ 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) => {
@@ -259168,10 +259200,10 @@ __webpack_require__.r(__webpack_exports__);
 /**
  * Class to accumulate statistics about a stream of signed numbers with tag items.
  * * All sums, counts, extrema, and item values are initialized to zero in the constructor.
- * * Each call to `announceItem (item, value)` updates the various sums, counts, and extrema.
+ * * Each call to `announceItem(item, value)` updates the various sums, counts, and extrema.
  */
 class SignedDataSummary {
-    /** setup with zero sums and optional arrays */
+    /** Setup with zero sums and optional arrays. */
     constructor(createArrays) {
         this.positiveSum = this.negativeSum = 0.0;
         this.numPositive = this.numNegative = this.numZero = 0.0;
@@ -259182,7 +259214,7 @@ class SignedDataSummary {
             this.zeroItemArray = [];
         }
     }
-    /** update with an item and its data value. */
+    /** Update with an item and its data value. */
     announceItem(item, data) {
         if (data < 0) {
             this.numNegative++;
@@ -260407,127 +260439,129 @@ __webpack_require__.r(__webpack_exports__);
  * @module Topology
  */
 /**
- * * XYParitySearchContext is an internal class for callers that can feed points (without extracting to array structures)
+ * `XYParitySearchContext` is an internal class for callers that can feed points (without extracting to array structures)
  * * Most will be via static methods which handle a specific data source.
- *   * PolygonOps.classifyPointInPolygon (x,y,points: XAndY[])
- *   * HalfEdgeGraphSearch.pointInOrOnFaceXY (halfEdgeOnFace, x, y)
+ *   * PolygonOps.classifyPointInPolygon(x,y,points: XAndY[])
+ *   * HalfEdgeGraphSearch.pointInOrOnFaceXY(halfEdgeOnFace, x, y)
  * Use pattern:
- * * Caller must be able walk around polygon producing x,y coordinates (possibly transformed from actual polygon)
+ * * Caller must be able to walk around polygon producing x,y coordinates (possibly transformed from actual polygon).
  * * Caller announce edges to tryStartEdge until finding one acceptable to the search.
  * * Caller then passes additional points up to and including both x0,y0 and x1, y1 of the accepted start edge.
  * Call sequence is:
- *    `context = new XYParitySearchContext`
- *    `repeat {  acquire edge (x0,y0) (x1,y1)} until context.tryStartEdge (x0,y0,x1,y1);`
- *    `for each (x,y) beginning AFTER x1,y1 and ending with (x1,y1) context.advance (x,y)`
- *  `return context.classifyCounts ();`
+ *   * `context = new XYParitySearchContext`
+ *   * `repeat { acquire edge (x0,y0) (x1,y1) } until context.tryStartEdge(x0,y0,x1,y1);`
+ *   * `for each (x,y) beginning AFTER x1,y1 and ending with (x1,y1) context.advance (x,y)`
+ *   * `return context.classifyCounts();`
  */
 class XYParitySearchContext {
     /**
      * Create a new searcher for specified test point.
-     * @param xTest x coordinate of test point
-     * @param yTest y coordinate of test point
+     * @param xTest x coordinate of test point.
+     * @param yTest y coordinate of test point.
      */
     constructor(xTest, yTest) {
         this.xTest = xTest;
         this.yTest = yTest;
-        this.u0 = this.v0 = this.u1 = this.v1 = 0; // Not valid for search -- caller must satisfy tryStartEdge !!!
+        this.u0 = this.v0 = this.u1 = this.v1 = 0; // not valid for search; caller must satisfy tryStartEdge
         this.numLeftCrossing = this.numRightCrossing = 0;
         this.numHit = 0;
     }
-    /**
-     * test if x,y is a safe first coordinate to start the search.
-     * * safe start must have non-zero y so that final point test (return to x0,y0) does not need look back for exact crossing logic.
-     * @param x
-     * @param y
-     */
+    /** Test if parity processing can begin with this edge. */
     tryStartEdge(x0, y0, x1, y1) {
         if (y0 !== this.yTest) {
             this.u0 = x0 - this.xTest;
             this.v0 = y0 - this.yTest;
             this.u1 = x1 - this.xTest;
             this.v1 = y1 - this.yTest;
-            return true;
+            return true; // we won't need wraparound logic to process the final edge ending at (x0,y0)
         }
         return false;
     }
-    /** Return true if parity accumulation proceeded normally.
-     * Return false if interrupted for exact hit.
-     */
-    advance(x, y) {
-        const u = x - this.xTest;
-        const v = y - this.yTest;
-        const p = v * this.v1;
+    /** Update local coordinates: the current edge becomes the previous edge. */
+    updateUV01(u2, v2) {
+        this.u0 = this.u1;
+        this.v0 = this.v1;
+        this.u1 = u2;
+        this.v1 = v2;
+        return true;
+    }
+    /**
+     * Process the current edge ending at (x2,y2).
+     * * Accumulate left/right parity of the test point wrt to the polygon. These counts track the number of polygon crossings
+     *   of the left and right horizontal rays emanating from the test point. After all edges are processed, if either count is
+     *   odd/even, the test point is inside/outside the polygon (see [[classifyCounts]]).
+     * * Check whether the test point lies on the edge.
+     * @returns whether caller should continue processing with the next edge. In particular, `false` if we have an exact hit.
+     */
+    advance(x2, y2) {
+        // In this method we use local u,v coordinates obtained by translating the test point to the origin.
+        // This simplifies our computations:
+        // * left (right) parity is incremented if the current edge crosses the u-axis at u<0 (u>0)
+        // * we have an exact hit if the current edge crosses the u-axis at u=0
+        const u2 = x2 - this.xTest;
+        const v2 = y2 - this.yTest;
+        const p = v2 * this.v1;
         if (p > 0) {
-            // The common case -- skittering along above or below the x axis . . .
-            this.u0 = this.u1;
-            this.v0 = this.v1;
-            this.u1 = u;
-            this.v1 = v;
-            return true;
+            // Current edge does not cross u-axis.
+            return this.updateUV01(u2, v2);
         }
         if (p < 0) {
-            // crossing within (u1,v1) to (u,v)
-            // both v values are nonzero and of opposite sign, so this division is safe . . .
-            const fraction = -this.v1 / (v - this.v1);
-            const uCross = this.u1 + fraction * (u - this.u1);
+            // Current edge crosses the u-axis at edge parameter 0 < lambda < 1 by the Intermediate Value Theorem.
+            // Solve for lambda in 0 = v1 + lambda (v2 - v1), then use it to compute the u-value of the crossing.
+            const lambda = -this.v1 / (v2 - this.v1);
+            const uCross = this.u1 + lambda * (u2 - this.u1);
             if (uCross === 0.0) {
-                this.numHit++;
+                this.numHit++; // Current edge crosses at the origin.
                 return false;
             }
             if (uCross > 0)
                 this.numRightCrossing++;
             else
                 this.numLeftCrossing++;
-            this.u0 = this.u1;
-            this.v0 = this.v1;
-            this.u1 = u;
-            this.v1 = v;
-            return true;
+            return this.updateUV01(u2, v2);
         }
-        // hard stuff -- one or more exact hits . . .
-        if (v === 0.0) {
+        // At this point, at least one endpoint of the current edge lies on the u-axis.
+        if (v2 === 0.0) {
             if (this.v1 === 0.0) {
-                // uh oh -- moving along x axis.  Does it pass through xTest:
-                if (u * this.u1 <= 0.0) {
-                    this.numHit++;
+                if (u2 * this.u1 <= 0.0) {
+                    this.numHit++; // Current edge lies on u-axis and contains the origin.
                     return false;
                 }
-                // quietly moving along the scan line, both xy and x1y1 to same side of test point ...
-                // u0 and u1 remain unchanged !!!
-                this.u1 = u;
-                this.v1 = v;
+                // Current edge lies on the u-axis to one side of the origin.
+                // This edge doesn't contribute to parity computations, so advance past it.
+                this.u1 = u2;
+                this.v1 = v2;
                 return true;
             }
-            // just moved onto the scan line ...
-            this.u0 = this.u1;
-            this.v0 = this.v1;
-            this.u1 = u;
-            this.v1 = v;
-            return true;
+            if (u2 === 0.0) {
+                this.numHit++; // Current edge ends at the origin.
+                return false;
+            }
+            // Current edge ends on the u-axis away from the origin.
+            return this.updateUV01(u2, v2);
         }
-        // fall out with v1 = 0
-        // both v0 and v are nonzero.
-        // any along-0 v values that have passed through are on the same side of xTest, so u1 determines crossing
-        const q = this.v0 * v;
-        if (this.u1 > 0) {
-            if (q < 0)
-                this.numRightCrossing++;
+        // At this point, the current edge starts at the u-axis.
+        if (this.u1 === 0.0) {
+            this.numHit++; // Current edge starts at the origin.
+            return false;
         }
-        else {
-            if (q < 0)
+        // At this point, the current edge starts on the u-axis away from the origin.
+        const q = this.v0 * v2;
+        if (q < 0) {
+            // The current edge and the previous edge lie on opposite sides of the u-axis, so we have a parity change.
+            if (this.u1 > 0)
+                this.numRightCrossing++;
+            else
                 this.numLeftCrossing++;
         }
-        this.u0 = this.u1;
-        this.v0 = this.v1;
-        this.u1 = u;
-        this.v1 = v;
-        return true;
+        // The current edge and the previous edge lie on the same sides of the u-axis, so no parity change.
+        return this.updateUV01(u2, v2);
     }
     /**
      * Return classification as ON, IN, or OUT according to hit and crossing counts.
-     * * Any nonzero hit count is ON
+     * * Any nonzero hit count is ON.
      * * Otherwise IN if left crossing count is odd.
-     * @return 0 if ON, 1 if IN, -1 if OUT
+     * @return 0 if ON, 1 if IN, -1 if OUT.
      */
     classifyCounts() {
         if (this.numHit > 0)
@@ -290240,7 +290274,7 @@ module.exports = JSON.parse('{"name":"axios","version":"0.21.4","description":"P
 /***/ ((module) => {
 
 "use strict";
-module.exports = JSON.parse('{"name":"@itwin/core-frontend","version":"4.4.0-dev.16","description":"iTwin.js frontend components","main":"lib/cjs/core-frontend.js","module":"lib/esm/core-frontend.js","typings":"lib/cjs/core-frontend","license":"MIT","scripts":{"build":"npm run -s copy:public && npm run -s build:cjs && npm run -s build:esm && npm run -s webpackWorkers && npm run -s copy:workers","build:cjs":"npm run -s copy:js:cjs && tsc 1>&2 --outDir lib/cjs","build:esm":"npm run -s copy:js:esm && tsc 1>&2 --module ES2020 --outDir lib/esm","clean":"rimraf lib .rush/temp/package-deps*.json","copy:public":"cpx \\"./src/public/**/*\\" ./lib/public","copy:js:cjs":"cpx \\"./src/**/*.js\\" ./lib/cjs","copy:js:esm":"cpx \\"./src/**/*.js\\" ./lib/esm","copy:workers":"cpx \\"./lib/workers/webpack/parse-imdl-worker.js\\" ./lib/public/scripts","docs":"betools docs --includes=../../generated-docs/extract --json=../../generated-docs/core/core-frontend/file.json --tsIndexFile=./core-frontend.ts --onlyJson --excludes=webgl/**/*,**/map/*.d.ts,**/tile/*.d.ts,**/*-css.ts","extract-api":"betools extract-api --entry=core-frontend && npm run extract-extension-api","extract-extension-api":"eslint -c extraction.eslint.config.js  \\"./src/**/*.ts\\" 1>&2","lint":"eslint -f visualstudio \\"./src/**/*.ts\\" 1>&2","pseudolocalize":"betools pseudolocalize --englishDir ./src/public/locales/en --out ./public/locales/en-PSEUDO","test":"npm run -s webpackTests && certa -r chrome","cover":"npm -s test","test:debug":"certa -r chrome --debug","webpackTests":"webpack --config ./src/test/utils/webpack.config.js 1>&2 && npm run -s webpackTestWorker","webpackTestWorker":"webpack --config ./src/test/worker/webpack.config.js 1>&2 && cpx \\"./lib/test/test-worker.js\\" ./lib/test","webpackWorkers":"webpack --config ./src/workers/ImdlParser/webpack.config.js 1>&2"},"repository":{"type":"git","url":"https://github.com/iTwin/itwinjs-core.git","directory":"core/frontend"},"keywords":["Bentley","BIM","iModel","digital-twin","iTwin"],"author":{"name":"Bentley Systems, Inc.","url":"http://www.bentley.com"},"peerDependencies":{"@itwin/appui-abstract":"workspace:^4.4.0-dev.16","@itwin/core-bentley":"workspace:^4.4.0-dev.16","@itwin/core-common":"workspace:^4.4.0-dev.16","@itwin/core-geometry":"workspace:^4.4.0-dev.16","@itwin/core-orbitgt":"workspace:^4.4.0-dev.16","@itwin/core-quantity":"workspace:^4.4.0-dev.16"},"//devDependencies":["NOTE: All peerDependencies should also be listed as devDependencies since peerDependencies are not considered by npm install","NOTE: All tools used by scripts in this package must be listed as devDependencies"],"devDependencies":{"@itwin/appui-abstract":"workspace:*","@itwin/build-tools":"workspace:*","@itwin/core-bentley":"workspace:*","@itwin/core-common":"workspace:*","@itwin/core-geometry":"workspace:*","@itwin/core-orbitgt":"workspace:*","@itwin/core-quantity":"workspace:*","@itwin/certa":"workspace:*","@itwin/eslint-plugin":"4.0.0-dev.44","@types/chai":"4.3.1","@types/chai-as-promised":"^7","@types/mocha":"^10.0.6","@types/sinon":"^17.0.2","babel-loader":"~8.2.5","babel-plugin-istanbul":"~6.1.1","chai":"^4.3.10","chai-as-promised":"^7.1.1","cpx2":"^3.0.0","eslint":"^8.44.0","glob":"^7.1.2","mocha":"^10.2.0","nyc":"^15.1.0","rimraf":"^3.0.2","sinon":"^17.0.1","source-map-loader":"^4.0.0","typescript":"~5.0.2","typemoq":"^2.1.0","webpack":"^5.76.0"},"//dependencies":["NOTE: these dependencies should be only for things that DO NOT APPEAR IN THE API","NOTE: core-frontend should remain UI technology agnostic, so no react/angular dependencies are allowed"],"dependencies":{"@itwin/cloud-agnostic-core":"^2.1.0","@itwin/object-storage-core":"^2.1.0","@itwin/core-i18n":"workspace:*","@itwin/core-telemetry":"workspace:*","@itwin/webgl-compatibility":"workspace:*","@loaders.gl/core":"^3.1.6","@loaders.gl/draco":"^3.1.6","fuse.js":"^3.3.0","wms-capabilities":"0.4.0"},"nyc":{"extends":"./node_modules/@itwin/build-tools/.nycrc"}}');
+module.exports = JSON.parse('{"name":"@itwin/core-frontend","version":"4.4.0-dev.17","description":"iTwin.js frontend components","main":"lib/cjs/core-frontend.js","module":"lib/esm/core-frontend.js","typings":"lib/cjs/core-frontend","license":"MIT","scripts":{"build":"npm run -s copy:public && npm run -s build:cjs && npm run -s build:esm && npm run -s webpackWorkers && npm run -s copy:workers","build:cjs":"npm run -s copy:js:cjs && tsc 1>&2 --outDir lib/cjs","build:esm":"npm run -s copy:js:esm && tsc 1>&2 --module ES2020 --outDir lib/esm","clean":"rimraf lib .rush/temp/package-deps*.json","copy:public":"cpx \\"./src/public/**/*\\" ./lib/public","copy:js:cjs":"cpx \\"./src/**/*.js\\" ./lib/cjs","copy:js:esm":"cpx \\"./src/**/*.js\\" ./lib/esm","copy:workers":"cpx \\"./lib/workers/webpack/parse-imdl-worker.js\\" ./lib/public/scripts","docs":"betools docs --includes=../../generated-docs/extract --json=../../generated-docs/core/core-frontend/file.json --tsIndexFile=./core-frontend.ts --onlyJson --excludes=webgl/**/*,**/map/*.d.ts,**/tile/*.d.ts,**/*-css.ts","extract-api":"betools extract-api --entry=core-frontend && npm run extract-extension-api","extract-extension-api":"eslint -c extraction.eslint.config.js  \\"./src/**/*.ts\\" 1>&2","lint":"eslint -f visualstudio \\"./src/**/*.ts\\" 1>&2","pseudolocalize":"betools pseudolocalize --englishDir ./src/public/locales/en --out ./public/locales/en-PSEUDO","test":"npm run -s webpackTests && certa -r chrome","cover":"npm -s test","test:debug":"certa -r chrome --debug","webpackTests":"webpack --config ./src/test/utils/webpack.config.js 1>&2 && npm run -s webpackTestWorker","webpackTestWorker":"webpack --config ./src/test/worker/webpack.config.js 1>&2 && cpx \\"./lib/test/test-worker.js\\" ./lib/test","webpackWorkers":"webpack --config ./src/workers/ImdlParser/webpack.config.js 1>&2"},"repository":{"type":"git","url":"https://github.com/iTwin/itwinjs-core.git","directory":"core/frontend"},"keywords":["Bentley","BIM","iModel","digital-twin","iTwin"],"author":{"name":"Bentley Systems, Inc.","url":"http://www.bentley.com"},"peerDependencies":{"@itwin/appui-abstract":"workspace:^4.4.0-dev.17","@itwin/core-bentley":"workspace:^4.4.0-dev.17","@itwin/core-common":"workspace:^4.4.0-dev.17","@itwin/core-geometry":"workspace:^4.4.0-dev.17","@itwin/core-orbitgt":"workspace:^4.4.0-dev.17","@itwin/core-quantity":"workspace:^4.4.0-dev.17"},"//devDependencies":["NOTE: All peerDependencies should also be listed as devDependencies since peerDependencies are not considered by npm install","NOTE: All tools used by scripts in this package must be listed as devDependencies"],"devDependencies":{"@itwin/appui-abstract":"workspace:*","@itwin/build-tools":"workspace:*","@itwin/core-bentley":"workspace:*","@itwin/core-common":"workspace:*","@itwin/core-geometry":"workspace:*","@itwin/core-orbitgt":"workspace:*","@itwin/core-quantity":"workspace:*","@itwin/certa":"workspace:*","@itwin/eslint-plugin":"4.0.0-dev.44","@types/chai":"4.3.1","@types/chai-as-promised":"^7","@types/mocha":"^10.0.6","@types/sinon":"^17.0.2","babel-loader":"~8.2.5","babel-plugin-istanbul":"~6.1.1","chai":"^4.3.10","chai-as-promised":"^7.1.1","cpx2":"^3.0.0","eslint":"^8.44.0","glob":"^7.1.2","mocha":"^10.2.0","nyc":"^15.1.0","rimraf":"^3.0.2","sinon":"^17.0.1","source-map-loader":"^4.0.0","typescript":"~5.0.2","typemoq":"^2.1.0","webpack":"^5.76.0"},"//dependencies":["NOTE: these dependencies should be only for things that DO NOT APPEAR IN THE API","NOTE: core-frontend should remain UI technology agnostic, so no react/angular dependencies are allowed"],"dependencies":{"@itwin/cloud-agnostic-core":"^2.1.0","@itwin/object-storage-core":"^2.2.2","@itwin/core-i18n":"workspace:*","@itwin/core-telemetry":"workspace:*","@itwin/webgl-compatibility":"workspace:*","@loaders.gl/core":"^3.1.6","@loaders.gl/draco":"^3.1.6","fuse.js":"^3.3.0","wms-capabilities":"0.4.0"},"nyc":{"extends":"./node_modules/@itwin/build-tools/.nycrc"}}');
 
 /***/ })