@itwin/core-geometry 4.7.0-dev.7 → 4.7.0-dev.8

package/lib/esm/polyface/PolyfaceQuery.js

@@ -6,6 +6,7 @@
  * @module Polyface
  */
 /* eslint-disable @typescript-eslint/naming-convention, no-empty */
+// cspell:word internaldocs
 import { BagOfCurves } from "../curve/CurveCollection";
 import { CurveOps } from "../curve/CurveOps";
 import { MultiChainCollector } from "../curve/internalContexts/MultiChainCollector";
@@ -48,8 +49,7 @@ import { RangeLengthData } from "./RangeLengthData";
  * @public
  */
 export class SweepLineStringToFacetsOptions {
-    /** constructor -- captures fully-checked parameters from static create method.
-    */
+    /** Constructor. Captures fully-checked parameters from static create method. */
     constructor(vectorToEye, sideAngle, assembleChains, collectOnForwardFacets, collectOnSideFacets, collectOnRearFacets) {
         this.vectorToEye = vectorToEye;
         this.sideAngle = sideAngle;
@@ -58,20 +58,27 @@ export class SweepLineStringToFacetsOptions {
         this.collectOnSideFacets = collectOnSideFacets;
         this.collectOnRearFacets = collectOnRearFacets;
     }
-    /** Create an options structure.
-     * * Default vectorToEye is positive Z
-     * * Default sideAngle has radians value Geometry.smallAngleRadians
-     * * Default assembleChains is true
-     * * Default collectOnForwardFacets, collectOnSideFacets, collectOnRearFacets are all true.
+    /**
+     * Create an options structure.
+     * * Default `vectorToEye` is (0,0,1).
+     * * Default `sideAngle` is `Geometry.smallAngleRadians`.
+     * * Default `assembleChains` is `true`.
+     * * Default `collectOnForwardFacets`, `collectOnSideFacets`, `collectOnRearFacets` are all `true`.
      */
     static create(vectorToEye, sideAngle, assembleChains, collectOnForwardFacets, collectOnSideFacets, collectOnRearFacets) {
         return new SweepLineStringToFacetsOptions(vectorToEye === undefined ? Vector3d.unitZ() : vectorToEye.clone(), sideAngle === undefined ? Angle.createRadians(Geometry.smallAngleRadians) : sideAngle.clone(), Geometry.resolveValue(assembleChains, true), Geometry.resolveValue(collectOnForwardFacets, true), Geometry.resolveValue(collectOnSideFacets, true), Geometry.resolveValue(collectOnRearFacets, true));
     }
-    /** Return true if all outputs are requested */
-    get collectAll() { return this.collectOnForwardFacets === true && this.collectOnRearFacets === true && this.collectOnRearFacets === true; }
-    /** Decide if the instance flags accept this facet.
-     * * Facets whose facet normal have positive, zero, or negative dot product with the vectorToEye are forward, side, and rear.
-     * * Undefined facet normal returns false
+    /** Return `true` if all outputs are requested. */
+    get collectAll() {
+        return this.collectOnForwardFacets === true &&
+            this.collectOnSideFacets === true &&
+            this.collectOnRearFacets === true;
+    }
+    /**
+     * Decide if the instance collector flags accept a facet with the given normal.
+     * * A facet whose facet normal has a positive, zero, or negative dot product with `vectorToEye` is classified
+     * as forward, side, or rear, respectively.
+     * * `undefined` facet normal returns `false`.
     */
     collectFromThisFacetNormal(facetNormal) {
         if (facetNormal === undefined)
@@ -85,22 +92,27 @@ export class SweepLineStringToFacetsOptions {
 /**
  * Options carrier for [[PolyfaceQuery.cloneOffset]].
  * * Default options are strongly recommended.
- * * The option most likely to be changed is chamferTurnAngle
+ * * The option most likely to be changed is `chamferAngleBetweenNormals`.
  * @public
  */
 export class OffsetMeshOptions {
-    /** Constructor -- CAPTURE parameters ... */
-    constructor(smoothSingleAngleBetweenNormals = Angle.createDegrees(25), smoothAccumulatedAngleBetweenNormals = Angle.createDegrees(60), chamferTurnAngle = Angle.createDegrees(90)) {
+    /** Constructor -- CAPTURE parameters. */
+    constructor(smoothSingleAngleBetweenNormals = Angle.createDegrees(25), smoothAccumulatedAngleBetweenNormals = Angle.createDegrees(60), chamferAngleBetweenNormals = Angle.createDegrees(90)) {
         this.smoothSingleAngleBetweenNormals = smoothSingleAngleBetweenNormals.clone();
         this.smoothAccumulatedAngleBetweenNormals = smoothAccumulatedAngleBetweenNormals.clone();
-        this.chamferAngleBetweenNormals = chamferTurnAngle.clone();
+        this.chamferAngleBetweenNormals = chamferAngleBetweenNormals.clone();
     }
-    /** construct and return an OffsetMeshOptions with given parameters.
+    /**
+     * Construct and return an `OffsetMeshOptions` with given parameters.
      * * Angles are forced to minimum values.
      * * Clones of the angles are given to the constructor.
-     * @param smoothSingleRadiansBetweenNormals an angle larger than this (between facets) is considered a sharp edge
-     * @param smoothAccumulatedAngleBetweenNormals angles that sum to this much may be consolidated for average normal
-     * @param chamferTurnAngleBetweenNormals when facets meet with larger angle, a chamfer edge may be added if the angle between facet normals is larger than this.
+     * @param smoothSingleRadiansBetweenNormals an angle larger than this (between facets) is considered a sharp edge.
+     * Default value is `25` degrees.
+     * @param smoothAccumulatedAngleBetweenNormals angles that sum to this much may be consolidated for average normal.
+     * Default value is `60` degrees.
+     * @param chamferTurnAngleBetweenNormals when facets meet and the turn angle (i.e., angle between facet normals)
+     * is larger than `chamferTurnAngleBetweenNormals`, a chamfer edge may be added to prevent offset mesh from having
+     * facets that extend out too far away from the source mesh. Default value is `120` degrees.
      */
     static create(smoothSingleAngleBetweenNormals = Angle.createDegrees(25), smoothAccumulatedAngleBetweenNormals = Angle.createDegrees(60), chamferTurnAngleBetweenNormals = Angle.createDegrees(120)) {
         const mySmoothSingleRadiansBetweenNormals = smoothSingleAngleBetweenNormals.clone();
@@ -116,25 +128,27 @@ export class OffsetMeshOptions {
     }
 }
 /**
- * Enumeration of cases for retaining facets among duplicates
+ * Enumeration of cases for retaining facets among duplicates.
  * @public
  */
 export var DuplicateFacetClusterSelector;
 (function (DuplicateFacetClusterSelector) {
-    /** retain none of the duplicates */
+    /** Retain none of the duplicates. */
     DuplicateFacetClusterSelector[DuplicateFacetClusterSelector["SelectNone"] = 0] = "SelectNone";
-    /** retain any one member among duplicates */
+    /** Retain any one member among duplicates. */
     DuplicateFacetClusterSelector[DuplicateFacetClusterSelector["SelectAny"] = 1] = "SelectAny";
-    /** retain all members among duplicates */
+    /** Retain all members among duplicates. */
     DuplicateFacetClusterSelector[DuplicateFacetClusterSelector["SelectAll"] = 2] = "SelectAll";
-    /** retain one from any cluster with an odd number of faces */
+    /** Retain one from any cluster with an odd number of faces. */
     DuplicateFacetClusterSelector[DuplicateFacetClusterSelector["SelectOneByParity"] = 3] = "SelectOneByParity";
 })(DuplicateFacetClusterSelector || (DuplicateFacetClusterSelector = {}));
-/** PolyfaceQuery is a static class whose methods implement queries on a polyface or polyface visitor provided as a parameter to each method.
+/**
+ * PolyfaceQuery is a static class whose methods implement queries on a `Polyface` or `PolyfaceVisitor` provided as a
+ * parameter to each method.
  * @public
  */
 export class PolyfaceQuery {
-    /** copy the points from a visitor into a Linestring3d in a Loop object */
+    /** Copy the points from a visitor into a linestring loop. */
     static visitorToLoop(visitor) {
         const ls = LineString3d.createPoints(visitor.point.getPoint3dArray());
         return Loop.create(ls);
@@ -149,11 +163,15 @@ export class PolyfaceQuery {
         }
         return result;
     }
-    /** Return the sum of all facet areas.
-     * @param vectorToEye compute sum of *signed* facet areas projected to a view plane perpendicular to this vector
-    */
+    /**
+     * Sum all facet areas.
+     * @param source polyface or visitor.
+     * @param vectorToEye compute sum of (signed) facet areas projected to a view plane perpendicular to `vectorToEye`.
+     * If `vectorToEye` is not provided, actual facet areas are calculated (without any projection).
+     * @returns the sum of all facet areas. Return 0 if `source` is `undefined`.
+     */
     static sumFacetAreas(source, vectorToEye) {
-        let s = 0;
+        let sum = 0;
         if (source !== undefined) {
             if (source instanceof Polyface)
                 return PolyfaceQuery.sumFacetAreas(source.createVisitor(1), vectorToEye);
@@ -162,20 +180,21 @@ export class PolyfaceQuery {
                 unitVectorToEye = vectorToEye.normalize();
             source.reset();
             while (source.moveToNextFacet()) {
-                const scaledNormal = PolygonOps.areaNormal(source.point.getPoint3dArray());
-                s += unitVectorToEye ? scaledNormal.dotProduct(unitVectorToEye) : scaledNormal.magnitude();
+                const areaNormal = PolygonOps.areaNormal(source.point.getPoint3dArray());
+                sum += unitVectorToEye ? areaNormal.dotProduct(unitVectorToEye) : areaNormal.magnitude();
             }
         }
-        return s;
+        return sum;
     }
-    /** sum volumes of tetrahedra from origin to all facets.
-     * * if origin is omitted, the first point encountered (by the visitor) is used as origin.
+    /**
+     * Sum volumes of tetrahedra from origin to all facets.
+     * * If origin is `undefined`, the first point encountered (by the visitor) is used as origin.
      * * If the mesh is closed, this sum is the volume.
-     * * If the mesh is not closed, this sum is the volume of a mesh with various additional facets
-     * from the origin to facets.
-    */
+     * * If the mesh is not closed, this sum is the volume of a mesh with various additional facets from the origin
+     * to facets.
+     */
     static sumTetrahedralVolumes(source, origin) {
-        let s = 0;
+        let sum = 0;
         if (source instanceof Polyface)
             return PolyfaceQuery.sumTetrahedralVolumes(source.createVisitor(0), origin);
         let myOrigin = origin;
@@ -190,17 +209,18 @@ export class PolyfaceQuery {
             for (let i = 1; i + 1 < source.point.length; i++) {
                 source.point.getPoint3dAtUncheckedPointIndex(i, targetA);
                 source.point.getPoint3dAtUncheckedPointIndex(i + 1, targetB);
-                s += myOrigin.tripleProductToPoints(facetOrigin, targetA, targetB);
+                sum += myOrigin.tripleProductToPoints(facetOrigin, targetA, targetB);
             }
         }
-        return s / 6.0;
+        return sum / 6.0;
     }
-    /** sum (signed) volumes between facets and a plane.
+    /**
+     * Sum (signed) volumes between facets and a plane.
      * Return a structure with multiple sums:
      * * volume = the sum of (signed) volumes between facets and the plane.
-     * * positiveAreaMomentData, negativeProjectedFacetAreaMoments = moment data with centroid, area, and second moments with respect to the centroid.
-     *
-    */
+     * * positiveProjectedFacetAreaMoments, negativeProjectedFacetAreaMoments = moment data with centroid, area, and second
+     * moments with respect to the centroid.
+     */
     static sumVolumeBetweenFacetsAndPlane(source, plane) {
         if (source instanceof Polyface)
             return PolyfaceQuery.sumVolumeBetweenFacetsAndPlane(source.createVisitor(0), plane);
@@ -218,18 +238,18 @@ export class PolyfaceQuery {
         const singleFacetProducts = Matrix4d.createZero();
         const projectToPlane = plane.getProjectionToPlane();
         source.reset();
-        // For each facet ..
-        //   Form triangles from facet origin to each far edge.
-        //   Sum signed area and volume contributions
-        // each "projectedArea" contribution is twice the area of a triangle.
-        // each volume contribution is  3 times the actual volume -- (1/3) of the altitude sums was the centroid altitude.
+        // For each facet:
+        // - form triangles from facet origin to each far edge.
+        // - sum signed area and volume contributions.
+        // each projected area contribution is twice the area of a triangle.
+        // each volume contribution is 3 times the actual volume -- (1/3) of the altitude sums was the centroid altitude.
         while (source.moveToNextFacet()) {
             source.point.getPoint3dAtUncheckedPointIndex(0, facetOrigin);
             h0 = plane.altitude(facetOrigin);
             singleFacetArea = 0;
             // within a single facets, the singleFacetArea sum is accumulated with signs of individual triangles.
-            // For a non-convex facet, this can be a mixture of positive and negative areas.
-            // The absoluteProjectedAreaSum contribution is forced positive after the sum for the facet.
+            // for a non-convex facet, this can be a mixture of positive and negative areas.
+            // the absoluteProjectedAreaSum contribution is forced positive after the sum for the facet.
             for (let i = 1; i + 1 < source.point.length; i++) {
                 source.point.getPoint3dAtUncheckedPointIndex(i, targetA);
                 source.point.getPoint3dAtUncheckedPointIndex(i + 1, targetB);
@@ -260,7 +280,7 @@ export class PolyfaceQuery {
             negativeProjectedFacetAreaMoments: negativeAreaMoments,
         };
     }
-    /** Return the inertia products [xx,xy,xz,xw, yw, etc] integrated over all all facets, as viewed from origin. */
+    /** Return the inertia products [xx,xy,xz,xw,yw, etc] integrated over all all facets as viewed from origin. */
     static sumFacetSecondAreaMomentProducts(source, origin) {
         if (source instanceof Polyface)
             return PolyfaceQuery.sumFacetSecondAreaMomentProducts(source.createVisitor(0), origin);
@@ -271,7 +291,7 @@ export class PolyfaceQuery {
         }
         return products;
     }
-    /** Return the inertia products [xx,xy,xz,xw, yw, etc] integrated over all tetrahedral volumes from origin */
+    /** Return the inertia products [xx,xy,xz,xw,yw, etc] integrated over all tetrahedral volumes from origin. */
     static sumFacetSecondVolumeMomentProducts(source, origin) {
         if (source instanceof Polyface)
             return PolyfaceQuery.sumFacetSecondVolumeMomentProducts(source.createVisitor(0), origin);
@@ -282,10 +302,11 @@ export class PolyfaceQuery {
         }
         return products;
     }
-    /** Compute area moments for the mesh. In the returned MomentData:
-     * * origin is the centroid.
-     * * localToWorldMap has the origin and principal directions
-     * * radiiOfGyration radii for rotation around the x,y,z axes.
+    /**
+     * Compute area moments for the mesh. In the returned `MomentData`:
+     * * `origin` is the centroid.
+     * * `localToWorldMap` has the origin and principal directions.
+     * * `radiiOfGyration` radii for rotation around the x,y,z axes.
      */
     static computePrincipalAreaMoments(source) {
         const origin = source.data.getPoint(0);
@@ -294,12 +315,13 @@ export class PolyfaceQuery {
         const inertiaProducts = PolyfaceQuery.sumFacetSecondAreaMomentProducts(source, origin);
         return MomentData.inertiaProductsToPrincipalAxes(origin, inertiaProducts);
     }
-    /** Compute area moments for the mesh. In the returned MomentData:
-     * * origin is the centroid.
-     * * localToWorldMap has the origin and principal directions
-     * * radiiOfGyration radii for rotation around the x,y,z axes.
+    /**
+     * Compute area moments for the mesh. In the returned MomentData:
+     * * `origin` is the centroid.
+     * * `localToWorldMap` has the origin and principal directions.
+     * * `radiiOfGyration` radii for rotation around the x,y,z axes.
      * * The result is only valid if the mesh is closed.
-     * * There is no test for closure.  Use `PolyfaceQuery.isPolyfaceClosedByEdgePairing(polyface)` to test for closure.
+     * * There is no test for closure. Use `PolyfaceQuery.isPolyfaceClosedByEdgePairing(polyface)` to test for closure.
      */
     static computePrincipalVolumeMoments(source) {
         const origin = source.data.getPoint(0);
@@ -308,8 +330,10 @@ export class PolyfaceQuery {
         const inertiaProducts = PolyfaceQuery.sumFacetSecondVolumeMomentProducts(source, origin);
         return MomentData.inertiaProductsToPrincipalAxes(origin, inertiaProducts);
     }
-    /** Determine whether all facets are convex.
-     * @param source mesh to examine
+    /**
+     * Determine whether all facets are convex.
+     * @param source polyface or visitor.
+     * @returns `true` if all facets are convex; `false` otherwise.
      */
     static areFacetsConvex(source) {
         if (source instanceof Polyface)
@@ -326,55 +350,67 @@ export class PolyfaceQuery {
     }
     /**
      * Test for convex volume by dihedral angle tests on all edges.
-     * * This tests if all dihedral angles are positive.
-     * * In a closed solid, this is a strong test for overall convexity.
-     * * With `ignoreBoundaries` true, this may be a useful test when all the facets are in a single edge-connected component, such as a pyramid with no underside.
+     * * This tests if all dihedral angles of the mesh are positive.
+     * * In a closed solid, this is a strong test for overall mesh convexity with outward facing normals.
+     * * See [[dihedralAngleSummary]] for the definition of "dihedral angle".
+     * * With `ignoreBoundaries` true, this may be a useful test when all the facets are in a single edge-connected
+     * component, such as a pyramid with no underside.
      * * It is not a correct test if there are multiple, disjoint components.
-     *   * Take the above-mentioned pyramid with no underside.
-     *   * Within the same mesh, have a second pyramid placed to the side, still facing upward.
-     *   * The angles will pass the dihedral convexity test, but the composite thing surely is not convex.
-     * @param source mesh to examine
-     * @param ignoreBoundaries if true, ignore simple boundary edges, i.e. allow unclosed meshes.
-     * @returns true if the mesh is closed and has all dihedral angles (angle across edge) positive
+     * * Take the above-mentioned pyramid with no underside.
+     * * Within the same mesh, have a second pyramid placed to the side, still facing upward.
+     * * The angles will pass the dihedral convexity test, but the composite thing surely is not convex.
+     * @param source mesh.
+     * @param ignoreBoundaries if `true` ignore simple boundary edges, i.e., allow unclosed meshes. Default is `false`.
+     * @returns true if all dihedral angles of the mesh are positive.
      */
     static isConvexByDihedralAngleCount(source, ignoreBoundaries = false) {
         return this.dihedralAngleSummary(source, ignoreBoundaries) > 0;
     }
     /**
     * Compute a number summarizing the dihedral angles in the mesh.
-    * @see [[isConvexByDihedralAngleCount]] for comments about ignoreBoundaries===true when there are multiple connected components.
-    * @param source mesh to examine
-    * @param ignoreBoundaries if true, ignore simple boundary edges, i.e. allow unclosed meshes.
-    * @returns a number summarizing the dihedral angles in the mesh.
-    *   * Return 1 if all angles are positive or planar.  The mesh is probably convex with outward normals.
-    *   * Return -1 if all angles are negative or planar.  The mesh is probably convex with inward normals.
-    *   * Return 0 if
-    *     * angles area mixed
-    *     * any edge has other than 1 incident facet or more than 2 incident facets.
-    *     * (but null edges are permitted -- These occur naturally at edges of quads at north or south pole)
+    * * A dihedral angle is the signed angle between adjacent facets' normals. This angle is positive when the cross
+    * product `normalA x normalB` has the same direction as facetA's traversal of the facets' shared edge.
+    * @param source mesh.
+    * @param ignoreBoundaries if `true` ignore simple boundary edges, i.e., allow unclosed meshes. Default is `false`.
+    * See [[isConvexByDihedralAngleCount]] for comments about passing true when there are multiple
+    * connected components.
+    * * Return `0` if all dihedral angles are zero (and `ignoreBoundaries === true`). The mesh is planar.
+    * * Otherwise, return `1` if all dihedral angles are non-negative. The mesh probably encloses a convex volume and
+    * has outward normals.
+    * * Otherwise, return `-1` if all dihedral angles are non-positive. The mesh probably encloses a convex volume and
+    * has inward normals.
+    * * Otherwise, return `-2`. Also return `-2` if a non-manifold condition was detected, or a facet normal could not
+    * be computed. A non-manifold condition is a positive-length edge adjacent to more than 2 facets or (if
+    * `ignoreBoundaries` is false) adjacent to exactly one facet.
     */
     static dihedralAngleSummary(source, ignoreBoundaries = false) {
+        // more info can be found at geometry/internaldocs/Polyface.md
         const edges = new IndexedEdgeMatcher();
         const visitor = source.createVisitor(1);
         visitor.reset();
+        // find centroid normals of all facets
         const centroidNormal = [];
         let normalCounter = 0;
         while (visitor.moveToNextFacet()) {
             const numEdges = visitor.pointCount - 1;
             const normal = PolygonOps.centroidAreaNormal(visitor.point);
             if (normal === undefined)
-                return 0;
+                return -2;
             centroidNormal.push(normal);
             for (let i = 0; i < numEdges; i++) {
                 edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), normalCounter);
             }
             normalCounter++;
         }
+        // find "manifold clusters" and "bad clusters"
+        // manifold clusters are edges adjacent to 2 facets
+        // bad clusters are edges adjacent to more than 2 facets or (if ignoreBoundaries is false) adjacent to 1 facet
         const badClusters = [];
         const manifoldClusters = [];
         edges.sortAndCollectClusters(manifoldClusters, ignoreBoundaries ? undefined : badClusters, undefined, badClusters);
         if (badClusters.length > 0)
-            return 0;
+            return -2;
+        // find angle between facet centroid normals (dihedral angles)
         let numPositive = 0;
         let numPlanar = 0;
         let numNegative = 0;
@@ -382,8 +418,7 @@ export class PolyfaceQuery {
         for (const cluster of manifoldClusters) {
             const sideA = cluster[0];
             const sideB = cluster[1];
-            if (sideA instanceof SortableEdge
-                && sideB instanceof SortableEdge
+            if (sideA instanceof SortableEdge && sideB instanceof SortableEdge
                 && source.data.point.vectorIndexIndex(sideA.vertexIndexA, sideA.vertexIndexB, edgeVector)) {
                 const dihedralAngle = centroidNormal[sideA.facetIndex].direction.signedAngleTo(centroidNormal[sideB.facetIndex].direction, edgeVector);
                 if (dihedralAngle.isAlmostZero)
@@ -394,26 +429,26 @@ export class PolyfaceQuery {
                     numNegative++;
             }
         }
+        // categorize the mesh
         if (numPositive > 0 && numNegative === 0)
             return 1;
         if (numNegative > 0 && numPositive === 0)
             return -1;
-        // problem case: if all edges have zero dihedral angle, record it as convex.
-        if (numPlanar > 0 && numPositive === 0 && numNegative === 0)
-            return 1;
-        return 0;
+        if (numPlanar > 0 && numPositive === 0 && numNegative === 0) // planar mesh
+            return 0;
+        return -2;
     }
-    /**
-     * Test if the facets in `source` occur in perfectly mated pairs, as is required for a closed manifold volume.
-     */
+    /** Test if the facets in `source` occur in perfectly mated pairs, as is required for a closed manifold volume. */
     static isPolyfaceClosedByEdgePairing(source) {
         return this.isPolyfaceManifold(source, false);
     }
-    /** Test edges pairing in `source` mesh.
-     * * for `allowSimpleBoundaries === false` true return means this is a closed 2-manifold surface
-     * * for `allowSimpleBoundaries === true` true means this is a 2-manifold surface which may have boundary, but is still properly matched internally.
-     * * Any edge with 3 or more incident facets triggers `false` return.
-     * * Any edge with 2 incident facets in the same direction triggers a `false` return.
+    /**
+     * Test edges pairing in `source` mesh.
+     * * For `allowSimpleBoundaries === false` true return means this is a closed 2-manifold surface.
+     * * For `allowSimpleBoundaries === true` true means this is a 2-manifold surface which may have boundary, but is
+     * still properly matched internally.
+     * * Any edge with 3 or more adjacent facets triggers `false` return.
+     * * Any edge with 2 adjacent facets in the same direction triggers a `false` return.
     */
     static isPolyfaceManifold(source, allowSimpleBoundaries = false) {
         const edges = new IndexedEdgeMatcher();
@@ -430,11 +465,11 @@ export class PolyfaceQuery {
         return badClusters.length === 0;
     }
     /**
-     * construct a CurveCollection containing boundary edges.
-     *   * each edge is a LineSegment3d
-     * @param source polyface or visitor
-     * @param includeTypical true to in include typical boundary edges with a single incident facet
-     * @param includeMismatch true to include edges with more than 2 incident facets
+     * Construct a CurveCollection containing boundary edges.
+     * * Each edge is a LineSegment3d.
+     * @param source polyface or visitor.
+     * @param includeTypical true to in include typical boundary edges with a single adjacent facet.
+     * @param includeMismatch true to include edges with more than 2 adjacent facets.
      * @param includeNull true to include edges with identical start and end vertex indices.
      */
     static boundaryEdges(source, includeTypical = true, includeMismatch = true, includeNull = true) {
@@ -450,9 +485,9 @@ export class PolyfaceQuery {
     /**
      * Collect boundary edges.
      * * Return the edges as the simplest collection of chains of line segments.
-     * @param source facets
-     * @param includeTypical true to in include typical boundary edges with a single incident facet
-     * @param includeMismatch true to include edges with more than 2 incident facets
+     * @param source polyface or visitor.
+     * @param includeTypical true to in include typical boundary edges with a single adjacent facet.
+     * @param includeMismatch true to include edges with more than 2 adjacent facets.
      * @param includeNull true to include edges with identical start and end vertex indices.
      */
     static collectBoundaryEdges(source, includeTypical = true, includeMismatch = true, includeNull = true) {
@@ -463,10 +498,11 @@ export class PolyfaceQuery {
     /**
      * Test if the facets in `source` occur in perfectly mated pairs, as is required for a closed manifold volume.
      * If not, extract the boundary edges as lines.
-     * @param source polyface or visitor
-     * @param announceEdge function to be called with each boundary edge. The announcement is start and end points, start and end indices, and facet index.
-     * @param includeTypical true to announce typical boundary edges with a single incident facet
-     * @param includeMismatch true to announce edges with more than 2 incident facets
+     * @param source polyface or visitor.
+     * @param announceEdge function to be called with each boundary edge. The announcement is start and end points,
+     * start and end indices, and facet index.
+     * @param includeTypical true to announce typical boundary edges with a single adjacent facet.
+     * @param includeMismatch true to announce edges with more than 2 adjacent facets.
      * @param includeNull true to announce edges with identical start and end vertex indices.
      */
     static announceBoundaryEdges(source, announceEdge, includeTypical = true, includeMismatch = true, includeNull = true) {
@@ -482,17 +518,17 @@ export class PolyfaceQuery {
                 edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), visitor.currentReadIndex());
             }
         }
-        const bad1 = [];
-        const bad2 = [];
-        const bad0 = [];
-        edges.sortAndCollectClusters(undefined, bad1, bad0, bad2);
+        const boundaryEdges = [];
+        const nullEdges = [];
+        const allOtherEdges = [];
+        edges.sortAndCollectClusters(undefined, boundaryEdges, nullEdges, allOtherEdges);
         const badList = [];
-        if (includeTypical && bad1.length > 0)
-            badList.push(bad1);
-        if (includeMismatch && bad2.length > 0)
-            badList.push(bad2);
-        if (includeNull && bad0.length > 0)
-            badList.push(bad0);
+        if (includeTypical && boundaryEdges.length > 0)
+            badList.push(boundaryEdges);
+        if (includeNull && nullEdges.length > 0)
+            badList.push(nullEdges);
+        if (includeMismatch && allOtherEdges.length > 0)
+            badList.push(allOtherEdges);
         if (badList.length === 0)
             return undefined;
         const sourcePolyface = visitor.clientPolyface();
@@ -509,12 +545,30 @@ export class PolyfaceQuery {
         }
     }
     /**
-     * Invoke the callback on each manifold edge whose adjacent facet normals form vectorToEye dot products with opposite sign.
+     * Load all half edges from a mesh to an IndexedEdgeMatcher.
+     * @param polyface a mesh or a visitor assumed to have numWrap === 1.
+    */
+    static createIndexedEdges(polyface) {
+        if (polyface instanceof Polyface)
+            return this.createIndexedEdges(polyface.createVisitor(1));
+        const edges = new IndexedEdgeMatcher();
+        polyface.reset();
+        while (polyface.moveToNextFacet()) {
+            const numEdges = polyface.pointCount - 1;
+            for (let i = 0; i < numEdges; i++) {
+                edges.addEdge(polyface.clientPointIndex(i), polyface.clientPointIndex(i + 1), polyface.currentReadIndex());
+            }
+        }
+        return edges;
+    }
+    /**
+     * Invoke the callback on each manifold edge whose adjacent facet normals form vectorToEye dot products
+     * with opposite sign.
      * * The callback is not called on boundary edges.
-     * @param source facets
-     * @param announce callback function invoked on manifold silhouette edges
-     * @param vectorToEye normal of plane in which to compute silhouette edges
-     * @param sideAngle angular tolerance for perpendicularity test
+     * @param source polyface or visitor.
+     * @param announce callback function invoked on manifold silhouette edges.
+     * @param vectorToEye normal of plane in which to compute silhouette edges.
+     * @param sideAngle angular tolerance for perpendicularity test.
      */
     static announceSilhouetteEdges(source, announce, vectorToEye, sideAngle = Angle.createSmallAngle()) {
         if (source instanceof Polyface)
@@ -564,16 +618,17 @@ export class PolyfaceQuery {
      * Collect manifold edges whose adjacent facet normals form vectorToEye dot products with opposite sign.
      * * Does not return boundary edges.
      * * Return the edges as chains of line segments.
-     * @param source facets
-     * @param vectorToEye normal of plane in which to compute silhouette edges
-     * @param sideAngle angular tolerance for perpendicularity test
+     * @param source polyface or visitor.
+     * @param vectorToEye normal of plane in which to compute silhouette edges.
+     * @param sideAngle angular tolerance for perpendicularity test.
      */
     static collectSilhouetteEdges(source, vectorToEye, sideAngle = Angle.createSmallAngle()) {
         const collector = new MultiChainCollector(Geometry.smallMetricDistance, Geometry.smallMetricDistance);
         PolyfaceQuery.announceSilhouetteEdges(source, (ptA, ptB) => collector.captureCurve(LineSegment3d.create(ptA, ptB)), vectorToEye, sideAngle);
         return collector.grabResult(true);
     }
-    /** Find segments (within the linestring) which project to facets.
+    /**
+     * Find segments (within the linestring) which project to facets.
      * * Announce each pair of linestring segment and on-facet segment through a callback.
      * * Facets are ASSUMED to be convex and planar, and not overlap in the z direction.
      */
@@ -586,7 +641,24 @@ export class PolyfaceQuery {
             }
         }
     }
-    /** Execute context.projectToPolygon until its work estimates accumulate to workLimit  */
+    /**
+     * Set the limit on work during an async time blocks, and return the old value.
+     * * This should be a large number -- default is 1.0e6
+     * @internal
+     */
+    static setAsyncWorkLimit(value) {
+        const oldValue = this._asyncWorkLimit;
+        this._asyncWorkLimit = value;
+        return oldValue;
+    }
+    /**
+     * Query the current limit on work during an async time block.
+     * @internal
+     */
+    static get asyncWorkLimit() {
+        return this._asyncWorkLimit;
+    }
+    /** Execute `context.projectToPolygon` until its work estimates accumulate to workLimit.  */
     static async continueAnnounceSweepLinestringToConvexPolyfaceXY(context, visitor, announce) {
         let workCount = 0;
         while ((workCount < this.asyncWorkLimit) && visitor.moveToNextFacet()) {
@@ -594,16 +666,8 @@ export class PolyfaceQuery {
         }
         return workCount;
     }
-    /** Set the limit on work during an async time blocks, and return the old value.
-     * * This should be a large number -- default is 1.0e6
-     * @internal
-     */
-    static setAsyncWorkLimit(value) { const a = this._asyncWorkLimit; this._asyncWorkLimit = value; return a; }
-    /** Query the current limit on work during an async time block.
-     * @internal
-     */
-    static get asyncWorkLimit() { return this._asyncWorkLimit; }
-    /** Find segments (within the linestring) which project to facets.
+    /**
+     * Find segments (within the linestring) which project to facets.
      * * Announce each pair of linestring segment and on-facet segment through a callback.
      * * Facets are ASSUMED to be convex and planar, and not overlap in the z direction.
      * * REMARK: Although this is public, the usual use is via slightly higher level public methods, viz:
@@ -626,14 +690,15 @@ export class PolyfaceQuery {
         // GeometryCoreTestIO.consoleLog({ myWorkTotal: workTotal, myBlockCount: this.awaitBlockCount });
         return workTotal;
     }
-    /** Search the facets for facet subsets that are connected with at least vertex contact.
+    /**
+     * Search the facets for facet subsets that are connected with at least vertex contact.
      * * Return array of arrays of facet indices.
      */
     static partitionFacetIndicesByVertexConnectedComponent(polyface) {
         if (polyface instanceof Polyface) {
             return this.partitionFacetIndicesByVertexConnectedComponent(polyface.createVisitor(0));
         }
-        // The polyface is really a visitor !!!
+        // The polyface is really a visitor
         const context = new UnionFindContext(this.visitorClientPointCount(polyface));
         for (polyface.reset(); polyface.moveToNextFacet();) {
             const firstVertexIndexOnThisFacet = polyface.pointIndex[0];
@@ -661,9 +726,9 @@ export class PolyfaceQuery {
     /**
      * * Examine the normal orientation for each faces.
      * * Separate to 3 partitions:
-     *    * facets with normal in the positive direction of the vectorToEye (partition 0)
-     *    * facets with normal in the negative direction of the vectorToEye (partition 1)
-     *    * facets nearly perpendicular to the view vector  (partition 2)
+     *    * Facets with normal in the positive direction of the vectorToEye (partition 0).
+     *    * Facets with normal in the negative direction of the vectorToEye (partition 1).
+     *    * Facets nearly perpendicular to the view vector  (partition 2).
      * * Return array of arrays of facet indices.
      */
     static partitionFacetIndicesByVisibilityVector(polyface, vectorToEye, sideAngleTolerance) {
@@ -698,13 +763,13 @@ export class PolyfaceQuery {
     }
     /**
      * Return the boundary of facets that are facing the eye.
-     * @param polyface
+     * @param polyface the indexed polyface
      * @param visibilitySubset selector among the visible facet sets extracted by partitionFacetIndicesByVisibilityVector
      *   * 0 ==> forward facing
      *   * 1 ==> rear facing
      *   * 2 ==> side facing
-     * @param vectorToEye
-     * @param sideAngleTolerance
+     * @param vectorToEye the vector to eye
+     * @param sideAngleTolerance the tolerance of side angle
      */
     static boundaryOfVisibleSubset(polyface, visibilitySelect, vectorToEye, sideAngleTolerance = Angle.createDegrees(1.0e-3)) {
         const partitionedIndices = this.partitionFacetIndicesByVisibilityVector(polyface, vectorToEye, sideAngleTolerance);
@@ -714,10 +779,9 @@ export class PolyfaceQuery {
         return this.boundaryEdges(visitor, true, false, false);
     }
     /**
-     * Search for edges with only 1 incident facet.
-     * * chain them into loops
-     * * emit the loops to the announceLoop function
-     * @param mesh
+     * Search for edges with only 1 adjacent facet.
+     * * Chain them into loops.
+     * * Emit the loops to the announceLoop function.
      */
     static announceBoundaryChainsAsLineString3d(mesh, announceLoop) {
         const collector = new MultiChainCollector(Geometry.smallMetricDistance, 1000);
@@ -728,9 +792,9 @@ export class PolyfaceQuery {
      * Return a mesh with
      *  * clusters of adjacent, coplanar facets merged into larger facets.
      *  * other facets included unchanged.
-     * @param mesh existing mesh or visitor
-     * @param maxSmoothEdgeAngle maximum dihedral angle across an edge between facets deemed coplanar. If undefined, uses `Geometry.smallAngleRadians`.
-     * @returns
+     * @param mesh existing mesh or visitor.
+     * @param maxSmoothEdgeAngle maximum dihedral angle across an edge between facets deemed coplanar. If undefined,
+     * uses `Geometry.smallAngleRadians`.
      */
     static cloneWithMaximalPlanarFacets(mesh, maxSmoothEdgeAngle) {
         if (mesh instanceof Polyface)
@@ -789,14 +853,14 @@ export class PolyfaceQuery {
      *  * Unclosed chains are rejected.
      *  * Closed chains are triangulated and returned as a mesh.
      *  * The options structure enforces restrictions on how complicated the hole filling can be:
-     *     * maxEdgesAroundHole -- holes with more edges are skipped
+     *     * maxEdgesAroundHole -- holes with more edges are skipped.
      *     * maxPerimeter -- holes with larger summed edge lengths are skipped.
      *     * upVector -- holes that do not have positive area along this view are skipped.
-     *     * includeOriginalMesh -- includes the original mesh in the output mesh, so the composite mesh is a clone with holes filled
-     * @param mesh existing mesh
+     *     * includeOriginalMesh -- includes the original mesh in the output mesh, so the composite mesh is a
+     * clone with holes filled.
+     * @param mesh existing mesh.
      * @param options options controlling the hole fill.
      * @param unfilledChains optional array to receive the points around holes that were not filled.
-     * @returns
      */
     static fillSimpleHoles(mesh, options, unfilledChains) {
         if (mesh instanceof Polyface)
@@ -832,9 +896,7 @@ export class PolyfaceQuery {
         }
         return builder.claimPolyface(true);
     }
-    /** Clone the facets in each partition to a separate polyface.
-   *
-   */
+    /** Clone the facets in each partition to a separate polyface. */
     static clonePartitions(polyface, partitions) {
         if (polyface instanceof Polyface) {
             return this.clonePartitions(polyface.createVisitor(0), partitions);
@@ -857,7 +919,7 @@ export class PolyfaceQuery {
         }
         return polyfaces;
     }
-    /** Clone facets that pass a filter function */
+    /** Clone facets that pass a filter function. */
     static cloneFiltered(source, filter) {
         if (source instanceof Polyface) {
             return this.cloneFiltered(source.createVisitor(0), filter);
@@ -927,46 +989,44 @@ export class PolyfaceQuery {
         }
         return builder.claimPolyface(true);
     }
-    /** If the visitor's client is a polyface, simply return its point array length.
-     * If not a polyface, visit all facets to find the largest index.
-     */
-    static visitorClientPointCount(visitor) {
-        if (visitor instanceof Polyface)
-            return visitor.data.point.length;
-        const polyface = visitor.clientPolyface();
+    /** Return the point count of the `source`. */
+    static visitorClientPointCount(source) {
+        if (source instanceof Polyface)
+            return source.data.point.length;
+        const polyface = source.clientPolyface();
         if (polyface !== undefined)
             return polyface.data.point.length;
-        visitor.reset();
+        source.reset();
         let maxIndex = -1;
-        while (visitor.moveToNextFacet()) {
-            for (const pointIndex of visitor.pointIndex)
+        while (source.moveToNextFacet()) {
+            for (const pointIndex of source.pointIndex)
                 if (pointIndex > maxIndex)
                     maxIndex = pointIndex;
         }
         return maxIndex + 1;
     }
-    /** If the visitor's client is a polyface, simply return its facet count.
-     * If not a polyface, visit all facets to accumulate a count.
-     */
-    static visitorClientFacetCount(visitor) {
-        if (visitor instanceof Polyface) {
-            if (visitor.facetCount !== undefined)
-                return visitor.facetCount;
-            visitor = visitor.createVisitor(0);
+    /** Return the facet count of the `source`. */
+    static visitorClientFacetCount(source) {
+        if (source instanceof Polyface) {
+            if (source.facetCount !== undefined)
+                return source.facetCount;
+            source = source.createVisitor(0);
         }
-        const polyface = visitor.clientPolyface();
+        const polyface = source.clientPolyface();
         if (polyface !== undefined && polyface.facetCount !== undefined)
             return polyface.facetCount;
         let facetCount = 0;
-        visitor.reset();
-        while (visitor.moveToNextFacet())
+        source.reset();
+        while (source.moveToNextFacet())
             ++facetCount;
         return facetCount;
     }
-    /** Partition the facet set into connected components such that two adjacent facets are in the same component if and only if they are adjacent across a clustered edge.
+    /**
+     * Partition the facet set into connected components such that two adjacent facets are in the same component if and
+     * only if they are adjacent across a clustered edge.
      * @param edgeClusters sorted and clustered edges (cf. `IndexedEdgeMatcher.sortAndCollectClusters`).
      * @param numFacets facet count in the parent mesh. In particular, `edge.facetIndex < numFacets` for every input edge.
-     * @return collection of facet index arrays, one array per connected component
+     * @return collection of facet index arrays, one array per connected component.
      */
     static partitionFacetIndicesBySortableEdgeClusters(edgeClusters, numFacets) {
         const context = new UnionFindContext(numFacets);
@@ -997,10 +1057,12 @@ export class PolyfaceQuery {
         }
         return facetsInComponent;
     }
-    /** Partition the facet set into connected components. Each facet in a given component shares an edge only with other facets in the component (or is a boundary edge).
-     * @param polyface facets to partition
-     * @param stopAtVisibleEdges whether to further split connected components by visible edges of the polyface
-     * @return collection of facet index arrays, one per connected component
+    /**
+     * Partition the facet set into connected components. Each facet in a given component shares an edge only with
+     * other facets in the component (or is a boundary edge).
+     * @param polyface facets to partition.
+     * @param stopAtVisibleEdges whether to further split connected components by visible edges of the polyface.
+     * @return collection of facet index arrays, one per connected component.
      */
     static partitionFacetIndicesByEdgeConnectedComponent(polyface, stopAtVisibleEdges = false) {
         if (polyface instanceof Polyface) {
@@ -1025,7 +1087,8 @@ export class PolyfaceQuery {
         matcher.sortAndCollectClusters(allEdges, allEdges, allEdges, allEdges);
         return this.partitionFacetIndicesBySortableEdgeClusters(allEdges, numFacets);
     }
-    /** Find segments (within the line string) which project to facets.
+    /**
+     * Find segments (within the line string) which project to facets.
      * * Assemble each input segment paired with its projected segment/point as a quad/triangle facet in a new polyface.
      * * Input facets are ASSUMED to be convex and planar, and not overlap in the z direction.
      */
@@ -1039,7 +1102,7 @@ export class PolyfaceQuery {
         });
         return builder.claimPolyface(true);
     }
-    /** @deprecated in 4.x. Use sweepLineStringToFacetsXYReturnSweptFacets instead. */
+    /** @deprecated in 4.x. Use [[sweepLineStringToFacetsXYReturnSweptFacets]] instead. */
     static sweepLinestringToFacetsXYreturnSweptFacets(linestringPoints, polyface) {
         return this.sweepLineStringToFacetsXYReturnSweptFacets(linestringPoints, polyface);
     }
@@ -1052,11 +1115,10 @@ export class PolyfaceQuery {
      */
     static sweepLineStringToFacets(linestringPoints, polyfaceOrVisitor, options) {
         let result = [];
-        // setup default options:
+        // setup default options
         if (options === undefined)
             options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createRadians(Geometry.smallAngleRadians), // tight geometry tolerance for vertical side facets
-            true, // assemble chains
-            true, true, true); // accept all outputs
+            true, true, true, true);
         let chainContext;
         if (options.assembleChains)
             chainContext = ChainMergeContext.create();
@@ -1087,9 +1149,9 @@ export class PolyfaceQuery {
     }
     /**
      * Sweep the line string in the z-direction to intersections with a mesh, using a search object for speedup.
-     * @param lineStringPoints input line string to drape on the mesh
-     * @param polyfaceOrVisitor mesh, or mesh visitor to traverse only part of a mesh
-     * @param searchByReadIndex object for searching facet 2D ranges tagged by mesh read index
+     * @param lineStringPoints input line string to drape on the mesh.
+     * @param polyfaceOrVisitor mesh, or mesh visitor to traverse only part of a mesh.
+     * @param searchByReadIndex object for searching facet 2D ranges tagged by mesh read index.
      * @example Using a 5x5 indexed search grid:
      * ```
      * const xyRange = Range2d.createFrom(myPolyface.range());
@@ -1099,7 +1161,7 @@ export class PolyfaceQuery {
      * }
      * const drapedLineStrings = PolyfaceQuery.sweepLineStringToFacetsXY(lineString, myPolyface, searcher);
      * ```
-     * @returns collected line strings
+     * @returns the collected line strings.
      */
     static sweepLineStringToFacetsXY(lineStringPoints, polyfaceOrVisitor, searchByReadIndex) {
         const chainContext = ChainMergeContext.create();
@@ -1133,32 +1195,36 @@ export class PolyfaceQuery {
         chainContext.clusterAndMergeVerticesXYZ();
         return chainContext.collectMaximalChains();
     }
-    /** Find segments (within the linestring) which project to facets.
+    /**
+     * Find segments (within the linestring) which project to facets.
       * * Return collected line segments.
       * * This calls [[sweepLineStringToFacets]] with options created by
-      *   `const options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createSmallAngle(),false, true, true, true);`
-      * @deprecated in 4.x. Use [[sweepLineStringToFacets]] to get further options.
+      *   `const options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createSmallAngle(), false, true, true, true);`
+      * @deprecated in 4.x. Use [[PolyfaceQuery.sweepLineStringToFacets]] to get further options.
       */
     static sweepLinestringToFacetsXYReturnLines(linestringPoints, polyface) {
         const options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createSmallAngle(), false, true, true, true);
         const result = PolyfaceQuery.sweepLineStringToFacets(linestringPoints, polyface, options);
         return result;
     }
-    /** Find segments (within the linestring) which project to facets.
+    /**
+     * Find segments (within the linestring) which project to facets.
      * * Return chains.
      * * This calls [[sweepLineStringToFacets]] with options created by
      *   `const options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createSmallAngle(),true, true, true, true);`
-     * @deprecated in 4.x. Use [[sweepLineStringToFacets]] to get further options.
+     * @deprecated in 4.x. Use [[PolyfaceQuery.sweepLineStringToFacets]] to get further options.
      */
     static sweepLinestringToFacetsXYReturnChains(linestringPoints, polyface) {
         const options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createSmallAngle(), true, true, true, true);
         const result = PolyfaceQuery.sweepLineStringToFacets(linestringPoints, polyface, options);
         return result;
     }
-    /** Find segments (within the linestring) which project to facets.
+    /**
+     * Find segments (within the linestring) which project to facets.
      * * This is done as a sequence of "await" steps.
-     * * Each "await" step deals with approximately PolyfaceQuery.asyncWorkLimit pairings of (linestring edge) with (facet edge)
-     * * PolyfaceQuery.setAsyncWorkLimit() to change work blocks from default
+     * * Each "await" step deals with approximately PolyfaceQuery.asyncWorkLimit pairings of "linestring edge"
+     * with "facet edge".
+     * * PolyfaceQuery.setAsyncWorkLimit() to change work blocks from default.
      * * Return chains.
      * * Facets are ASSUMED to be convex and planar, and not overlap in the z direction.
      */
@@ -1172,7 +1238,7 @@ export class PolyfaceQuery {
         return chains;
     }
     /**
-     * * Examine ranges of facets.
+     * Examine ranges of facets.
      * * Return statistical summary of x,y,z ranges.
      */
     static collectRangeLengthData(polyface) {
@@ -1180,17 +1246,18 @@ export class PolyfaceQuery {
             return this.collectRangeLengthData(polyface.createVisitor(0));
         }
         const rangeData = new RangeLengthData();
-        // polyface is a visitor ...
+        // polyface is a visitor
         for (polyface.reset(); polyface.moveToNextFacet();)
             rangeData.accumulateGrowableXYZArrayRange(polyface.point);
         return rangeData;
     }
-    /** Clone the facets, inserting vertices (within edges) where points not part of each facet's vertex indices impinge within edges.
-     *
+    /**
+     * Clone the facets, inserting vertices (within edges) where points not part of each facet's vertex indices
+     * impinge within edges.
      */
     static cloneWithTVertexFixup(polyface) {
-        const oldFacetVisitor = polyface.createVisitor(1); // This is to visit the existing facets.
-        const newFacetVisitor = polyface.createVisitor(0); // This is to build the new facets.
+        const oldFacetVisitor = polyface.createVisitor(1); // this is to visit the existing facets
+        const newFacetVisitor = polyface.createVisitor(0); // this is to build the new facets
         const rangeSearcher = XYPointBuckets.create(polyface.data.point, 30);
         const builder = PolyfaceBuilder.create();
         const edgeRange = Range3d.createNull();
@@ -1201,7 +1268,7 @@ export class PolyfaceQuery {
         for (oldFacetVisitor.reset(); oldFacetVisitor.moveToNextFacet();) {
             newFacetVisitor.clearArrays();
             for (let i = 0; i + 1 < oldFacetVisitor.point.length; i++) {
-                // each base vertex is part of the result ...
+                // each base vertex is part of the result
                 oldFacetVisitor.point.getPoint3dAtUncheckedPointIndex(i, point0);
                 oldFacetVisitor.point.getPoint3dAtUncheckedPointIndex(i + 1, point1);
                 newFacetVisitor.pushDataFrom(oldFacetVisitor, i);
@@ -1212,12 +1279,12 @@ export class PolyfaceQuery {
                 edgeRange.extend(point1);
                 edgeRange.ensureMinLengths(Geometry.smallMetricDistance); // add some slop in case segment is axis-aligned
                 rangeSearcher.announcePointsInRange(edgeRange, (index, _x, _y, _z) => {
-                    // x,y,z has x,y within the range of the search ... test for exact on (in full 3d!)
+                    // x,y,z has x,y within the range of the search; test for exact on (in full 3d)
                     polyface.data.point.getPoint3dAtUncheckedPointIndex(index, spacePoint);
                     const detail = segment.closestPoint(spacePoint, false);
                     if (undefined !== detail) {
-                        if (detail.fraction > 0.0 && detail.fraction < 1.0 && !detail.point.isAlmostEqual(point0) && !detail.point.isAlmostEqual(point1)
-                            && spacePoint.isAlmostEqual(detail.point)) {
+                        if (detail.fraction > 0.0 && detail.fraction < 1.0 && !detail.point.isAlmostEqual(point0) &&
+                            !detail.point.isAlmostEqual(point1) && spacePoint.isAlmostEqual(detail.point)) {
                             if (detailArray === undefined)
                                 detailArray = [];
                             detail.a = index;
@@ -1238,14 +1305,13 @@ export class PolyfaceQuery {
         return builder.claimPolyface();
     }
     /**
+     * Compare index arrays formatted as follows. Return 0 if arrays are the same.
      * * Each array input structure is: [facetIndex, vertexIndex0, vertexIndex1, ....]
-     * * Vertex indices assumed reversed so it
-     *   * vertexIndex0 is the lowest index on the facet
-     *   * vertexIndex1 is the lowest neighbor of vertex0
+     * * Vertex indices assumed reversed so:
+     *   * vertexIndex0 is the lowest index on the facet.
+     *   * vertexIndex1 is the lowest neighbor of vertex0.
      *   * first different entry among vertex indices determines lexical result.
-     *   * Hence facets with duplicate indices (whether forward or reversed) are considered equal.
-     * @param arrayA
-     * @param arrayB
+     *   * hence facets with duplicate indices (whether forward or reversed) are considered equal.
      */
     static compareFacetIndexAndVertexIndices(arrayA, arrayB) {
         if (arrayA.length !== arrayB.length)
@@ -1258,9 +1324,11 @@ export class PolyfaceQuery {
         return 0;
     }
     /**
-     * * Return an array of arrays describing facet duplication.
+     * Collect facet duplicates.
+     * @param polyface the polyface.
      * @param includeSingletons if true, non-duplicated facets are included in the output.
-     * * Each array `entry` in the output contains read indices of a cluster of facets with the same vertex indices.
+     * @returns an array of arrays describing facet duplication. Each array `entry` in the output contains read
+     * indices of a cluster of facets with the same vertex indices.
      */
     static collectDuplicateFacetIndices(polyface, includeSingletons = false) {
         const result = [];
@@ -1271,12 +1339,12 @@ export class PolyfaceQuery {
         return result;
     }
     /**
-     * * Return an array of arrays describing facet duplication.
-     * @param includeSingletons if true, non-duplicated facets are included in the output.
-     * * Each array `entry` in the output contains read indices of a cluster of facets with the same vertex indices.
+     * Announce facet duplicates.
+     * @returns an array of arrays describing facet duplication. Each array `entry` in the output contains read
+     * indices of a cluster of facets with the same vertex indices.
      */
     static announceDuplicateFacetIndices(polyface, announceCluster) {
-        const visitor = polyface.createVisitor(0); // This is to visit the existing facets.
+        const visitor = polyface.createVisitor(0); // this is to visit the existing facets
         const facetIndexAndVertexIndices = [];
         for (visitor.reset(); visitor.moveToNextFacet();) {
             const facetIndex = visitor.currentReadIndex();
@@ -1284,12 +1352,12 @@ export class PolyfaceQuery {
             const pointIndex = visitor.pointIndex;
             const numPointsThisFacet = pointIndex.length;
             let lowIndex = 0;
-            // find the lowest point index ...
+            // find the lowest point index
             for (let i = 1; i < visitor.pointIndex.length; i++) {
                 if (pointIndex[i] < pointIndex[lowIndex])
                     lowIndex = i;
             }
-            // find its lowest neighbor -- assemble sort array in that direction
+            // find its lowest neighbor; assemble sort array in that direction
             if (pointIndex[(lowIndex + 1) % numPointsThisFacet] < pointIndex[(lowIndex + numPointsThisFacet - 1) % numPointsThisFacet]) {
                 for (let i = 0; i < numPointsThisFacet; i++) {
                     entry.push(pointIndex[(lowIndex + i) % numPointsThisFacet]);
@@ -1317,9 +1385,11 @@ export class PolyfaceQuery {
             announceCluster(clusterArray);
         }
     }
-    /** Return a new facet set with a subset of facets in source
+    /**
+     * Return a new facet set with a subset of facets in polyface.
+     * @param source the polyface.
      * @param includeSingletons true to copy facets that only appear once
-     * @param clusterSelector indicates whether duplicate clusters are to have 0, 1, or all facets included
+     * @param clusterSelector indicates whether duplicate clusters are to have 0, 1, or all facets included.
      */
     static cloneByFacetDuplication(source, includeSingletons, clusterSelector) {
         const builder = PolyfaceBuilder.create();
@@ -1345,25 +1415,23 @@ export class PolyfaceQuery {
         });
         return builder.claimPolyface();
     }
-    /** Clone the facets, inserting removing points that are simply within colinear edges.
-     *
-     */
+    /** Clone the facets, removing points that are simply within colinear edges. */
     static cloneWithColinearEdgeFixup(polyface) {
-        const oldFacetVisitor = polyface.createVisitor(2); // This is to visit the existing facets.
-        const newFacetVisitor = polyface.createVisitor(0); // This is to build the new facets.
+        const oldFacetVisitor = polyface.createVisitor(2); // this is to visit the existing facets
+        const newFacetVisitor = polyface.createVisitor(0); // this is to build the new facets
         const builder = PolyfaceBuilder.create();
         const vector01 = Vector3d.create();
         const vector12 = Vector3d.create();
         const numPoint = polyface.data.point.length;
         const pointState = new Int32Array(numPoint);
-        // FIRST PASS -- in each sector of each facet, determine if the sector has colinear incoming and outgoing vectors.
-        //   Mark each point as
-        //  0 unvisited
-        // -1 incident to a non-colinear sector
-        //  n incident to n colinear sectors
+        // FIRST PASS: in each sector of each facet, determine if the sector has colinear incoming and outgoing vectors.
+        // Mark each point as
+        //    0 unvisited
+        //   -1 adjacent to a non-colinear sector
+        //    n adjacent to n colinear sectors
         for (oldFacetVisitor.reset(); oldFacetVisitor.moveToNextFacet();) {
             for (let i = 0; i + 2 < oldFacetVisitor.point.length; i++) {
-                // each base vertex is part of the result ...
+                // each base vertex is part of the result
                 oldFacetVisitor.point.vectorIndexIndex(i, i + 1, vector01);
                 oldFacetVisitor.point.vectorIndexIndex(i + 1, i + 2, vector12);
                 const pointIndex = oldFacetVisitor.clientPointIndex(i + 1);
@@ -1378,7 +1446,7 @@ export class PolyfaceQuery {
                 }
             }
         }
-        // SECOND PASS -- make copies, omitting references to points at colinear sectors
+        // SECOND PASS: make copies, omitting references to points at colinear sectors.
         for (oldFacetVisitor.reset(); oldFacetVisitor.moveToNextFacet();) {
             newFacetVisitor.clearArrays();
             for (let i = 0; i + 2 < oldFacetVisitor.point.length; i++) {
@@ -1394,9 +1462,9 @@ export class PolyfaceQuery {
     }
     /**
      * Set the edge visibility for specified edges in the polyface.
-     * @param polyface mesh to be edited
-     * @param clusters array of edge references
-     * @param value visibility value (true or false)
+     * @param polyface mesh to be edited.
+     * @param clusters array of edge references.
+     * @param value visibility value (true or false).
      */
     static setEdgeVisibility(polyface, clusters, value) {
         for (const cluster of clusters) {
@@ -1411,9 +1479,9 @@ export class PolyfaceQuery {
     }
     /**
      * Set the visibility of a particular edge of a particular facet.
-     * @param polyface containing polyface
-     * @param facetIndex facet index
-     * @param vertexIndex vertex index (in vertex array) at which the edge starts
+     * @param polyface containing polyface.
+     * @param facetIndex facet index.
+     * @param vertexIndex vertex index (in vertex array) at which the edge starts.
      * @param value visibility value.
      */
     static setSingleEdgeVisibility(polyface, facetIndex, vertexIndex, value) {
@@ -1426,9 +1494,9 @@ export class PolyfaceQuery {
     }
     /**
      * Get the visibility of a particular edge of a particular facet.
-     * @param polyface containing polyface
-     * @param facetIndex facet index
-     * @param vertexIndex vertex index (in vertex array) at which the edge starts
+     * @param polyface containing polyface.
+     * @param facetIndex facet index.
+     * @param vertexIndex vertex index (in vertex array) at which the edge starts.
      */
     static getSingleEdgeVisibility(polyface, facetIndex, vertexIndex) {
         const data = polyface.data;
@@ -1439,29 +1507,13 @@ export class PolyfaceQuery {
                 return data.edgeVisible[i]; // return visibility of first edge in the face that starts at this vertex
         return undefined;
     }
-    /** Load all half edges from a mesh to an IndexedEdgeMatcher.
-     * @param polyface a mesh, or a visitor assumed to have numWrap === 1
-    */
-    static createIndexedEdges(polyface) {
-        if (polyface instanceof Polyface)
-            return this.createIndexedEdges(polyface.createVisitor(1));
-        const edges = new IndexedEdgeMatcher();
-        polyface.reset();
-        while (polyface.moveToNextFacet()) {
-            const numEdges = polyface.pointCount - 1;
-            for (let i = 0; i < numEdges; i++) {
-                edges.addEdge(polyface.clientPointIndex(i), polyface.clientPointIndex(i + 1), polyface.currentReadIndex());
-            }
-        }
-        return edges;
-    }
     /**
      * Return manifold edge pairs whose dihedral angle is bounded by the given angle.
      * * The dihedral angle of a manifold edge is measured between the normals of its two adjacent faces.
      * * Boundary edges are not returned as they are not manifold.
-     * @param mesh existing polyface or visitor
-     * @param maxSmoothEdgeAngle maximum dihedral angle of a smooth edge. If undefined, uses `Geometry.smallAngleRadians`.
-     * @param sharpEdges true to reverse the angle threshold test and return sharp edges; otherwise return smooth edges (default)
+     * @param mesh existing polyface or visitor.
+     * @param maxSmoothEdgeAngle maximum dihedral angle of a smooth edge. If `undefined`, uses `Geometry.smallAngleRadians`.
+     * @param sharpEdges true to reverse the angle threshold test and return sharp edges; otherwise return smooth edges (default).
      */
     static collectEdgesByDihedralAngle(mesh, maxSmoothEdgeAngle, sharpEdges = false) {
         if (mesh instanceof Polyface)
@@ -1496,13 +1548,13 @@ export class PolyfaceQuery {
         return outEdges;
     }
     /**
+     * Make paired edges invisible.
     * * Find mated pairs among facet edges.
     * * Mated pairs have the same vertex indices appearing in opposite order.
     * * Mark all non-mated pairs visible.
     * * At mated pairs
     *    * if angle across the edge is larger than `sharpEdgeAngle`, mark visible
     *    * otherwise mark invisible.
-    * @param mesh mesh to be marked
     */
     static markPairedEdgesInvisible(mesh, sharpEdgeAngle) {
         const visitor = mesh.createVisitor(1);
@@ -1531,7 +1583,8 @@ export class PolyfaceQuery {
             }
         }
     }
-    /** Try to compute a unit normal for a facet accessible through a visitor.
+    /**
+     * Try to compute a unit normal for a facet accessible through a visitor.
      * * Unit normal is computed by `PolygonOps.unitNormal` with the points around the facet.
      */
     static computeFacetUnitNormal(visitor, facetIndex, result) {
@@ -1544,18 +1597,18 @@ export class PolyfaceQuery {
         return undefined;
     }
     /**
-    * * Mark all edge visibilities in the IndexedPolyface
-    * @param mesh mesh to be marked
-    * @param value true for visible, false for hidden
-    */
+     * * Mark all edge visibilities in the IndexedPolyface.
+     * @param mesh mesh to be marked.
+     * @param value true for visible, false for hidden.
+     */
     static markAllEdgeVisibility(mesh, value) {
         const data = mesh.data;
         for (let i = 0; i < data.edgeVisible.length; i++)
             data.edgeVisible[i] = value;
     }
     /**
-     * Create a HalfEdgeGraph with a face for each facet of the IndexedPolyface
-     * @param mesh mesh to convert
+     * Create a HalfEdgeGraph with a face for each facet of the IndexedPolyface.
+     * @param mesh mesh to convert.
      * @internal
      */
     static convertToHalfEdgeGraph(mesh) {
@@ -1574,28 +1627,22 @@ export class PolyfaceQuery {
         });
         return graph;
     }
-    /**
-     * * Examine adjacent facet orientations throughout the mesh
-     * * If possible, reverse a subset to achieve proper pairing.
-     * @param mesh
-     */
+    /** Examine adjacent facet orientations throughout the mesh. If possible, reverse a subset to achieve proper pairing. */
     static reorientVertexOrderAroundFacetsForConsistentOrientation(mesh) {
         return FacetOrientationFixup.doFixup(mesh);
     }
-    /**
-     * Set up indexed normals with one normal in the plane of each facet of the mesh.
-     * @param polyface
-     */
+    /** Set up indexed normals with one normal in the plane of each facet of the mesh. */
     static buildPerFaceNormals(polyface) {
         BuildAverageNormalsContext.buildPerFaceNormals(polyface);
     }
     /**
-    * * At each vertex of the mesh
-    *   * Find clusters of almost parallel normals
-    *   * Compute simple average of those normals
-    *   * Index to the averages
+    * * At each vertex of the mesh:
+    *   * Find clusters of almost parallel normals.
+    *   * Compute simple average of those normals.
+    *   * Index to the averages.
     * * For typical meshes, this correctly clusters adjacent normals.
-    * * One can imagine a vertex with multiple "smooth cone-like" sets of incident facets such that averaging occurs among two nonadjacent cones.  But this does not seem to be a problem in practice.
+    * * One can imagine a vertex with multiple "smooth cone-like" sets of adjacent facets such that averaging occurs
+    * among two nonadjacent cones. But this does not seem to be a problem in practice.
     * @param polyface polyface to update.
     * @param toleranceAngle averaging is done between normals up to this angle.
     */
@@ -1604,9 +1651,9 @@ export class PolyfaceQuery {
     }
     /**
      * Offset the faces of the mesh.
-     * @param source original mesh
+     * @param source original mesh.
      * @param signedOffsetDistance distance to offset
-     * @param offsetOptions angle options.  The default options are recommended.
+     * @param offsetOptions angle options. The default options are recommended.
      * @returns shifted mesh.
      */
     static cloneOffset(source, signedOffsetDistance, offsetOptions = OffsetMeshOptions.create()) {
@@ -1615,16 +1662,22 @@ export class PolyfaceQuery {
         OffsetMeshContext.buildOffsetMeshWithEdgeChamfers(source, offsetBuilder, signedOffsetDistance, offsetOptions);
         return offsetBuilder.claimPolyface();
     }
-    /** Search facets for the first one that intersects the infinite line.
-     * * To process _all_ intersections, callers can supply an `options.acceptIntersection` callback that always returns false.
-     * In this case, `intersectRay3d` will return undefined, but the callback will be invoked for each intersection.
+    /**
+     * Search facets for the first one that intersects the infinite line.
+     * * To process _all_ intersections, callers can supply an `options.acceptIntersection` callback that always
+     * returns `false`.
+     * In this case, `intersectRay3d` will return `undefined`, but the callback will be invoked for each intersection.
      * * Example callback logic:
      *    * Accept the first found facet that intersects the half-line specified by the ray: `return detail.a >= 0.0;`
-     *    * Collect all intersections: `myIntersections.push(detail.clone()); return false;` Then after `intersectRay3d` returns, sort along `ray` with `myIntersections.sort((d0, d1) => d0.a - d1.a);`
-     * @param visitor facet iterator
-     * @param ray infinite line parameterized as a ray. The returned `detail.a` is the intersection parameter on the ray, e.g., zero at `ray.origin` and increasing in `ray.direction`.
-     * @param options options for computing and populating an intersection detail, and an optional callback for accepting one
-     * @return detail for the (accepted) intersection with `detail.IsInsideOrOn === true`, or `undefined` if no (accepted) intersection
+     *    * Collect all intersections: `myIntersections.push(detail.clone()); return false;` Then after `intersectRay3d`
+     * returns, sort along `ray` with `myIntersections.sort((d0, d1) => d0.a - d1.a);`
+     * @param visitor facet iterator.
+     * @param ray infinite line parameterized as a ray. The returned `detail.a` is the intersection parameter on the
+     * ray, e.g., zero at `ray.origin` and increasing in `ray.direction`.
+     * @param options options for computing and populating an intersection detail, and an optional callback for
+     * accepting one.
+     * @return detail for the (accepted) intersection with `detail.IsInsideOrOn === true`, or `undefined` if no
+     * (accepted) intersection.
      * @see PolygonOps.intersectRay3d
     */
     static intersectRay3d(visitor, ray, options) {
@@ -1667,7 +1720,8 @@ export class PolyfaceQuery {
 }
 // amount of computation to do per step of async methods.
 PolyfaceQuery._asyncWorkLimit = 1.e06;
-/** Number of "await" steps executed in recent async calls.
+/**
+ * Number of "await" steps executed in recent async calls.
  * @internal
  */
 PolyfaceQuery.awaitBlockCount = 0;