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

package/lib/cjs/polyface/PolyfaceQuery.js

@@ -9,6 +9,7 @@ exports.PolyfaceQuery = exports.DuplicateFacetClusterSelector = exports.OffsetMe
  * @module Polyface
  */
 /* eslint-disable @typescript-eslint/naming-convention, no-empty */
+// cspell:word internaldocs
 const CurveCollection_1 = require("../curve/CurveCollection");
 const CurveOps_1 = require("../curve/CurveOps");
 const MultiChainCollector_1 = require("../curve/internalContexts/MultiChainCollector");
@@ -51,8 +52,7 @@ const RangeLengthData_1 = require("./RangeLengthData");
  * @public
  */
 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;
@@ -61,20 +61,27 @@ 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 ? Point3dVector3d_1.Vector3d.unitZ() : vectorToEye.clone(), sideAngle === undefined ? Angle_1.Angle.createRadians(Geometry_1.Geometry.smallAngleRadians) : sideAngle.clone(), Geometry_1.Geometry.resolveValue(assembleChains, true), Geometry_1.Geometry.resolveValue(collectOnForwardFacets, true), Geometry_1.Geometry.resolveValue(collectOnSideFacets, true), Geometry_1.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)
@@ -89,22 +96,27 @@ exports.SweepLineStringToFacetsOptions = 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
  */
 class OffsetMeshOptions {
-    /** Constructor -- CAPTURE parameters ... */
-    constructor(smoothSingleAngleBetweenNormals = Angle_1.Angle.createDegrees(25), smoothAccumulatedAngleBetweenNormals = Angle_1.Angle.createDegrees(60), chamferTurnAngle = Angle_1.Angle.createDegrees(90)) {
+    /** Constructor -- CAPTURE parameters. */
+    constructor(smoothSingleAngleBetweenNormals = Angle_1.Angle.createDegrees(25), smoothAccumulatedAngleBetweenNormals = Angle_1.Angle.createDegrees(60), chamferAngleBetweenNormals = Angle_1.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_1.Angle.createDegrees(25), smoothAccumulatedAngleBetweenNormals = Angle_1.Angle.createDegrees(60), chamferTurnAngleBetweenNormals = Angle_1.Angle.createDegrees(120)) {
         const mySmoothSingleRadiansBetweenNormals = smoothSingleAngleBetweenNormals.clone();
@@ -121,25 +133,27 @@ class OffsetMeshOptions {
 }
 exports.OffsetMeshOptions = OffsetMeshOptions;
 /**
- * Enumeration of cases for retaining facets among duplicates
+ * Enumeration of cases for retaining facets among duplicates.
  * @public
  */
 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 || (exports.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
  */
 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_1.LineString3d.createPoints(visitor.point.getPoint3dArray());
         return Loop_1.Loop.create(ls);
@@ -154,11 +168,15 @@ 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_1.Polyface)
                 return PolyfaceQuery.sumFacetAreas(source.createVisitor(1), vectorToEye);
@@ -167,20 +185,21 @@ class PolyfaceQuery {
                 unitVectorToEye = vectorToEye.normalize();
             source.reset();
             while (source.moveToNextFacet()) {
-                const scaledNormal = PolygonOps_1.PolygonOps.areaNormal(source.point.getPoint3dArray());
-                s += unitVectorToEye ? scaledNormal.dotProduct(unitVectorToEye) : scaledNormal.magnitude();
+                const areaNormal = PolygonOps_1.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_1.Polyface)
             return PolyfaceQuery.sumTetrahedralVolumes(source.createVisitor(0), origin);
         let myOrigin = origin;
@@ -195,17 +214,18 @@ 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_1.Polyface)
             return PolyfaceQuery.sumVolumeBetweenFacetsAndPlane(source.createVisitor(0), plane);
@@ -223,18 +243,18 @@ class PolyfaceQuery {
         const singleFacetProducts = Matrix4d_1.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);
@@ -265,7 +285,7 @@ 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_1.Polyface)
             return PolyfaceQuery.sumFacetSecondAreaMomentProducts(source.createVisitor(0), origin);
@@ -276,7 +296,7 @@ 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_1.Polyface)
             return PolyfaceQuery.sumFacetSecondVolumeMomentProducts(source.createVisitor(0), origin);
@@ -287,10 +307,11 @@ 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);
@@ -299,12 +320,13 @@ class PolyfaceQuery {
         const inertiaProducts = PolyfaceQuery.sumFacetSecondAreaMomentProducts(source, origin);
         return MomentData_1.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);
