@itwin/core-geometry 4.3.0-dev.8 → 4.4.0-dev.1

package/lib/esm/topology/Graph.js

@@ -12,18 +12,16 @@ import { Point2d, Vector2d } from "../geometry3d/Point2dVector2d";
 import { Point3d, Vector3d } from "../geometry3d/Point3dVector3d";
 import { SmallSystem } from "../numerics/Polynomials";
 import { MaskManager } from "./MaskManager";
-// import { GraphChecker } from "../test/topology/Graph.test";
+// import { GraphChecker } from "../test/topology/Graph.test"; // used for debugging
 /* eslint-disable @typescript-eslint/no-this-alias */
-// cspell:word CONSTU
-// cspell:word CONSTV
-// cspell:word USEAM
-// cspell:word VSEAM
+// cspell:word CONSTU CONSTV USEAM VSEAM internaldocs
 /**
  * * Each node of the graph has a mask member.
  * * The mask member is a number which is used as set of single bit boolean values.
  * * Particular meanings of the various bits are HIGHLY application dependent.
  *   * The EXTERIOR mask bit is widely used to mark nodes that are "outside" the active areas
- *   * The PRIMARY_EDGE bit is widely used to indicate linework created directly from input data, hence protected from triangle edge flipping.
+ *   * The PRIMARY_EDGE bit is widely used to indicate linework created directly from input data, hence protected from
+ * triangle edge flipping.
  *   * The BOUNDARY bit is widely used to indicate that crossing this edge is a transition from outside to inside.
  *   * VISITED is used locally in many searches.
  *      * Never use VISITED unless the search logic is highly self contained.
@@ -31,17 +29,6 @@ import { MaskManager } from "./MaskManager";
  */
 export var HalfEdgeMask;
 (function (HalfEdgeMask) {
-    /**  Mask commonly set consistently around exterior faces.
-     * * A boundary edge with interior to one side, exterior to the other will have EXTERIOR only on the outside.
-     * * An 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.
-     */
-    HalfEdgeMask[HalfEdgeMask["EXTERIOR"] = 1] = "EXTERIOR";
-    /** Mask commonly set (on both sides) of original geometry edges that are transition from outside from 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.
-     */
-    HalfEdgeMask[HalfEdgeMask["BOUNDARY_EDGE"] = 2] = "BOUNDARY_EDGE";
     // REMARK: Various mask names are COMMENTED here for reference to native legacy code.
     // CONSTU_MASK = 0x00000004,
     // CONSTV_MASK = 0x00000008,
@@ -50,21 +37,37 @@ export var HalfEdgeMask;
     // BOUNDARY_VERTEX_MASK = 0x00000040,
     // PRIMARY_VERTEX_MASK = 0x00000080,
     // DIRECTED_EDGE_MASK = 0x00000100,
-    /** Mask commonly set (on both sides) of original geometry edges, but NOT indicating that the edge is certainly a boundary between outside and inside.
-     * * For instance, if geometry is provided as stray sticks (not loops), it can be marked PRIMARY_EDGE but neither BOUNDARY_EDGE nor EXTERIOR_EDGE
+    /**
+     * Mask commonly set consistently around exterior faces.
+     * * A boundary edge with interior to one side, exterior to the other, will have EXTERIOR only on the outside.
+     * * An 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.
+     */
+    HalfEdgeMask[HalfEdgeMask["EXTERIOR"] = 1] = "EXTERIOR";
+    /**
+     * Mask commonly set (on both sides) of original geometry edges that are transition from outside from 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.
+     */
+    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
+     * boundary between outside and inside.
+     * * For instance, if geometry is provided as stray sticks (not loops), it can be marked PRIMARY_EDGE but neither
+     * BOUNDARY_EDGE nor EXTERIOR_EDGE.
      */
     HalfEdgeMask[HalfEdgeMask["PRIMARY_EDGE"] = 4] = "PRIMARY_EDGE";
-    /** Mask used for low level searches to identify previously-visited nodes */
+    /** Mask used for low level searches to identify previously-visited nodes. */
     HalfEdgeMask[HalfEdgeMask["VISITED"] = 16] = "VISITED";
-    /** Mask applied to triangles by earcut triangulator */
+    /** Mask applied to triangles by earcut triangulator. */
     HalfEdgeMask[HalfEdgeMask["TRIANGULATED_FACE"] = 256] = "TRIANGULATED_FACE";
-    /** mask applied in a face with 2 edges. */
+    /** Mask applied in a face with 2 edges. */
     HalfEdgeMask[HalfEdgeMask["NULL_FACE"] = 512] = "NULL_FACE";
-    /** no mask bits */
+    /** No mask bits. */
     HalfEdgeMask[HalfEdgeMask["NULL_MASK"] = 0] = "NULL_MASK";
-    /** The "upper 12 " bits of 32 bit integer. */
+    /** The "upper 12" bits of 32 bit integer reserved for grab/drop. */
     HalfEdgeMask[HalfEdgeMask["ALL_GRAB_DROP_MASKS"] = 4293918720] = "ALL_GRAB_DROP_MASKS";
-    /** all mask bits */
+    /** All mask bits */
     HalfEdgeMask[HalfEdgeMask["ALL_MASK"] = 4294967295] = "ALL_MASK";
     // informal convention on preassigned mask bit numbers:
     // byte0 (EXTERIOR, BOUNDARY_EDGE, PRIMARY_EDGE) -- edge properties
@@ -72,35 +75,61 @@ export var HalfEdgeMask;
     // byte2 (TRIANGULATED_FACE, NULL_FACE) -- face properties.
 })(HalfEdgeMask || (HalfEdgeMask = {}));
 /**
+ * A HalfEdge is "one side of an edge" in a structure of faces, edges and vertices. From a node there are
+ * navigational links to:
+ * * "faceSuccessor" -- the next half edge in a loop around a face.
+ * * "facePredecessor" -- the previous half edge in a loop around a face.
+ * * "edgeMate"  -- the node's partner on the other side of the edge.
+ *
+ * The next, prev, and mate are the essential connectivity. Additional node content is for application-specific
+ * uses. The most useful ones are:
+ * * x,y -- coordinates in the xy plane
+ * * z -- z coordinate. This is normally ignored during planar setup, but used for output.
+ * * maskBits -- an integer value manipulated as individual bits.
  *
- * * A HalfEdge is "one side of an edge" in a structure of faces, edges and vertices.  From a node there are navigational links to:
- * ** "faceSuccessor" -- the next half edge in a loop around a face.
- * ** "facePredecessor" -- the previous half edge in a loop around a face.
- * ** "edgeMate"  -- the node's partner on the other side of the edge.
- * * The next, prev, and mate are the essential connectivity.  Additional node content is for application-specific
- *     uses.  The most useful ones are:
- * ** x,y -- coordinates in the xy plane
- * ** z -- z coordinate.  This is normally ignored during planar setup, but used for output.
- * ** buffer -- a integer value manipulated as individual bits.
- * * In properly connected planar graph, interior face loops are counterclockwise.  But that property (along with
- *      expected masking) is a result of extensive validation of inputs, and is not true in intermediate phases
- *      of graph manipulation.
+ * In properly connected planar graph, interior face loops are counterclockwise. But that property (along with
+ * expected masking) is a result of extensive validation of inputs, and is not true in intermediate phases of
+ * graph manipulation.
  * @internal
  */
 class HalfEdge {
-    /** id assigned sequentially during construction --- useful for debugging. */
-    get id() { return this._id; }
-    /** previous half edge "around the face"
-     */
-    get facePredecessor() { return this._facePredecessor; }
-    /** next half edge "around the face" */
-    get faceSuccessor() { return this._faceSuccessor; }
-    /** Half edge on the other side of this edge.
-     */
-    get edgeMate() { return this._edgeMate; }
-    /** Take numStep face steps and return y coordinate
-     * * positive steps are through faceSuccessor
-     * * negative steps are through facePredecessor
+    /** Immutable ID assigned sequentially during construction --- useful for debugging. */
+    get id() {
+        return this._id;
+    }
+    /** Previous half edge "around the face" */
+    get facePredecessor() {
+        return this._facePredecessor;
+    }
+    /** Next half edge "around the face" */
+    get faceSuccessor() {
+        return this._faceSuccessor;
+    }
+    /** Half edge on the other side of this edge. */
+    get edgeMate() {
+        return this._edgeMate;
+    }
+    constructor(x = 0, y = 0, z = 0, i = 0) {
+        this._id = HalfEdge._totalNodesCreated++;
+        this.i = i;
+        this.maskBits = 0x00000000;
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        // explicit init to undefined is important for performance here
+        this.sortAngle = undefined;
+        this.sortData = undefined;
+        this.edgeTag = undefined;
+        this.faceTag = undefined;
+        // always created in pairs, init here to make TS compiler and JS runtime happy
+        this._facePredecessor = this;
+        this._faceSuccessor = this;
+        this._edgeMate = this;
+    }
+    /**
+     * Take numStep face steps and return y coordinate.
+     * * Positive steps are through faceSuccessor.
+     * * Negative steps are through facePredecessor.
      */
     faceStepY(numStep) {
         let node = this;
@@ -113,12 +142,13 @@ class HalfEdge {
         return node.y;
     }
     /**
-     * * Create 2 half edges.
+     * Create 2 half edges.
      * * The two edges are joined as edgeMate pair.
      * * The two edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
-     * @returns Returns the reference to the first half edge created
+     * @returns the reference to the first half edge created.
      */
     static createHalfEdgePair(heArray) {
+        // Visualization can be found at geometry/internaldocs/Graph.md
         const a = new HalfEdge();
         const b = new HalfEdge();
         if (heArray) {
@@ -134,8 +164,8 @@ class HalfEdge {
      * * Create 2 half edges.
      * * The two edges are joined as edgeMate pair.
      * * The two edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
-     * * Properties x,y,z,i are inserted in each
-     * @returns Returns the reference to the first half edge created
+     * * Properties x,y,z,i are inserted in each half edge.
+     * @returns the reference to the first half edge created.
      */
     static createHalfEdgePairWithCoordinates(xA = 0, yA = 0, zA = 0, iA = 0, xB = 0, yB = 0, zB = 0, iB = 0, heArray) {
         const a = HalfEdge.createHalfEdgePair(heArray);
@@ -151,32 +181,32 @@ class HalfEdge {
         return a;
     }
     /**
-     * * set heA <==> heB pointer relation through heA._faceSuccessor and heB._facePredecessor
+     * * Set heA <==> heB pointer relation through heA._faceSuccessor and heB._facePredecessor.
      * * This changes heA._faceSuccessor and heB._facePredecessor, but not heA._facePredecessor and heB._faceSuccessor.
-     * * this must always be done with another call to reestablish the entire double-linked list.
+     * * This must always be done with another call to setFaceLinks(heB,heA) in order to re-establish the entire
+     * double-linked list.
      */
     static setFaceLinks(heA, heB) {
         heA._faceSuccessor = heB;
         heB._facePredecessor = heA;
     }
-    /**
-     * * set heA <==> heB pointer relation edgeMate
-     */
+    /** set heA <==> heB pointer relation edgeMate. */
     static setEdgeMates(heA, heB) {
         heA._edgeMate = heB;
         heB._edgeMate = heA;
     }
     /**
-     * * Create a new vertex within the edge from base.
-     * * Insert it "within" the base edge.
-     * * This requires two new half edges.
-     * * if the base is undefined, create a single-edge loop.
-     * * This (unlike pinch) breaks the edgeMate pairing of the base edge.
-     * * This preserves xyz and i properties at all existing vertices.
-     * * on each side, if edgeTag is present it is copied to the new edge.
-     * @returns Returns the reference to the half edge created.
+     * Create a new vertex within the edge beginning at `baseA`.
+     * * This creates two new nodes in their own vertex loop.
+     * * If the base is undefined, create a single-edge loop.
+     * * Existing nodes stay in their face and vertex loops and retain xyz and i values.
+     * * Unlike [[pinch]], this breaks the edgeMate pairing of the input edge:
+     * each node of the input edge gets a new node as its edge mate.
+     * * On each side of the edge, if edgeTag is present, it is copied to the new node on that side.
+     * @returns reference to the half edge created, the new face successor of `baseA`.
      */
     static splitEdge(baseA, xA = 0, yA = 0, zA = 0, iA = 0, heArray) {
+        // Visualization can be found at geometry/internaldocs/Graph.md
         const newA = new HalfEdge(xA, yA, zA, iA);
         const newB = new HalfEdge(xA, yA, zA, iA);
         if (heArray) {
@@ -192,10 +222,12 @@ class HalfEdge {
             const nextA = baseA._faceSuccessor;
             const mateA = baseA._edgeMate;
             const vPredA = mateA._faceSuccessor;
+            // insert newA and newB between existing half edges
             HalfEdge.setFaceLinks(newA, nextA);
             HalfEdge.setFaceLinks(baseA, newA);
             HalfEdge.setFaceLinks(mateA, newB);
             HalfEdge.setFaceLinks(newB, vPredA);
+            // set correct edge mates
             HalfEdge.setEdgeMates(newA, mateA);
             HalfEdge.setEdgeMates(newB, baseA);
             this.transferEdgeProperties(baseA, newA);
@@ -204,29 +236,26 @@ class HalfEdge {
         return newA;
     }
     /**
-     * * Create a new sliver face "inside" an existing edge.
-     * * Insert it "within" the base edge.
-     * * This requires two new half edges.
-     * * if the base is undefined, create a single-edge loop.
-     * * This (unlike pinch) breaks the edgeMate pairing of the base edge.
-     * * This preserves xyz and i properties at all existing vertices.
-     * * The two new half edges are a sliver face (via their predecessor and successor)
-     * * Each new edge mates to one existing edge.
-     * @returns Returns the reference to the half edge created.
+     * Create a new sliver face "inside" an existing edge.
+     * * This creates two nodes that are each face predecessor and successor to the other.
+     * * Existing nodes stay in their face and vertex loops and retain xyz and i values.
+     * * Unlike [[pinch]], this breaks the edgeMate pairing of the input edge:
+     * each node of the input edge gets a new node as its edge mate.
+     * * New nodes get the xyz and i values shared by the nodes in the vertex loops into which they are placed.
+     * * New nodes' faceTag and edgeTag are `undefined`.
+     * @returns reference to the half edge created in the vertex loop of baseA.
      */
     static splitEdgeCreateSliverFace(baseA, heArray) {
-        // raw edges ...
+        // Visualization can be found at geometry/internaldocs/Graph.md
+        const baseB = baseA.edgeMate;
         const newA = new HalfEdge();
         const newB = new HalfEdge();
-        const baseB = baseA.edgeMate;
         if (heArray) {
             heArray.push(newA);
             heArray.push(newB);
         }
         newA._faceSuccessor = newA._facePredecessor = newB;
         newB._faceSuccessor = newB._facePredecessor = newA;
-        // newA is in vertex loop with baseA etc.
-        // newA mates to baseB
         HalfEdge.setEdgeMates(newA, baseB);
         HalfEdge.setEdgeMates(newB, baseA);
         newA.copyDataFrom(baseA, true, true, false, false);
@@ -234,11 +263,9 @@ class HalfEdge {
         return newA;
     }
     /**
-     * Copy "edge based" content of fromNode to toNode
+     * Copy "edge based" content of `fromNode` to `toNode`:
      * * edgeTag
-     * * masks in _edgePropertyMasks: EXTERIOR, BOUNDARY_EDGE, NULL_FACE, PRIMARY_EDGE
-     * @param fromNode
-     * @param toNode
+     * * masks EXTERIOR, BOUNDARY_EDGE, NULL_FACE, PRIMARY_EDGE
      */
     static transferEdgeProperties(fromNode, toNode) {
         toNode.edgeTag = fromNode.edgeTag;
@@ -249,49 +276,38 @@ class HalfEdge {
                 toNode.clearMask(mask);
         }
     }
-    constructor(x = 0, y = 0, z = 0, i = 0) {
-        this._id = HalfEdge._totalNodesCreated++;
-        this.i = i;
-        this.maskBits = 0x00000000;
-        this.x = x;
-        this.y = y;
-        this.z = z;
-        // Explicit init to undefined is important for performance here
-        this.sortAngle = undefined;
-        this.sortData = undefined;
-        this.edgeTag = undefined;
-        this.faceTag = undefined;
-        // Always created in pairs, init here to make TS compiler and JS runtime happy
-        this._facePredecessor = this;
-        this._faceSuccessor = this;
-        this._edgeMate = this;
+    /** Return the next half edge around this vertex in the CCW direction. */
+    get vertexSuccessor() {
+        return this.facePredecessor.edgeMate;
+    }
+    /** Return the next half edge around this vertex in the CW direction. */
+    get vertexPredecessor() {
+        return this.edgeMate.faceSuccessor;
     }
     /**
-     * Return the next outbound half edge around this vertex in the CCW direction
-     */
-    get vertexSuccessor() { return this.facePredecessor.edgeMate; }
-    /**
-     * Return the next outbound half edge around this vertex in the CW direction
-     */
-    get vertexPredecessor() { return this.edgeMate.faceSuccessor; }
-    /**
-     * Set mask bits on this HalfEdge
-     * @param mask mask to apply
+     * Set mask bits on this HalfEdge.
+     * @param mask mask bits to apply
      */
-    setMask(mask) { this.maskBits |= mask; }
+    setMask(mask) {
+        this.maskBits |= mask;
+    }
     /**
-     * Get mask bits from this HalfEdge
-     * @param mask mask to query
+     * Get mask bits from this HalfEdge.
+     * @param mask mask bits to query
      */
-    getMask(mask) { return (this.maskBits & mask); }
+    getMask(mask) {
+        return (this.maskBits & mask);
+    }
     /**
-     * Clear mask bits from this HalfEdge
-     * @param mask mask to clear
+     * Clear mask bits from this HalfEdge.
+     * @param mask mask bits to clear
      */
-    clearMask(mask) { this.maskBits &= ~mask; }
+    clearMask(mask) {
+        this.maskBits &= ~mask;
+    }
     /**
      * Set a mask at all nodes around a vertex.
-     * @param mask mask to apply to the half edges around this HalfEdge's vertex loop
+     * @param mask mask to apply to the half edges around this HalfEdge's vertex loop.
      */
     setMaskAroundVertex(mask) {
         let node = this;
@@ -300,10 +316,7 @@ class HalfEdge {
             node = node.vertexSuccessor;
         } while (node !== this);
     }
-    /**
-     * Set x,y,z at all nodes around a vertex.
-     * @param mask mask to apply to the half edges around this HalfEdge's vertex loop
-     */
+    /** Set x,y,z at all nodes around a vertex. */
     setXYZAroundVertex(x, y, z) {
         let node = this;
         do {
@@ -315,7 +328,7 @@ class HalfEdge {
     }
     /**
      * Apply a mask to all edges around a face.
-     * @param mask mask to apply to the half edges around this HalfEdge's face loop
+     * @param mask mask to apply to the half edges around this HalfEdge's face loop.
      */
     setMaskAroundFace(mask) {
         let node = this;
@@ -326,7 +339,7 @@ class HalfEdge {
     }
     /**
      * Apply a mask to both sides of an edge.
-     * @param mask mask to apply to this edge and its `edgeMate`
+     * @param mask mask to apply to this edge and its edgeMate.
      */
     setMaskAroundEdge(mask) {
         this.setMask(mask);
@@ -334,7 +347,7 @@ class HalfEdge {
     }
     /**
      * Clear a mask on both sides of an edge.
-     * @param mask mask to clear on this edge and its `edgeMate`
+     * @param mask mask to clear on this edge and its edgeMate.
      */
     clearMaskAroundEdge(mask) {
         this.clearMask(mask);
@@ -350,7 +363,7 @@ class HalfEdge {
         } while (node !== this);
         return count;
     }
-    /** Return true if other is in the vertex loop around this. */
+    /** Return true if `other` node is in the vertex loop around `this` node. */
     findAroundVertex(other) {
         let node = this;
         do {
@@ -360,7 +373,7 @@ class HalfEdge {
         } while (node !== this);
         return false;
     }
-    /** Return true if other is in the face loop around this. */
+    /** Return true if `other` node is in the face loop around `this` node. */
     findAroundFace(other) {
         let node = this;
         do {
@@ -371,7 +384,9 @@ class HalfEdge {
         return false;
     }
     /**
-     * @return whether the mask is set (or unset) on all nodes of the face loop
+     * Returns whether the mask is set or unset on all nodes of the face loop.
+     * @param mask the mask to check.
+     * @param value true for mask set and false for mask unset.
      */
     isMaskedAroundFace(mask, value = true) {
         let node = this;
@@ -392,10 +407,10 @@ class HalfEdge {
         return true;
     }
     /**
-     * Apply a edgeTag and mask to all edges around a face.
-     * optionally apply it to all edge mates.
-     * @param edgeTag tag to apply
-     * @param bothSides If true, also apply the tag to the mates around the face.
+     * Apply a mask and edgeTag to all edges around a face. Optionally apply it to all edge mates.
+     * @param mask mask to apply.
+     * @param tag edgeTag to apply
+     * @param applyToMate If true, also apply the tag to the edge mates around the face.
      */
     setMaskAndEdgeTagAroundFace(mask, tag, applyToMate = false) {
         let node = this;
@@ -404,8 +419,8 @@ class HalfEdge {
             node.edgeTag = tag;
             if (applyToMate) {
                 const mate = node.edgeMate;
-                mate.edgeTag = tag;
                 mate.setMask(mask);
+                mate.edgeTag = tag;
             }
             node = node.faceSuccessor;
         } while (node !== this);
@@ -420,7 +435,11 @@ class HalfEdge {
         } while (node !== this);
         return count;
     }
-    /** Returns the number of nodes found with the given mask value around this vertex loop. */
+    /**
+     * Returns the number of nodes that match (or do not match) the given mask value around this face loop.
+     * @param mask the mask to check.
+     * @param value true for mask match and false for mask not match.
+     */
     countMaskAroundFace(mask, value = true) {
         let count = 0;
         let node = this;
@@ -440,7 +459,11 @@ class HalfEdge {
         }
         return count;
     }
-    /** Returns the number of nodes found with the given mask value around this vertex loop.   */
+    /**
+     * Returns the number of nodes that match (or do not match) the given mask value around this vertex loop.
+     * @param mask the mask to check.
+     * @param value true for mask match and false for mask not match.
+     */
     countMaskAroundVertex(mask, value = true) {
         let count = 0;
         let node = this;
@@ -460,7 +483,12 @@ class HalfEdge {
         }
         return count;
     }
-    /** Returns the first node with given mask value around this vertex loop.   */
+    /**
+     * Returns the first node that matches (or does not match) the given mask value around this vertex loop, starting
+     * with the instance node and proceeding via vertex successors.
+     * @param mask the mask to check.
+     * @param value true for mask match and false for mask not match.
+     */
     findMaskAroundVertex(mask, value = true) {
         let node = this;
         do {
@@ -470,7 +498,12 @@ class HalfEdge {
         } while (node !== this);
         return undefined;
     }
-    /** Returns the first node with given mask value around this face loop.   */
+    /**
+     * Returns the first node that matches (or does not match) the given mask value around this face loop, starting
+     * with the instance node and proceeding via face successors.
+     * @param mask the mask to check.
+     * @param value true for mask match and false for mask not match.
+     */
     findMaskAroundFace(mask, value = true) {
         let node = this;
         do {
@@ -480,7 +513,12 @@ class HalfEdge {
         } while (node !== this);
         return undefined;
     }
-    /** Returns the first node with given mask value on this edge (i.e. examining this and this.mate)  */
+    /**
+     *  Returns the first node that matches (or does not match) the given mask value around this edge, starting
+     * with the instance node and then checking its edge mate.
+     * @param mask the mask to check.
+     * @param value true for mask match and false for mask not match.
+     */
     findMaskAroundEdge(mask, value = true) {
         if (this.isMaskSet(mask) === value)
             return this;
@@ -489,8 +527,9 @@ class HalfEdge {
             return mate;
         return undefined;
     }
-    /** Set a mask, and return prior value.
-     * @param mask mask to apply
+    /**
+     * Set a mask and return prior value.
+     * @param mask mask to apply.
      */
     testAndSetMask(mask) {
         const oldMask = this.maskBits & mask;
@@ -498,8 +537,8 @@ class HalfEdge {
         return oldMask;
     }
     /**
-     * Set (copy) the this.x, this.y, this.z from node.x, node.y, node.z
-     * @param node node containing xyz
+     * Set `this.x`, `this.y`, `this.z` from `node.x`, `node.y`, `node.z`.
+     * @param node node containing xyz.
      */
     setXYZFrom(node) {
         this.x = node.x;
@@ -507,7 +546,7 @@ class HalfEdge {
         this.z = node.z;
     }
     /**
-     * Set (copy) the this.x, this.y, this.z from xyz.x, xyz.y, xyz.z
+     * Set `this.x`, `this.y`, `this.z` from `xyz.x`, `xyz.y`, `xyz.z`.
      * @param node source with x,y,z properties
      */
     setXYZ(xyz) {
@@ -516,32 +555,37 @@ class HalfEdge {
         this.z = xyz.z;
     }
     /**
-     * Test if mask bits are set in the node's bitMask.
-     * @return Return true (as a simple boolean, not a mask) if any bits of the mask parameter match bits of the node's bitMask
+     * Test if any of the `mask` bits are set in the node's bitMask.
+     * @return true (as a simple boolean, not a mask) if any bits of the `mask` match bits of the node's bitMask.
      */
-    isMaskSet(mask) { return (this.maskBits & mask) !== 0; }
-    /** (static!) method to test if a mask is set on a node.
-     * This is used as filter in searches.
-     * @returns true iff `node.isMaskSet (mask)`
+    isMaskSet(mask) {
+        return (this.maskBits & mask) !== 0;
+    }
+    /**
+     * Static method to test if any of the `mask` bits are set in the `node`'s bitMask.
+     * * This is used as filter in searches.
+     * @returns `node.isMaskSet(mask)`
      */
     static filterIsMaskOn(node, mask) {
         return node.isMaskSet(mask);
     }
-    /** (static!) method to test if a mask is set on a node.
-     * This is used as filter in searches.
-     * @returns true iff `!node.isMaskSet (mask)`
+    /**
+     * Static method to test if any of the `mask` bits are set in the `node`'s bitMask.
+     * * This is used as filter in searches.
+     * @returns `!node.isMaskSet(mask)`
      */
     static filterIsMaskOff(node, mask) {
         return !node.isMaskSet(mask);
     }
     /**
      * Create an edge with initial id,x,y at each end.
-     * @param id0 id for first node
-     * @param x0  x coordinate for first node
-     * @param y0  y coordinate for first node
-     * @param id1 id for second node
-     * @param x1 x coordinate for second node
-     * @param y1 y coordinate for second node
+     * @param id0 id for first node.
+     * @param x0 x coordinate for first node.
+     * @param y0 y coordinate for first node.
+     * @param id1 id for second node.
+     * @param x1 x coordinate for second node.
+     * @param y1 y coordinate for second node.
+     * @returns the reference to the new node at (x0,y0).
      */
     static createEdgeXYXY(id0, x0, y0, id1, x1, y1) {
         const node0 = new HalfEdge(x0, y0);
@@ -552,15 +596,15 @@ class HalfEdge {
         node1._id = id1;
         return node0;
     }
-    /** "pinch" ...
-     *
-     * * is the universal manipulator for manipulating a node's next and prev pointers
-     * * swaps face predecessors of nodeA and nodeB.
-     * *  is its own inverse.
-     * *  if nodeA, nodeB are in different face loops, the loops join to one loop.
-     * *  if nodeA, nodeB are in the same face loop, the loop splits into two loops.
+    /**
+     *"Pinch" is the universal operator for manipulating a node's next and previous pointers.
+     * * It is its own inverse: applying it twice on the same inputs (i.e., `pinch(a,b); pinch(a,b);`) gets back to
+     * where you started.
+     * * If the inputs are in different face loops, the loops join to one face loop after the pinch.
+     * * If the inputs are in the same face loop, the loop splits into two face loops after the pinch.
      */
     static pinch(nodeA, nodeB) {
+        // Visualization can be found at geometry/internaldocs/Graph.md
         if (nodeA !== nodeB) {
             const predA = nodeA._facePredecessor;
             const predB = nodeB._facePredecessor;
@@ -572,17 +616,19 @@ class HalfEdge {
     }
     /**
      * Pinch this half edge out of its base vertex loop.
-     * @return the surviving HalfEdge in the vertex loop, or undefined if the instance HalfEdge is already dangling
+     * @return the surviving HalfEdge in the vertex loop or `undefined` if the instance HalfEdge is already dangling.
      */
     yankFromVertexLoop() {
         const other = this.edgeMate.faceSuccessor;
         if (other === this)
             return undefined;
+        // at this point "other" is the vertex predecessor of "this"
         HalfEdge.pinch(this, other);
         return other;
     }
-    /** Turn all pointers to undefined so garbage collector can reuse the object.
-     *  This is to be called only by a Graph object that is being decommissioned.
+    /**
+     * Turn all pointers to `undefined` so garbage collector can reuse the object.
+     * * This is to be called only by a Graph object that is being decommissioned.
      */
     decommission() {
         this._facePredecessor = undefined;
@@ -590,27 +636,34 @@ class HalfEdge {
         this._edgeMate = undefined;
     }
     /** Return the node. This identity function is useful as the NodeFunction in collector methods. */
-    static nodeToSelf(node) { return node; }
-    /** Return the id of a node.  Useful for collector methods. */
-    static nodeToId(node) { return node.id; }
-    /** Return the id of a node.Useful for collector methods. */
-    static nodeToIdString(node) { return node.id.toString(); }
-    /** Return the [id, [x,y]] of a node.  Useful for collector methods. */
+    static nodeToSelf(node) {
+        return node;
+    }
+    /** Return the id of a node. Useful for collector methods. */
+    static nodeToId(node) {
+        return node.id;
+    }
+    /** Return the id of a node as string. Useful for collector methods. */
+    static nodeToIdString(node) {
+        return node.id.toString();
+    }
+    /** Return the [id, mask, [x,y]] of a node. Useful for collector methods. */
     static nodeToIdMaskXY(node) {
         return { id: node.id, mask: HalfEdge.nodeToMaskString(node), xy: [node.x, node.y] };
     }
-    /** Return the [id, [x,y]] of a node.  Useful for collector methods. */
+    /** Return the [id, mask, [x,y]] of a node as string. Useful for collector methods. */
     static nodeToIdXYString(node) {
         const s = `${node.id.toString()}+${HalfEdge.nodeToMaskString(node)}[${node.x},${node.y}]`;
         return s;
     }
-    /** Return the [id, [x,y],z] of a node.  Useful for collector methods. */
+    /** Return the [id, [x,y,z]] of a node as string. Useful for collector methods. */
     static nodeToIdXYZString(node) {
         return `[${node.id.toString()}: ${node.x},${node.y},${node.z}]`;
     }
-    /** Create a string representation of the mask
+    /**
+     * Create a string representation of the mask.
      * * Null mask is empty string.
-     * * Appended characters B,P,X for Boundary, Primary, Exterior mask bits.
+     * * Appended characters B,P,X,N are for BOUNDARY_EDGE, PRIMARY_EDGE, EXTERIOR, and NULL_FACE mask bits.
      */
     static nodeToMaskString(node) {
         let s = "";
@@ -624,49 +677,46 @@ class HalfEdge {
             s += "N";
         return s;
     }
-    /** Return [x,y] with coordinates of node */
-    static nodeToXY(node) { return [node.x, node.y]; }
-    /** Return Vector2d to face successor, with only xy coordinates */
+    /** Return [x,y] with coordinates of node. */
+    static nodeToXY(node) {
+        return [node.x, node.y];
+    }
+    /** Return Vector2d from `this` to face successor (with only xy coordinates). */
     vectorToFaceSuccessorXY(result) {
         return Vector2d.create(this.faceSuccessor.x - this.x, this.faceSuccessor.y - this.y, result);
     }
-    /** Return Vector3d to face successor */
+    /** Return Vector3d from `this` to face successor. */
     vectorToFaceSuccessor(result) {
         const other = this.faceSuccessor;
         return Vector3d.create(other.x - this.x, other.y - this.y, other.z - this.z, result);
     }
-    /** Return Vector3d to face successor */
+    /** Return Vector3d from `this` to face successor. */
     vectorToFacePredecessor(result) {
         const other = this.facePredecessor;
         return Vector3d.create(other.x - this.x, other.y - this.y, other.z - this.z, result);
     }
-    /** test if spaceNode is in the sector at sectorNode */
+    /** Test if `spaceNode` is in the sector at `sectorNode`. */
     static isNodeVisibleInSector(spaceNode, sectorNode) {
-        // remark: fussy details ported from native code.
-        // The obscure cases seemed "unlikely" at first.  But preexisting unit tests for triangulation pinged just about everything.
-        // So it really matters to do the "0" cases this way.
-        //  (As usual, hard coded zero is suspect, but it seems to work nicely in the discrete decisions.)
+        // remark: fussy details ported from native code. The obscure cases seemed "unlikely" at first. But pre-existing
+        // unit tests for triangulation pinged just about everything. So it really matters to do the "0" cases this way
+        // (as usual, hard coded zero is suspect, but it seems to work nicely in the discrete decisions).
         if (sectorNode.vertexSuccessor === sectorNode)
             return true;
         const successor = sectorNode.faceSuccessor;
         const predecessor = sectorNode.facePredecessor;
         const successorCross = this.crossProductXYToTargets(sectorNode, successor, spaceNode);
         const predecessorCross = this.crossProductXYToTargets(predecessor, sectorNode, spaceNode);
-        // simplest case:  two positives
+        // simplest case: two positives
         if (successorCross > 0.0 && predecessorCross > 0.0)
             return true;
         const sectorCross = this.crossProductXYToTargets(predecessor, sectorNode, successor);
         if (predecessorCross <= 0.0 && successorCross <= 0.0) {
             if (predecessorCross === 0.0 && successorCross === 0.0 && sectorCross === 0.0) {
-                /* Everything is on a line.*/
-                /* If the sector is a degenerate face, nodeP can only be
-                        in if it is the other node in the degenerate face.
-                */
+                // Everything is on a line. If the sector is a degenerate face, nodeP
+                // can only be in if it is the other node in the degenerate face.
                 if (predecessor === successor && sectorNode.vertexSuccessor !== sectorNode)
                     return spaceNode === successor;
-                /* Sector is 360 degrees.  Call it in only if vector from predP
-                    to sectorP points forward to nodeP.
-                */
+                // Sector is 360 degrees. Call it in only if vector from predP to sectorP points forward to nodeP.
                 return HalfEdge.dotProductNodeToNodeVectorsXY(predecessor, sectorNode, sectorNode, spaceNode) > 0.0;
             }
             else {
@@ -675,56 +725,59 @@ class HalfEdge {
         }
         else {
             if (sectorCross === 0.0 && predecessorCross !== 0.0 && successorCross !== 0.0) {
-                // The incoming and outgoing edges at the sector are identical direction.
-                // We have to decide if this node is  inside the degenerate face (i.e. a geometrically empty sector)
-                // or outside (i.e. a nearly complete sector).
-                // In the inside case, the face is just two nodes.
-                // Exact equality for zero is ok because cross product should be using identical
-                // coordinates in subtracted terms.  (All furrow eyebrows in unison ....)
+                // The incoming and outgoing edges at the sector are identical direction. We have to decide if this node is
+                // inside the degenerate face (i.e. a geometrically empty sector) or outside (i.e. a nearly complete sector).
+                // In the inside case, the face is just two nodes. Exact equality for zero is ok because cross product should
+                // be using identical coordinates in subtracted terms (all furrow eyebrows in unison).
                 return predecessor !== successor;
             }
             return sectorCross < 0.0;
         }
     }
-    /** Returns Return cross product (2d) of vectors from baseA to targetA and baseB to targetB */
+    /** Returns 2D cross product of vectors from `base` to `targetA` and from `base` to `targetB`. */
     static crossProductXYToTargets(base, targetA, targetB) {
         return Geometry.crossProductXYXY(targetA.x - base.x, targetA.y - base.y, targetB.x - base.x, targetB.y - base.y);
     }
-    /** Returns Return dot product (2d) of vectors along two edges. */
+    /** Returns 2D dot product of vectors from `baseA` to `targetA` and from `baseB` to `targetB`. */
     static dotProductNodeToNodeVectorsXY(baseA, targetA, baseB, targetB) {
         return Geometry.dotProductXYXY(targetA.x - baseA.x, targetA.y - baseA.y, targetB.x - baseB.x, targetB.y - baseB.y);
     }
-    /** Return cross product (2d) of vectors from nodeA to nodeB and nodeB to nodeC
-     */
+    /** Return 2D cross product of vectors from `nodeA` to `nodeB` and from `nodeB` to `nodeC`. */
     static crossProductXYAlongChain(nodeA, nodeB, nodeC) {
         return Geometry.crossProductXYXY(nodeB.x - nodeA.x, nodeB.y - nodeA.y, nodeC.x - nodeB.x, nodeC.y - nodeB.y);
     }
     /**
      * Compute whether the sector defined by the chain of nodes is convex.
+     * * This function is determining if, in the traversal of the HalfEdges in a face loop, a corner makes a left turn
+     * (convex) or a right turn (not-convex). Note that if we have a convex face, then to traverse it in ccw orientation,
+     * we always do left turns. However, if the face is not convex, we make both left and right turns.
      * * This computation ignores z-coordinates and connectivity, so the nodes are not required to be in the same face loop.
-     * @param nodeA the first node in the chain, nominally the face predecessor of nodeB
-     * @param nodeB the second node in the chain; the node at the sector vertex
-     * @param nodeC the third node in the chain, nominally the face successor of nodeB
-     * @param signedAreaTol optional signed area tolerance to use in test for parallel vectors.
-     *   Typically this is a fraction of the sector's face's signed area. We can't compute area here, so if undefined, zero tolerance is used.
-     * @returns true iff the sector is convex
+     * @param nodeA the first node in the chain, nominally the face predecessor of nodeB.
+     * @param nodeB the second node in the chain; the node at the sector vertex.
+     * @param nodeC the third node in the chain, nominally the face successor of nodeB.
+     * @param signedAreaTol optional signed area tolerance to use in test for parallel vectors. Typically this is a
+     * fraction of the sector's face's signed area. We can't compute area here, so if undefined, zero tolerance is used.
+     * @returns true iff the sector is convex. A degenerate sector, where the incident edges overlap, returns false.
      */
     static isSectorConvex(nodeA, nodeB, nodeC, signedAreaTol = 0) {
         const signedSectorArea = 0.5 * HalfEdge.crossProductXYAlongChain(nodeA, nodeB, nodeC);
         signedAreaTol = signedAreaTol ?? 0.0;
         if (Math.abs(signedSectorArea) <= Math.abs(signedAreaTol)) {
-            // the sector vectors are nearly parallel or antiparallel; only the former is deemed convex.
+            // the sector vectors are nearly parallel or anti-parallel; only the former is deemed convex.
             return HalfEdge.dotProductNodeToNodeVectorsXY(nodeA, nodeB, nodeB, nodeC) > 0.0;
         }
-        return signedSectorArea > -signedAreaTol; // call it convex even if we are a little bit on the other side of zero
+        // // sector is convex if the area is positive. Call it convex even if we are a little bit on the other side of zero.
+        return signedSectorArea > -signedAreaTol;
     }
     /**
      * Compute whether the sector at this node is convex.
+     * * This function is determining if, in the traversal of the HalfEdges in a face loop, a corner makes a left turn
+     * (convex) or a right turn (not-convex). Note that if we have a convex face, then to traverse it in ccw orientation,
+     * we always do left turns. However, if the face is not convex, we make both left and right turns.
      * * This computation ignores z-coordinates.
-     * @param signedAreaTol optional signed area tolerance to use in test for parallel vectors.
-     *   If undefined, a fraction ([[Geometry.smallMetricDistanceSquared]]) of the computed signed area is used.
-     *   Pass zero to skip toleranced computation.
-     * @returns true iff the sector is convex and its two edges are not antiparallel.
+     * @param signedAreaTol optional signed area tolerance to use in test for parallel vectors. If undefined, a fraction
+     * (`Geometry.smallMetricDistanceSquared`) of the computed signed area is used. Pass 0 to skip toleranced computation.
+     * @returns true iff the sector is convex. A degenerate sector, where the incident edges overlap, returns false.
      */
     isSectorConvex(signedAreaTol) {
         if (signedAreaTol === undefined)
@@ -733,10 +786,11 @@ class HalfEdge {
     }
     /**
      * Compute whether this face is convex.
+     * * Note that if we have a convex face, then to traverse it in ccw orientation, we always do left turns.
+     * However, if the face is not convex, we make both left and right turns.
      * * This computation ignores z-coordinates.
-     * @param tolerance optional relative tolerance to use in test for parallel vectors.
-     *   Default value is [[Geometry.smallMetricDistanceSquared]].
-     *   Pass zero to skip toleranced computation.
+     * @param tolerance optional relative tolerance to use in test for parallel vectors. Default value is
+     * `Geometry.smallMetricDistanceSquared`. Pass 0 to skip toleranced computation.
      * @returns true iff this face is convex.
      */
     isFaceConvex(tolerance = Geometry.smallMetricDistanceSquared) {
@@ -749,83 +803,80 @@ class HalfEdge {
         } while (node !== this);
         return true;
     }
-    /**
-     * Isolate the edge from the graph by yanking each end from its vertex loop.
-     */
+    /** Isolate the edge from the graph by yanking each end from its vertex loop. */
     isolateEdge() {
         const mate = this.edgeMate;
         this.yankFromVertexLoop();
         mate.yankFromVertexLoop();
     }
-    /**
-     * @return whether this edge is isolated from the rest of the graph.
-     */
+    /** Specify whether this edge is isolated from the rest of the graph. */
     get isIsolatedEdge() {
         return this === this.vertexSuccessor && this.edgeMate === this.edgeMate.vertexSuccessor;
     }
-    /** Return true if `this` is lexically below `other`, comparing y first then x. */
+    /** Return true if `this` is lexically below `other`. We compare y first, then x, and ignore z. */
     belowYX(other) {
-        // Check y's
-        // if (!Geometry.isSameCoordinate(a.y, b.y))
         if (this.y < other.y)
             return true;
         if (this.y > other.y)
             return false;
-        // same y.
-        // Check x's
         if (this.x < other.x)
             return true;
         return false;
     }
-    /** Returns Returns true if the node does NOT have Mask.EXTERIOR_MASK set. */
-    static testNodeMaskNotExterior(node) { return !node.isMaskSet(HalfEdgeMask.EXTERIOR); }
-    /** Returns Returns true if the edge mate has Mask.EXTERIOR_MASK set. */
-    static testMateMaskExterior(node) { return node.edgeMate.isMaskSet(HalfEdgeMask.EXTERIOR); }
-    /** Returns radians between this edge and its face predecessor edge, using all three coordinates x,y,z and given normal to resolve sweep direction.
-     *   * The returned angle is positive, i.e. may be larger than PI radians.
-    */
+    /** Returns `true` if the node does NOT have `Mask.EXTERIOR_MASK` set. */
+    static testNodeMaskNotExterior(node) {
+        return !node.isMaskSet(HalfEdgeMask.EXTERIOR);
+    }
+    /** Returns `true` if the edge mate has `Mask.EXTERIOR_MASK` set. */
+    static testMateMaskExterior(node) {
+        return node.edgeMate.isMaskSet(HalfEdgeMask.EXTERIOR);
+    }
+    /**
+     * Returns radians between this edge and its face predecessor edge, using all three coordinates x,y,z and
+     * given normal to resolve sweep direction.
+     * * The returned angle is non-negative: 0 <= radians < 2*PI.
+     */
     static sectorSweepRadiansXYZ(node, normal) {
-        const nodeB = node.faceSuccessor;
-        const nodeC = node.facePredecessor;
-        return Angle.orientedRadiansBetweenVectorsXYZ(nodeB.x - node.x, nodeB.y - node.y, nodeB.z - node.z, nodeC.x - node.x, nodeC.y - node.y, nodeC.z - node.z, normal.x, normal.y, normal.z, true);
+        const suc = node.faceSuccessor;
+        const pred = node.facePredecessor;
+        return Angle.orientedRadiansBetweenVectorsXYZ(suc.x - node.x, suc.y - node.y, suc.z - node.z, pred.x - node.x, pred.y - node.y, pred.z - node.z, normal.x, normal.y, normal.z, true);
     }
-    /** Returns Returns true if the face has positive area in xy parts. */
+    /** Returns true if the face has positive area in xy parts. */
     static testFacePositiveAreaXY(node) {
         return node.countEdgesAroundFace() > 2 && node.signedFaceArea() > 0.0;
     }
-    /** Return true if x and y coordinates of this and other are exactly equal */
+    /** Return true if x and y coordinates of `this` and `other` are exactly equal .*/
     isEqualXY(other) {
         return this.x === other.x && this.y === other.y;
     }
-    /** Return distance between xy coordinates of this and other node */
+    /** Return distance between xy coordinates of `this` and `other` node. */
     distanceXY(other) {
         return Geometry.distanceXYXY(this.x, this.y, other.x, other.y);
     }
-    /** Return distance between xyz coordinates of this and other node */
+    /** Return distance between xyz coordinates of `this` and `other` node. */
     distanceXYZ(other) {
         return Geometry.distanceXYZXYZ(this.x, this.y, this.z, other.x, other.y, other.z);
     }
     /**
-     *
-     * * Evaluate f(node) at each node around a face loop.
-     * * Collect the function values.
-     * @returns Return the array of function values.
+     * Evaluate `f(node)` at each node around `this` node's face loop. Collect the function values.
+     * @param f optional node function. If `undefined`, collect the nodes themselves.
+     * @returns the array of function values.
      */
     collectAroundFace(f) {
         const nodes = [];
         let node = this;
         do {
-            nodes.push(f ? f(node) : node);
+            nodes.push(f ? f(node) : node); // push the node itself if "f" is undefined
             node = node.faceSuccessor;
         } while (node !== this);
         return nodes;
     }
     /**
-     * search around a vertex for nodes that have a specified mask setting.
-     * @param vertexSeed first node to search
-     * @param mask target mask
-     * @param value target value for mask on half edges.
-     * @param collectedNodes optional array to be cleared and receive masked nodes
+     * Search around `this` node's vertex loop for nodes with the specified mask value.
+     * * Returned nodes satisfy `node.isMaskSet(mask) === value`.
+     * @param mask target mask.
+     * @param value target boolean value for mask on half edges.
+     * @param result optional array to be cleared and receive masked nodes.
      */
     collectMaskedEdgesAroundVertex(mask, value = true, result) {
         if (result === undefined)
@@ -841,25 +892,23 @@ class HalfEdge {
         return result;
     }
     /**
-     *
-     * * Evaluate f(node) at each outbound node around this node's vertex loop.
-     * * Collect the function values.
-     * @returns Return the array of function values.
+     * Evaluate `f(node)` at each node around `this` node's vertex loop. Collect the function values.
+     * @param f optional node function. If `undefined`, collect the nodes themselves.
+     * @returns the array of function values.
      */
     collectAroundVertex(f) {
         const nodes = [];
         let node = this;
         do {
-            nodes.push(f ? f(node) : node);
+            nodes.push(f ? f(node) : node); // push the node itself if "f" is undefined
             node = node.vertexSuccessor;
         } while (node !== this);
         return nodes;
     }
     /**
-     *
-     * * Evaluate f(node) at each node around a face loop.
-     * * Sum the function values
-     * @returns Return the sum
+     * Evaluate `f(node)` at each node around `this` node's face loop. Sum the function values.
+     * @param f node to number function.
+     * @returns the sum of function values.
      */
     sumAroundFace(f) {
         let node = this;
@@ -871,10 +920,9 @@ class HalfEdge {
         return sum;
     }
     /**
-     *
-     * * Evaluate f(node) at each outbound node around this node's vertex loop.
-     * * Sum the function values
-     * @returns Return the sum
+     * Evaluate `f(node)` at each node around `this` node's vertex loop. Sum the function values.
+     * @param f node to number function.
+     * @returns the sum of function values.
      */
     sumAroundVertex(f) {
         let node = this;
@@ -885,7 +933,7 @@ class HalfEdge {
         } while (node !== this);
         return sum;
     }
-    /** For all the nodes in the face loop of the given node, clear out the mask given */
+    /** Clear the given mask bits for all nodes in `this` node's face loop. */
     clearMaskAroundFace(mask) {
         let node = this;
         do {
@@ -893,7 +941,7 @@ class HalfEdge {
             node = node.faceSuccessor;
         } while (node !== this);
     }
-    /** For all the nodes in the vertex loop of the given node, clear out the mask given */
+    /** Clear out the given mask bits for all nodes in `this` node's vertex loop. */
     clearMaskAroundVertex(mask) {
         let node = this;
         do {
@@ -902,29 +950,39 @@ class HalfEdge {
         } while (node !== this);
     }
     /**
-     * Compute the signed sum of xy areas of triangles from first node to edges.
+     * Compute the signed xy area of `this` node's face.
      * * A positive area is counterclockwise.
      * * A negative area is clockwise.
-     * @returns signed area of this node's face
+     * @returns signed area of `this` node's face.
      */
     signedFaceArea() {
         let sum = 0;
-        // sum area of trapezoids.
-        // * the formula in the loop gives twice the area (because it does not average the y values).
-        // * this is fixed up at the end by a single multiply by 0.5
-        // * individual trapezoid heights are measured from y at the start node to keep area values numerical smaller.
+        // We start from `this` node and traverse the face, forming trapezoids with vertical bases.
+        // Some trapezoids will have a zero-length base, e.g., a triangle.
+        // Trapezoid bases are measured from `this.y` to keep area values numerically smaller.
+        // Split each trapezoid into two triangles whose y-coordinates are above/below `this.y`.
+        // Each trapezoid's signed area is computed by summing the signed areas of these two triangles.
+        // Area signs depend on careful assignment of signs to trapezoid height (relative to `this.x`) and trapezoid
+        // bases (relative to `this.y`).
+        // Some trapezoids have signed areas outside the face that are cancelled out by subsequent trapezoids.
+        // The formula in the loop accumulates twice the trapezoid areas, so at the end we halve the sum.
+        // Illustration of the algorithm can be found at geometry/internaldocs/Graph.md
+        let x0 = this.x;
+        let x1 = 0.0;
         const y0 = this.y;
         let dy0 = 0.0;
         let dy1 = 0.0;
-        let x0 = this.x;
-        let x1;
         let node1;
         let node0 = this;
         do {
             node1 = node0.faceSuccessor;
             x1 = node1.x;
             dy1 = node1.y - y0;
-            sum += (x0 - x1) * (dy0 + dy1);
+            // When trapezoid bases dy0 and dy1 have opposite sign, this product is (twice) the difference of the areas
+            // of the trapezoid above and below y=y0. This is equal to (twice) the difference of the areas of the congruent
+            // triangles formed by the trapezoid diagonals and bases, a consequence of the other two triangles having equal
+            // area, and thus cancelling out.
+            sum += (x0 - x1) * (dy0 + dy1); // twice trapezoid area = trapezoid height * sum of trapezoid bases
             x0 = x1;
             dy0 = dy1;
             node0 = node1;
@@ -932,108 +990,105 @@ class HalfEdge {
         return 0.5 * sum;
     }
     /**
-     * interpolate xy coordinates between this node and its face successor.
+     * Interpolate xy coordinates between `this` node and its face successor.
      * @param fraction fractional position along this edge.
-     * @param result xy coordinates
+     * @param result optional point to populate and return.
      */
     fractionToPoint2d(fraction, result) {
-        const node1 = this.faceSuccessor;
-        return Point2d.create(this.x + (node1.x - this.x) * fraction, this.y + (node1.y - this.y) * fraction, result);
+        const suc = this.faceSuccessor;
+        return Point2d.create(this.x + (suc.x - this.x) * fraction, this.y + (suc.y - this.y) * fraction, result);
     }
     /**
-     * interpolate xy coordinates between this node and its face successor.
+     * Interpolate xyz coordinates between `this` node and its face successor.
      * @param fraction fractional position along this edge.
-     * @param result xy coordinates
+     * @param result optional point to populate and return.
      */
     fractionToPoint3d(fraction, result) {
-        const node1 = this.faceSuccessor;
-        return Point3d.create(this.x + (node1.x - this.x) * fraction, this.y + (node1.y - this.y) * fraction, this.z + (node1.z - this.z) * fraction, result);
+        const suc = this.faceSuccessor;
+        return Point3d.create(this.x + (suc.x - this.x) * fraction, this.y + (suc.y - this.y) * fraction, this.z + (suc.z - this.z) * fraction, result);
     }
     /**
-     * * interpolate xy coordinates at fractionAlong between this node and its face successor.
-     * * shift to left by fractionPerpendicular
-     * @param fraction fractional position along this edge.
-     * @param result xy coordinates
+     * Interpolate xy coordinates at `fractionAlong` between this node and its face successor. Then shift perpendicular
+     * to the left of this edge by `fractionPerpendicular`.
+     * @param fractionAlong fractional position along this edge.
+     * @param fractionPerpendicular fractional position along the left perpendicular with the same length as this edge.
+     * @param result optional xy coordinates.
      */
     fractionAlongAndPerpendicularToPoint2d(fractionAlong, fractionPerpendicular, result) {
-        const node1 = this.faceSuccessor;
-        const dx = node1.x - this.x;
-        const dy = node1.y - this.y;
+        const suc = this.faceSuccessor;
+        const dx = suc.x - this.x;
+        const dy = suc.y - this.y;
         return Point2d.create(this.x + dx * fractionAlong - dy * fractionPerpendicular, this.y + dy * fractionAlong + dx * fractionPerpendicular, result);
     }
-    /**
-     * return the 3d coordinates at this half edge base
-     */
+    /** Return the 3d coordinates at this half edge. */
     getPoint3d(result) {
         return Point3d.create(this.x, this.y, this.z, result);
     }
-    /**
-     * return the 2d coordinates at this half edge base
-     */
+    /** Return the 2d coordinates at this half edge. */
     getPoint2d(result) {
         return Point2d.create(this.x, this.y, result);
     }
-    /**
-     * return a 3d vector from start to end of this half edge.
-     */
+    /** Return a 3d vector from start to end of this half edge. */
     getVector3dAlongEdge(result) {
-        const nodeB = this.faceSuccessor;
-        return Vector3d.create(nodeB.x - this.x, nodeB.y - this.y, nodeB.z - this.z, result);
+        const suc = this.faceSuccessor;
+        return Vector3d.create(suc.x - this.x, suc.y - this.y, suc.z - this.z, result);
     }
-    /**
-     * return a 2d vector from start to end of this half edge
-     */
+    /** Return a 2d vector from start to end of this half edge. */
     getVector2dAlongEdge(result) {
-        const nodeB = this.faceSuccessor;
-        return Vector2d.create(nodeB.x - this.x, nodeB.y - this.y, result);
+        const suc = this.faceSuccessor;
+        return Vector2d.create(suc.x - this.x, suc.y - this.y, result);
     }
     /**
-     * Return the interpolated x coordinate between this node and its face successor.
+     * Return the interpolated x coordinate between `this` node and its face successor.
      * @param fraction fractional position along this edge.
      */
     fractionToX(fraction) {
-        const node1 = this.faceSuccessor;
-        return this.x + (node1.x - this.x) * fraction;
+        const suc = this.faceSuccessor;
+        return this.x + (suc.x - this.x) * fraction;
     }
     /**
-     * Return the interpolated y coordinate between this node and its face successor.
+     * Return the interpolated y coordinate between `this` node and its face successor.
      * @param fraction fractional position along this edge.
      */
     fractionToY(fraction) {
-        const node1 = this.faceSuccessor;
-        return this.y + (node1.y - this.y) * fraction;
+        const suc = this.faceSuccessor;
+        return this.y + (suc.y - this.y) * fraction;
     }
     /**
-     * Return the interpolated z coordinate between this node and its face successor.
+     * Return the interpolated z coordinate between `this` node and its face successor.
      * @param fraction fractional position along this edge.
      */
     fractionToZ(fraction) {
-        const node1 = this.faceSuccessor;
-        return this.z + (node1.z - this.z) * fraction;
+        const suc = this.faceSuccessor;
+        return this.z + (suc.z - this.z) * fraction;
     }
     /**
-     * * Compute fractional coordinates of the intersection of edges from given base nodes
+     * Compute fractional coordinates of the intersection of edges from given base nodes.
      * * If parallel or colinear, return undefined.
      * * If (possibly extended) lines intersect, return the fractions of intersection as x,y in the result.
-     * @param nodeA0 Base node of edge A
-     * @param nodeB0 Base node of edge B
-     * @param result optional preallocated result
+     * @param nodeA0 base node of edge A.
+     * @param nodeB0 base node of edge B.
+     * @param result optional preallocated result.
      */
     static transverseIntersectionFractions(nodeA0, nodeB0, result) {
         const nodeA1 = nodeA0.faceSuccessor;
         const nodeB1 = nodeB0.faceSuccessor;
         if (!result)
             result = Vector2d.create();
+        // To find the fraction of intersection (ta,tb), you need to solve these 2 equations:
+        // (nodeA1.x - nodeA0.x)ta + (nodeB0.x - nodeB1.x)tb = nodeB0.x - nodeA0.x
+        // (nodeA1.y - nodeA0.y)ta + (nodeB0.y - nodeB1.y)tb = nodeB0.y - nodeA0.y
+        // Proof can be found at geometry/internaldocs/Graph.md
         if (SmallSystem.linearSystem2d(nodeA1.x - nodeA0.x, nodeB0.x - nodeB1.x, nodeA1.y - nodeA0.y, nodeB0.y - nodeB1.y, nodeB0.x - nodeA0.x, nodeB0.y - nodeA0.y, result))
             return result;
         return undefined;
     }
     /**
-     * * Compute fractional coordinates of the intersection of a horizontal line with an edge.
+     * Compute fractional position (possibly outside 0..1) of the intersection of a horizontal line with an edge.
      * * If the edge is horizontal with (approximate) identical y, return the node.
-     * * If the edge is horizontal with different y, return undefined.
-     * * If the edge is not horizontal, return the fractional position (possibly outside 0..1) of the intersection.
-     * @param node0 Base node of edge
+     * * If the edge is horizontal with different y, return `undefined`.
+     * @param node0 base node of edge.
+     * @param y y coordinate of the horizontal line.
      */
     static horizontalScanFraction(node0, y) {
         const node1 = node0.faceSuccessor;
@@ -1042,13 +1097,16 @@ class HalfEdge {
             return node0;
         if (Geometry.isSameCoordinate(dy, 0.0))
             return undefined;
+        // parametric equation of line is (1-t)y0 + ty1 which is equal to y at the intersection so
+        // (1-t)y0 + ty1 = y or t = (y-y0)/(y1-y0)
         return Geometry.conditionalDivideFraction(y - node0.y, dy);
     }
     /**
-     * * Compute fractional coordinates of the intersection of a horizontal line with an edge.
-     * * If the edge is horizontal return undefined (no test for horizontal at y!!!)
-     * * If the edge is not horizontal and y is between its end y's, return the fraction
-     * @param node0 Base node of edge
+     * Compute fractional position (inside 0..1) of the intersection of a horizontal line with an edge.
+     * * If fractional position is outside 0..1, return `undefined`.
+     * * If the edge is horizontal return `undefined` (no test for horizontal at y).
+     * @param node0 base node of edge.
+     * @param y y coordinate of the horizontal line.
      */
     static horizontalScanFraction01(node0, y) {
         const node1 = node0.faceSuccessor;
@@ -1063,12 +1121,12 @@ class HalfEdge {
         return undefined;
     }
     /**
-     * Copy various data from source to this.
-     * @param source other half edge.
-     * @param XYZ copy simple coordinates
-     * @param copyVertexData true to copy data belonging to the vertex. (i.e. the "i" member)
-     * @param copyVertexData true to copy data belonging to the edge. (i.e. call transferEdgeData)
-     * @param copyFaceData true to copy faceTag
+     * Copy various data from source to `this`.
+     * @param source source half edge.
+     * @param copyXYZ true to copy xyz coordinates.
+     * @param copyVertexData true to copy data belonging to the vertex (i.e. the `i` member).
+     * @param copyEdgeData true to copy data belonging to the edge (i.e. edge masks, `edgeTag`).
+     * @param copyFaceData true to copy `faceTag`.
      */
     copyDataFrom(source, copyXYZ, copyVertexData, copyEdgeData, copyFaceData) {
         if (copyXYZ) {
@@ -1088,13 +1146,16 @@ class HalfEdge {
         }
     }
 }
-HalfEdge._edgePropertyMasks = [HalfEdgeMask.BOUNDARY_EDGE, HalfEdgeMask.EXTERIOR, HalfEdgeMask.PRIMARY_EDGE, HalfEdgeMask.NULL_FACE];
 HalfEdge._totalNodesCreated = 0;
+/** Edge property masks. */
+HalfEdge._edgePropertyMasks = [
+    HalfEdgeMask.BOUNDARY_EDGE, HalfEdgeMask.EXTERIOR, HalfEdgeMask.PRIMARY_EDGE, HalfEdgeMask.NULL_FACE,
+];
 export { HalfEdge };
 /**
  * A HalfEdgeGraph has:
- * * An array of (pointers to ) HalfEdge objects.
- * * A pool of masks for grab/drop use by algorithms.
+ * * An array of (pointers to) HalfEdge objects.
+ * * A pool of masks for grab/drop used by algorithms.
  * @internal
  */
 export class HalfEdgeGraph {
@@ -1103,7 +1164,8 @@ export class HalfEdgeGraph {
         this.allHalfEdges = [];
         this._maskManager = MaskManager.create(HalfEdgeMask.ALL_GRAB_DROP_MASKS);
     }
-    /** Ask for a mask (from the graph's free pool.) for caller's use.
+    /**
+     * Ask for a mask (from the graph's free pool) for caller's use.
      * * Optionally clear the mask throughout the graph.
      */
     grabMask(clearInAllHalfEdges = true) {
@@ -1113,49 +1175,49 @@ export class HalfEdgeGraph {
         }
         return mask;
     }
+    /** Return `mask` to the free pool. */
+    dropMask(mask) {
+        this._maskManager.dropMask(mask);
+    }
     /**
-     * Return `mask` to the free pool.
-     */
-    dropMask(mask) { this._maskManager.dropMask(mask); }
-    /**
-     * * Create 2 half edges forming 2 vertices, 1 edge, and 1 face
-     * * The two edges are joined as edgeMate pair.
-     * * The two edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
-     * * The two edges are added to the graph's HalfEdge set
-     * @returns Return pointer to the first half edge created.
+     * Create 2 half edges forming 2 vertices, 1 edge, and 1 face.
+     * * The two half edges are joined as edgeMate pair.
+     * * The two half edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
+     * * The two half edges are added to the graph's HalfEdge set.
+     * @returns pointer to the first half edge created.
      */
     createEdgeXYZXYZ(xA = 0, yA = 0, zA = 0, iA = 0, xB = 0, yB = 0, zB = 0, iB = 0) {
-        const a = HalfEdge.createHalfEdgePairWithCoordinates(xA, yA, zA, iA, xB, yB, zB, iB, this.allHalfEdges);
-        return a;
+        return HalfEdge.createHalfEdgePairWithCoordinates(xA, yA, zA, iA, xB, yB, zB, iB, this.allHalfEdges);
     }
     /**
-     * * Create 2 half edges forming 2 vertices, 1 edge, and 1 face
-     * * The two edges are joined as edgeMate pair.
-     * * The two edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
-     * * The two edges are added to the graph's HalfEdge set
+     * Create 2 half edges forming 2 vertices, 1 edge, and 1 face.
+     * * The two half edges are joined as edgeMate pair.
+     * * The two half edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
+     * * The two half edges are added to the graph's HalfEdge set.
      * * Coordinates are set to zero.
-     * * ids are installed in the two half edges.
-     * @returns Return pointer to the first half edge created.  (This has idA as its id.)
+     * * IDs are installed in the two half edges.
+     * @returns pointer to the first half edge created, with ID set to iA.
      */
     createEdgeIdId(iA = 0, iB = 0) {
-        const a = HalfEdge.createHalfEdgePairWithCoordinates(0.0, 0.0, 0.0, iA, 0.0, 0.0, 0.0, iB, this.allHalfEdges);
-        return a;
+        return HalfEdge.createHalfEdgePairWithCoordinates(0.0, 0.0, 0.0, iA, 0.0, 0.0, 0.0, iB, this.allHalfEdges);
     }
     /**
-     * * create an edge from coordinates x,y,z to (the tail of) an existing half edge.
-     * @returns Return pointer to the half edge with tail at x,y,z
+     * Create an edge from coordinates x,y,z connected to the graph at the vertex of the given `node`.
+     * @returns pointer to the dangling node at x,y,z.
      */
     createEdgeXYZHalfEdge(xA = 0, yA = 0, zA = 0, iA = 0, node, iB = 0) {
+        // Visualization can be found at geometry/internaldocs/Graph.md
         const a = HalfEdge.createHalfEdgePairWithCoordinates(xA, yA, zA, iA, node.x, node.y, node.z, iB, this.allHalfEdges);
         const b = a.faceSuccessor;
         HalfEdge.pinch(node, b);
         return a;
     }
     /**
-     * * create an edge from coordinates x,y,z to (the tail of) an existing half edge.
-     * @returns Return pointer to the half edge with tail at x,y,z
+     * Create an edge from the vertex of `nodeA` to the vertex of `nodeB`.
+     * @returns pointer to the new half edge at the vertex of `nodeA`.
      */
     createEdgeHalfEdgeHalfEdge(nodeA, idA, nodeB, idB = 0) {
+        // Visualization can be found at geometry/internaldocs/Graph.md
         const a = HalfEdge.createHalfEdgePairWithCoordinates(nodeA.x, nodeA.y, nodeA.z, idA, nodeB.x, nodeB.y, nodeB.z, idB, this.allHalfEdges);
         const b = a.faceSuccessor;
         HalfEdge.pinch(nodeA, a);
@@ -1163,56 +1225,56 @@ export class HalfEdgeGraph {
         return a;
     }
     /**
-     * * Create 2 half edges forming 2 vertices, 1 edge, and 1 face
-     * * The two edges are joined as edgeMate pair.
-     * * The two edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
-     * * The two edges are added to the graph's HalfEdge set
-     * @returns Return pointer to the first half edge created.
+     * Create 2 half edges forming 2 vertices, 1 edge, and 1 face
+     * * The two half edges are joined as edgeMate pair.
+     * * The two half edges are a 2-half-edge face loop in both the faceSuccessor and facePredecessor directions.
+     * * The two half edges are added to the graph's HalfEdge set.
+     * @returns pointer to the first half edge created, with coordinates `xyz0`.
      */
     createEdgeXYAndZ(xyz0, id0, xyz1, id1) {
-        const a = HalfEdge.createHalfEdgePairWithCoordinates(xyz0.x, xyz0.y, xyz0.z, id0, xyz1.x, xyz1.y, xyz1.z, id1, this.allHalfEdges);
-        return a;
+        return HalfEdge.createHalfEdgePairWithCoordinates(xyz0.x, xyz0.y, xyz0.z, id0, xyz1.x, xyz1.y, xyz1.z, id1, this.allHalfEdges);
     }
     /**
-     * * Insert a vertex in the edge beginning at base.
-     * * this creates two half edges.
-     * * The base of the new edge is 'after' the (possibly undefined) start node in its face loop.
-     * * The existing mate retains its base xyz and i properties but is no longer the mate of base.
-     * * The base and existing mate each become mates with a new half edge.
-     * @returns Returns the reference to the half edge created.
+     * Create a new vertex within the edge beginning at `base`.
+     * * This creates two new nodes in their own vertex loop.
+     * * If the base is undefined, create a single-edge loop.
+     * * Existing nodes stay in their face and vertex loops and retain xyz and i values.
+     * * Unlike [[pinch]], this breaks the edgeMate pairing of the input edge:
+     * each node of the input edge gets a new node as its edge mate.
+     * * On each side of the edge, if edgeTag is present, it is copied to the new node on that side.
+     * @returns reference to the half edge created, the new face successor of `base`.
      */
     splitEdge(base, xA = 0, yA = 0, zA = 0, iA = 0) {
-        const he = HalfEdge.splitEdge(base, xA, yA, zA, iA, this.allHalfEdges);
-        return he;
+        return HalfEdge.splitEdge(base, xA, yA, zA, iA, this.allHalfEdges);
     }
     /**
-     * * Create a sliver face "within" an edge.
-     * * this creates two half edges.
-     * * The existing edges both stay in their same face loops and retain coordinates and i value.
-     * * Each existing edge's mate is a new edge (rather than original mate)
-     * * Coordinates are copied to the new edges at respective vertices.
-     * * New faceTag and edgeTag undefined.
-     * * i members are copied around their respective vertices.
-     * @returns Returns the reference to the half edge created.
+     * Create a new sliver face "inside" an existing edge.
+     * * This creates two nodes that are each face predecessor and successor to the other.
+     * * Existing nodes stay in their face and vertex loops and retain xyz and i values.
+     * * Unlike [[pinch]], this breaks the edgeMate pairing of the input edge:
+     * each node of the input edge gets a new node as its edge mate.
+     * * New nodes get the xyz and i values shared by the nodes in the vertex loops into which they are placed.
+     * * New nodes' faceTag and edgeTag are `undefined`.
+     * @returns reference to the half edge created in the vertex loop of baseA.
      */
     splitEdgeCreateSliverFace(base) {
-        const he = HalfEdge.splitEdgeCreateSliverFace(base, this.allHalfEdges);
-        return he;
+        return HalfEdge.splitEdgeCreateSliverFace(base, this.allHalfEdges);
     }
     /**
-     * * Insert a vertex in the edge beginning at base, with coordinates specified as a fraction along the existing edge.
-     * * this creates two half edges.
-     * * The base of the new edge is 'after' the (possibly undefined) start node in its face loop.
-     * * The existing mate retains its base xyz and i properties but is no longer the mate of base.
-     * * The base and existing mate each become mates with a new half edge.
-     * @returns Returns the reference to the half edge created.
+     * Create a new vertex within the edge beginning at `base`, with coordinates specified by a fraction along the edge.
+     * * This creates two new nodes in their own vertex loop.
+     * * Existing nodes stay in their face and vertex loops and retain xyz and i values.
+     * * Unlike [[pinch]], this breaks the edgeMate pairing of the input edge:
+     * each node of the input edge gets a new node as its edge mate.
+     * * On each side of the edge, if edgeTag is present, it is copied to the new node on that side.
+     * @returns reference to the half edge created, the new face successor of `base`.
      */
     splitEdgeAtFraction(base, fraction) {
-        const he = HalfEdge.splitEdge(base, base.fractionToX(fraction), base.fractionToY(fraction), base.fractionToZ(fraction), 0, this.allHalfEdges);
-        return he;
+        return HalfEdge.splitEdge(base, base.fractionToX(fraction), base.fractionToY(fraction), base.fractionToZ(fraction), 0, this.allHalfEdges);
     }
-    /** This is a destructor-like action that eliminates all interconnection among the graph's nodes.
-     * After this is called the graph is unusable.
+    /**
+     * This is a destructor-like action that eliminates all inter-connections among the graph's nodes.
+     * After this is called, the graph is unusable.
      */
     decommission() {
         for (const node of this.allHalfEdges) {
@@ -1221,8 +1283,9 @@ export class HalfEdgeGraph {
         this.allHalfEdges.length = 0;
         this.allHalfEdges = undefined;
     }
-    /** create two nodes of a new edge.
-     * @returns Return one of the two nodes, which the caller may consider as the start of the edge.
+    /**
+     * Create two nodes of a new edge.
+     * @returns the reference to the new node at (x0,y0).
      */
     addEdgeXY(x0, y0, x1, y1) {
         const baseNode = HalfEdge.createEdgeXYXY(this._numNodesCreated, x0, y0, this._numNodesCreated + 1, x1, y1);
@@ -1231,17 +1294,17 @@ export class HalfEdgeGraph {
         this.allHalfEdges.push(baseNode.faceSuccessor);
         return baseNode;
     }
-    /** Clear selected bits in all nodes of the graph. */
+    /** Clear selected `mask` bits in all nodes of the graph. */
     clearMask(mask) {
         for (const node of this.allHalfEdges)
             node.maskBits &= ~mask;
     }
-    /** Set selected bits in all nodes of the graph. */
+    /** Set selected `mask` bits in all nodes of the graph. */
     setMask(mask) {
         for (const node of this.allHalfEdges)
             node.maskBits |= mask;
     }
-    /** toggle selected bits in all nodes of the graph. */
+    /** Toggle selected `mask` bits in all nodes of the graph. */
     reverseMask(mask) {
         for (const node of this.allHalfEdges) {
             node.maskBits ^= mask;
@@ -1258,10 +1321,11 @@ export class HalfEdgeGraph {
                 n++;
         return n;
     }
-    /** Return an array LineSegment3d.
-     * * The array has one segment per edge
+    /**
+     * Return an array of LineSegment3d.
+     * * The array has one segment per edge.
      * * The coordinates are taken from a node and its face successor.
-     * * On each edge, the line segment start at the HalfEdge with lower id than its edgeMate.
+     * * On each edge, the line segment starts at the HalfEdge with lower ID than its edgeMate.
      */
     collectSegments() {
         const segments = [];
@@ -1271,24 +1335,27 @@ export class HalfEdgeGraph {
         }
         return segments;
     }
-    /** Returns the number of vertex loops in a graph structure */
+    /** Returns the number of vertex loops in a graph structure. */
     countVertexLoops() {
         this.clearMask(HalfEdgeMask.VISITED);
         let count = 0;
-        this.announceVertexLoops((_graph, _seed) => { count++; return true; });
+        this.announceVertexLoops((_graph, _seed) => {
+            count++;
+            return true;
+        });
         return count;
     }
-    /** Returns the number of face loops */
+    /** Returns the number of face loops in a graph structure. */
     countFaceLoops() {
         this.clearMask(HalfEdgeMask.VISITED);
         let count = 0;
-        this.announceFaceLoops((_graph, _seed) => { count++; return true; });
+        this.announceFaceLoops((_graph, _seed) => {
+            count++;
+            return true;
+        });
         return count;
     }
-    /**
-     * Returns the number of face loops satisfying a filter function with mask argument.
-     *
-     */
+    /** Returns the number of face loops satisfying a filter function with mask argument. */
     countFaceLoopsWithMaskFilter(filter, mask) {
         this.clearMask(HalfEdgeMask.VISITED);
         let count = 0;
@@ -1299,32 +1366,47 @@ export class HalfEdgeGraph {
         });
         return count;
     }
-    /** Returns an array of nodes, where each node represents a starting point of a face loop.
-     */
+    /** Returns an array of nodes, where each node represents a starting point of a vertex loop. */
+    collectVertexLoops() {
+        const returnArray = [];
+        this.announceVertexLoops((_graph, node) => {
+            returnArray.push(node);
+            return true;
+        });
+        return returnArray;
+    }
+    /** Returns an array of nodes, where each node represents a starting point of a face loop. */
     collectFaceLoops() {
         const returnArray = [];
-        this.announceFaceLoops((_graph, node) => { returnArray.push(node); return true; });
+        this.announceFaceLoops((_graph, node) => {
+            returnArray.push(node);
+            return true;
+        });
         return returnArray;
     }
-    /** Returns an array of nodes, where each node represents a starting point of a vertex loop.
+    /**
+     * Visit each vertex loop of the graph once.
+     * * Call the `announceVertex` function.
+     * * Continue search if `announceVertex(graph, node)` returns `true`.
+     * * Terminate search if `announceVertex(graph, node)` returns `false`.
+     * @param announceVertex function to apply at one node of each vertex.
      */
-    collectVertexLoops() {
+    announceVertexLoops(announceVertex) {
         this.clearMask(HalfEdgeMask.VISITED);
-        const returnArray = [];
         for (const node of this.allHalfEdges) {
             if (node.getMask(HalfEdgeMask.VISITED))
                 continue;
-            returnArray.push(node);
             node.setMaskAroundVertex(HalfEdgeMask.VISITED);
+            if (!announceVertex(this, node))
+                break;
         }
-        return returnArray;
     }
     /**
-     * * Visit each facet of the graph once.
-     * * Call the announceFace function
-     * * continue search if announceFace(graph, node) returns true
-     * * terminate search if announce face (graph, node) returns false
-     * @param  announceFace function to apply at one node of each face.
+     * Visit each facet of the graph once.
+     * * Call the `announceFace` function.
+     * * Continue search if `announceFace(graph, node)` returns `true`.
+     * * Terminate search if `announceFace(graph, node)` returns `false`.
+     * @param announceFace function to apply at one node of each face.
      */
     announceFaceLoops(announceFace) {
         this.clearMask(HalfEdgeMask.VISITED);
@@ -1337,13 +1419,13 @@ export class HalfEdgeGraph {
         }
     }
     /**
-       * * Visit each edge of the graph once.
-       * * Call the announceEdge function.
-       * * the edge mate will NOT appear in an announceEdge call.
-       * * continue search if announceEdge(graph, node) returns true
-       * * terminate search if announceEdge (graph, node) returns false
-       * @param  announceEdge function to apply at one node of each edge.
-       */
+     * Visit each edge of the graph once.
+     * * Call the `announceEdge` function.
+     * * The edge mate will NOT appear in an announceEdge call.
+     * * Continue search if `announceEdge(graph, node)` returns `true`.
+     * * Terminate search if `announceEdge(graph, node)` returns `false`.
+     * @param announceEdge function to apply at one node of each edge.
+     */
     announceEdges(announceEdge) {
         this.clearMask(HalfEdgeMask.VISITED);
         for (const node of this.allHalfEdges) {
@@ -1357,28 +1439,11 @@ export class HalfEdgeGraph {
         }
     }
     /**
-     * * Visit each vertex loop of the graph once.
-     * * Call the announceVertex function
-     * * continue search if announceVertex(graph, node) returns true
-     * * terminate search if announce vertex (graph, node) returns false
-     * @param  announceVertex function to apply at one node of each face.
-     */
-    announceVertexLoops(announceVertex) {
-        this.clearMask(HalfEdgeMask.VISITED);
-        for (const node of this.allHalfEdges) {
-            if (node.getMask(HalfEdgeMask.VISITED))
-                continue;
-            node.setMaskAroundVertex(HalfEdgeMask.VISITED);
-            if (!announceVertex(this, node))
-                break;
-        }
-    }
-    /**
-     * * Visit each half edge (node) of the graph once.
-     * * Call the announceNode function
-     * * continue search if announceNode(graph, node) returns true
-     * * terminate search if announce face (graph, node) returns false
-     * @param  announceNode function to apply at one node of each face.
+     * Visit each half edge (node) of the graph once.
+     * * Call the `announceNode` function.
+     * * Continue search if `announceNode(graph, node)` returns `true`.
+     * * Terminate search if `announceFace(graph, node)` returns `false`.
+     * @param announceNode function to apply at each node.
      */
     announceNodes(announceNode) {
         for (const node of this.allHalfEdges) {
@@ -1386,8 +1451,10 @@ export class HalfEdgeGraph {
                 break;
         }
     }
-    /** Return the number of nodes in the graph */
-    countNodes() { return this.allHalfEdges.length; }
+    /** Return the number of nodes in the graph. */
+    countNodes() {
+        return this.allHalfEdges.length;
+    }
     /** Apply transform to the xyz coordinates in the graph. */
     transformInPlace(transform) {
         for (const node of this.allHalfEdges) {
@@ -1395,8 +1462,8 @@ export class HalfEdgeGraph {
         }
     }
     /**
-     * disconnect and delete all nodes that satisfy a filter condition.
-     * @param deleteThisNode returns true to delete the corresponding edge. Should act symmetrically on the edgeMate.
+     * Disconnect and delete all nodes that satisfy a filter condition.
+     * @param deleteThisNode returns true to delete the corresponding node. Should act symmetrically on the edgeMate.
      * @returns the number of nodes deleted (twice the number of deleted edges).
      */
     yankAndDeleteEdges(deleteThisNode) {
@@ -1405,9 +1472,9 @@ export class HalfEdgeGraph {
         for (let i = 0; i < numTotal; i++) {
             const candidate = this.allHalfEdges[i];
             if (!deleteThisNode(candidate))
-                this.allHalfEdges[numAccepted++] = candidate;
+                this.allHalfEdges[numAccepted++] = candidate; // overwrite a previously "deleted node"
             else
-                candidate.yankFromVertexLoop(); // ASSUME callback symmetry so we eventually yank the mate!
+                candidate.yankFromVertexLoop(); // assume callback symmetry so we eventually yank the mate
         }
         const numDeleted = numTotal - numAccepted;
         this.allHalfEdges.length = numAccepted;