@@ -313,8 +335,10 @@ class PolyfaceQuery {
         const inertiaProducts = PolyfaceQuery.sumFacetSecondVolumeMomentProducts(source, origin);
         return MomentData_1.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_1.Polyface)
@@ -330,56 +354,50 @@ class PolyfaceQuery {
         return true;
     }
     /**
-     * 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.
-     * * 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
+     * Compute a number summarizing the dihedral angles in the mesh.
+     * * 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 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)
-    */
     static dihedralAngleSummary(source, ignoreBoundaries = false) {
+        // more info can be found at geometry/internaldocs/Polyface.md
         const edges = new IndexedEdgeMatcher_1.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_1.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;
@@ -387,8 +405,7 @@ class PolyfaceQuery {
         for (const cluster of manifoldClusters) {
             const sideA = cluster[0];
             const sideB = cluster[1];
-            if (sideA instanceof IndexedEdgeMatcher_1.SortableEdge
-                && sideB instanceof IndexedEdgeMatcher_1.SortableEdge
+            if (sideA instanceof IndexedEdgeMatcher_1.SortableEdge && sideB instanceof IndexedEdgeMatcher_1.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)
@@ -399,26 +416,40 @@ 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.
-     */
-    static isPolyfaceClosedByEdgePairing(source) {
-        return this.isPolyfaceManifold(source, false);
+   * Test for convex volume by dihedral angle tests on all edges.
+   * * 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.
+   * @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;
     }
-    /** 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_1.IndexedEdgeMatcher();
@@ -434,44 +465,18 @@ class PolyfaceQuery {
         edges.sortAndCollectClusters(undefined, allowSimpleBoundaries ? undefined : badClusters, undefined, badClusters);
         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
-     * @param includeNull true to include edges with identical start and end vertex indices.
-     */
-    static boundaryEdges(source, includeTypical = true, includeMismatch = true, includeNull = true) {
-        const result = new CurveCollection_1.BagOfCurves();
-        const announceEdge = (pointA, pointB, _indexA, _indexB, _readIndex) => {
-            result.tryAddChild(LineSegment3d_1.LineSegment3d.create(pointA, pointB));
-        };
-        PolyfaceQuery.announceBoundaryEdges(source, announceEdge, includeTypical, includeMismatch, includeNull);
-        if (result.children.length === 0)
-            return undefined;
-        return result;
-    }
-    /**
-     * 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 includeNull true to include edges with identical start and end vertex indices.
-     */
-    static collectBoundaryEdges(source, includeTypical = true, includeMismatch = true, includeNull = true) {
-        const collector = new MultiChainCollector_1.MultiChainCollector(Geometry_1.Geometry.smallMetricDistance, Geometry_1.Geometry.smallMetricDistance);
-        PolyfaceQuery.announceBoundaryEdges(source, (ptA, ptB) => collector.captureCurve(LineSegment3d_1.LineSegment3d.create(ptA, ptB)), includeTypical, includeMismatch, includeNull);
-        return collector.grabResult(true);
+    /** 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 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) {
@@ -487,17 +492,17 @@ 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();
@@ -514,12 +519,61 @@ class PolyfaceQuery {
         }
     }
     /**
-     * Invoke the callback on each manifold edge whose adjacent facet normals form vectorToEye dot products with opposite sign.
+     * 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) {
+        const result = new CurveCollection_1.BagOfCurves();
+        const announceEdge = (pointA, pointB, _indexA, _indexB, _readIndex) => {
+            result.tryAddChild(LineSegment3d_1.LineSegment3d.create(pointA, pointB));
+        };
+        PolyfaceQuery.announceBoundaryEdges(source, announceEdge, includeTypical, includeMismatch, includeNull);
+        if (result.children.length === 0)
+            return undefined;
+        return result;
+    }
+    /**
+     * Collect boundary edges.
+     * * Return the edges as the simplest collection of chains of line segments.
+     * @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) {
+        const collector = new MultiChainCollector_1.MultiChainCollector(Geometry_1.Geometry.smallMetricDistance, Geometry_1.Geometry.smallMetricDistance);
+        PolyfaceQuery.announceBoundaryEdges(source, (ptA, ptB) => collector.captureCurve(LineSegment3d_1.LineSegment3d.create(ptA, ptB)), includeTypical, includeMismatch, includeNull);
+        return collector.grabResult(true);
+    }
+    /**
+     * 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_1.Polyface)
+            return this.createIndexedEdges(polyface.createVisitor(1));
+        const edges = new IndexedEdgeMatcher_1.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_1.Angle.createSmallAngle()) {
         if (source instanceof Polyface_1.Polyface)
@@ -569,16 +623,17 @@ 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_1.Angle.createSmallAngle()) {
         const collector = new MultiChainCollector_1.MultiChainCollector(Geometry_1.Geometry.smallMetricDistance, Geometry_1.Geometry.smallMetricDistance);
         PolyfaceQuery.announceSilhouetteEdges(source, (ptA, ptB) => collector.captureCurve(LineSegment3d_1.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.
      */
@@ -591,7 +646,24 @@ 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()) {
@@ -599,16 +671,8 @@ 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:
@@ -631,14 +695,15 @@ 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_1.Polyface) {
             return this.partitionFacetIndicesByVertexConnectedComponent(polyface.createVisitor(0));
         }
-        // The polyface is really a visitor !!!
+        // The polyface is really a visitor
         const context = new UnionFind_1.UnionFindContext(this.visitorClientPointCount(polyface));
         for (polyface.reset(); polyface.moveToNextFacet();) {
             const firstVertexIndexOnThisFacet = polyface.pointIndex[0];
@@ -666,9 +731,9 @@ 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) {
@@ -703,13 +768,13 @@ 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_1.Angle.createDegrees(1.0e-3)) {
         const partitionedIndices = this.partitionFacetIndicesByVisibilityVector(polyface, vectorToEye, sideAngleTolerance);
@@ -719,10 +784,9 @@ 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_1.MultiChainCollector(Geometry_1.Geometry.smallMetricDistance, 1000);
@@ -733,9 +797,9 @@ 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_1.Polyface)
@@ -794,14 +858,14 @@ 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_1.Polyface)
@@ -837,9 +901,7 @@ 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_1.Polyface) {
             return this.clonePartitions(polyface.createVisitor(0), partitions);
@@ -862,7 +924,7 @@ 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_1.Polyface) {
             return this.cloneFiltered(source.createVisitor(0), filter);
@@ -932,46 +994,44 @@ 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_1.Polyface)
-            return visitor.data.point.length;
-        const polyface = visitor.clientPolyface();
+    /** Return the point count of the `source`. */
+    static visitorClientPointCount(source) {
+        if (source instanceof Polyface_1.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_1.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_1.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 UnionFind_1.UnionFindContext(numFacets);
@@ -1002,10 +1062,12 @@ 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_1.Polyface) {
@@ -1030,7 +1092,8 @@ 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.
      */
@@ -1044,7 +1107,7 @@ 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);
     }
@@ -1057,11 +1120,10 @@ class PolyfaceQuery {
      */
     static sweepLineStringToFacets(linestringPoints, polyfaceOrVisitor, options) {
         let result = [];
-        // setup default options:
+        // setup default options
         if (options === undefined)
             options = SweepLineStringToFacetsOptions.create(Point3dVector3d_1.Vector3d.unitZ(), Angle_1.Angle.createRadians(Geometry_1.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 = ChainMerge_1.ChainMergeContext.create();
@@ -1092,9 +1154,9 @@ 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());
@@ -1104,7 +1166,7 @@ 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 = ChainMerge_1.ChainMergeContext.create();
@@ -1138,32 +1200,36 @@ 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(Point3dVector3d_1.Vector3d.unitZ(), Angle_1.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(Point3dVector3d_1.Vector3d.unitZ(), Angle_1.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.
      */
@@ -1177,7 +1243,7 @@ class PolyfaceQuery {
         return chains;
     }
     /**
-     * * Examine ranges of facets.
+     * Examine ranges of facets.
      * * Return statistical summary of x,y,z ranges.
      */
     static collectRangeLengthData(polyface) {
@@ -1185,17 +1251,18 @@ class PolyfaceQuery {
             return this.collectRangeLengthData(polyface.createVisitor(0));
         }
         const rangeData = new RangeLengthData_1.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_1.XYPointBuckets.create(polyface.data.point, 30);
         const builder = PolyfaceBuilder_1.PolyfaceBuilder.create();
         const edgeRange = Range_1.Range3d.createNull();
@@ -1206,7 +1273,7 @@ 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);
@@ -1217,12 +1284,12 @@ class PolyfaceQuery {
                 edgeRange.extend(point1);
                 edgeRange.ensureMinLengths(Geometry_1.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;
@@ -1243,14 +1310,13 @@ 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)
@@ -1263,25 +1329,12 @@ class PolyfaceQuery {
         return 0;
     }
     /**
-     * * 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.
-     */
-    static collectDuplicateFacetIndices(polyface, includeSingletons = false) {
-        const result = [];
-        this.announceDuplicateFacetIndices(polyface, (clusterFacetIndices) => {
-            if (includeSingletons || clusterFacetIndices.length > 1)
-                result.push(clusterFacetIndices.slice());
-        });
-        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();
@@ -1289,12 +1342,12 @@ 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]);
@@ -1322,9 +1375,26 @@ class PolyfaceQuery {
             announceCluster(clusterArray);
         }
     }
-    /** Return a new facet set with a subset of facets in source
+    /**
+     * Collect facet duplicates.
+     * @param polyface the polyface.
+     * @param includeSingletons if true, non-duplicated facets are included in the output.
+     * @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 = [];
+        this.announceDuplicateFacetIndices(polyface, (clusterFacetIndices) => {
+            if (includeSingletons || clusterFacetIndices.length > 1)
+                result.push(clusterFacetIndices.slice());
+        });
+        return result;
+    }
+    /**
+     * 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_1.PolyfaceBuilder.create();
@@ -1350,25 +1420,23 @@ 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_1.PolyfaceBuilder.create();
         const vector01 = Point3dVector3d_1.Vector3d.create();
         const vector12 = Point3dVector3d_1.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);
@@ -1383,7 +1451,7 @@ 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++) {
@@ -1399,9 +1467,9 @@ 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) {
@@ -1416,9 +1484,9 @@ 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) {
@@ -1431,9 +1499,9 @@ 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;
@@ -1444,29 +1512,13 @@ 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_1.Polyface)
-            return this.createIndexedEdges(polyface.createVisitor(1));
-        const edges = new IndexedEdgeMatcher_1.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_1.Polyface)
@@ -1501,13 +1553,13 @@ 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);
@@ -1536,7 +1588,8 @@ 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) {
@@ -1549,18 +1602,18 @@ 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) {
@@ -1579,28 +1632,22 @@ 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 FacetOrientation_1.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_1.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.
     */
@@ -1609,9 +1656,9 @@ 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()) {
@@ -1620,16 +1667,22 @@ class PolyfaceQuery {
         OffsetMeshContext_1.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) {
@@ -1673,7 +1726,8 @@ class PolyfaceQuery {
 exports.PolyfaceQuery = 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;