@itwin/core-geometry 5.1.0-dev.9 → 5.2.0-dev.2

package/lib/esm/polyface/PolyfaceQuery.js

@@ -36,12 +36,11 @@ import { SpacePolygonTriangulation } from "../topology/SpaceTriangulation";
 import { ConvexFacetLocationDetail, NonConvexFacetLocationDetail, TriangularFacetLocationDetail, } from "./FacetLocationDetail";
 import { FacetOrientationFixup } from "./FacetOrientation";
 import { IndexedEdgeMatcher, SortableEdge } from "./IndexedEdgeMatcher";
-import { IndexedPolyfaceSubsetVisitor } from "./IndexedPolyfaceVisitor";
 import { BuildAverageNormalsContext } from "./multiclip/BuildAverageNormalsContext";
 import { OffsetMeshContext } from "./multiclip/OffsetMeshContext";
 import { ClipSweptLineStringContext, EdgeClipData, SweepLineStringToFacetContext } from "./multiclip/SweepLineStringToFacetContext";
 import { XYPointBuckets } from "./multiclip/XYPointBuckets";
-import { Polyface } from "./Polyface";
+import { IndexedPolyface, Polyface } from "./Polyface";
 import { PolyfaceBuilder } from "./PolyfaceBuilder";
 import { RangeLengthData } from "./RangeLengthData";
 /**
@@ -69,14 +68,27 @@ export class SweepLineStringToFacetsOptions {
     sideAngle;
     /** Option to assemble lines into chains. */
     assembleChains;
+    /**
+     * Optional searcher object for vertical sweep speedup. If provided, `vectorToEye` must be the positive Z vector.
+     * @example To construct a 5x5 indexed search grid:
+     * ````
+     * const xyRange = Range2d.createFrom(myPolyface.range());
+     * const searcher = GriddedRaggedRange2dSetWithOverflow.create<number>(xyRange, 5, 5)!;
+     * for (const visitor = myPolyface.createVisitor(0); visitor.moveToNextFacet();) {
+     *   searcher.addRange(visitor.point.getRange(), visitor.currentReadIndex());
+     * }
+     * ````
+     */
+    searcher;
     /** Constructor. Captures fully-checked parameters from static create method. */
-    constructor(vectorToEye, sideAngle, assembleChains, collectOnForwardFacets, collectOnSideFacets, collectOnRearFacets) {
+    constructor(vectorToEye, sideAngle, assembleChains, collectOnForwardFacets, collectOnSideFacets, collectOnRearFacets, searcher) {
         this.vectorToEye = vectorToEye;
         this.sideAngle = sideAngle;
         this.assembleChains = assembleChains;
         this.collectOnForwardFacets = collectOnForwardFacets;
         this.collectOnSideFacets = collectOnSideFacets;
         this.collectOnRearFacets = collectOnRearFacets;
+        this.searcher = searcher;
     }
     /**
      * Create an options structure.
@@ -85,14 +97,12 @@ export class SweepLineStringToFacetsOptions {
      * * 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));
+    static create(vectorToEye, sideAngle, assembleChains, collectOnForwardFacets, collectOnSideFacets, collectOnRearFacets, searcher) {
+        return new SweepLineStringToFacetsOptions((!vectorToEye || searcher) ? Vector3d.unitZ() : vectorToEye.clone(), sideAngle?.clone() ?? Angle.createRadians(Geometry.smallAngleRadians), assembleChains ?? true, collectOnForwardFacets ?? true, collectOnSideFacets ?? true, collectOnRearFacets ?? true, searcher);
     }
     /** Return `true` if all outputs are requested. */
     get collectAll() {
-        return this.collectOnForwardFacets === true &&
-            this.collectOnSideFacets === true &&
-            this.collectOnRearFacets === true;
+        return this.collectOnForwardFacets && this.collectOnSideFacets && this.collectOnRearFacets;
     }
     /**
      * Decide if the instance collector flags accept a facet with the given normal.
@@ -203,21 +213,21 @@ export class PolyfaceQuery {
      * @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`.
+     * @returns the sum of all facet areas.
      */
     static sumFacetAreas(source, vectorToEye) {
         let sum = 0;
-        if (source !== undefined) {
-            if (source instanceof Polyface)
-                return PolyfaceQuery.sumFacetAreas(source.createVisitor(1), vectorToEye);
-            let unitVectorToEye;
-            if (vectorToEye !== undefined)
-                unitVectorToEye = vectorToEye.normalize();
-            source.reset();
-            while (source.moveToNextFacet()) {
-                const areaNormal = PolygonOps.areaNormal(source.point.getPoint3dArray());
-                sum += unitVectorToEye ? areaNormal.dotProduct(unitVectorToEye) : areaNormal.magnitude();
-            }
+        if (source instanceof Polyface)
+            source = source.createVisitor(1);
+        else
+            source.setNumWrap(1);
+        let unitVectorToEye;
+        if (vectorToEye !== undefined)
+            unitVectorToEye = vectorToEye.normalize();
+        source.reset();
+        while (source.moveToNextFacet()) {
+            const areaNormal = PolygonOps.areaNormal(source.point.getPoint3dArray());
+            sum += unitVectorToEye ? areaNormal.dotProduct(unitVectorToEye) : areaNormal.magnitude();
         }
         return sum;
     }
@@ -251,68 +261,46 @@ export class PolyfaceQuery {
     }
     /**
      * 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.
-     * * positiveProjectedFacetAreaMoments, negativeProjectedFacetAreaMoments = moment data with centroid, area, and second
-     * moments with respect to the centroid.
+     * @param source facet set
+     * @param plane infinite plane bounding volume between the input facets and (virtual) side facets perpendicular to the plane.
+     * @param skipMoments whether to skip computation of the area moments. Set to `true` if only volume is needed. Default is `false`.
+     * @returns a structure with multiple sums:
+     * * volume: the sum of (signed) volumes between facets and the plane.
+     * * positiveProjectedFacetAreaMoments, negativeProjectedFacetAreaMoments: area moment data (centroid, signed area,
+     * and second moments with respect to the centroid), separately computed for the input facets that project with
+     * positive/negative area onto the plane.
      */
-    static sumVolumeBetweenFacetsAndPlane(source, plane) {
-        if (source instanceof Polyface)
-            return PolyfaceQuery.sumVolumeBetweenFacetsAndPlane(source.createVisitor(0), plane);
-        const facetOrigin = Point3d.create();
-        const targetA = Point3d.create();
-        const targetB = Point3d.create();
-        const triangleNormal = Vector3d.create();
-        const planeNormal = plane.getNormalRef();
-        let h0, hA, hB;
-        let signedVolumeSum = 0.0;
-        let signedTriangleArea;
-        let singleFacetArea;
-        const positiveAreaMomentSums = MomentData.create(undefined, true);
-        const negativeAreaMomentSums = MomentData.create(undefined, true);
-        const singleFacetProducts = Matrix4d.createZero();
-        const projectToPlane = plane.getProjectionToPlane();
-        source.reset();
+    static sumVolumeBetweenFacetsAndPlane(source, plane, skipMoments) {
+        const visitor = source instanceof Polyface ? source.createVisitor(0) : source;
+        visitor.setNumWrap(0);
+        const workPoint0 = Point3d.create();
+        const workPoint1 = Point3d.create();
+        const workVector = Vector3d.create();
+        const workMatrix = Matrix4d.createZero();
+        let signedVolumeTimes6 = 0.0;
+        const posSums = skipMoments ? undefined : MomentData.create(undefined, true);
+        const negSums = skipMoments ? undefined : MomentData.create(undefined, true);
         // 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 (let i = 1; i + 1 < source.point.length; i++) {
-                source.point.getPoint3dAtUncheckedPointIndex(i, targetA);
-                source.point.getPoint3dAtUncheckedPointIndex(i + 1, targetB);
-                facetOrigin.crossProductToPoints(targetA, targetB, triangleNormal);
-                hA = plane.altitude(targetA);
-                hB = plane.altitude(targetB);
-                signedTriangleArea = planeNormal.dotProduct(triangleNormal);
-                singleFacetArea += signedTriangleArea;
-                signedVolumeSum += signedTriangleArea * (h0 + hA + hB);
-            }
-            singleFacetProducts.setZero();
-            source.point.multiplyTransformInPlace(projectToPlane);
-            PolygonOps.addSecondMomentAreaProducts(source.point, facetOrigin, singleFacetProducts);
-            if (singleFacetArea > 0) {
-                positiveAreaMomentSums.accumulateProductsFromOrigin(facetOrigin, singleFacetProducts, 1.0);
-            }
-            else {
-                negativeAreaMomentSums.accumulateProductsFromOrigin(facetOrigin, singleFacetProducts, 1.0);
+        // - sum signed area and volume contributions (for non-convex facet, signs can be mixed).
+        // - each projected area contribution is twice the area of a triangle.
+        // - each volume contribution is 3 times the actual volume -- a third of the altitude sum is the centroid altitude.
+        const options = { skipMoments, p0: workPoint0, p1: workPoint1, v0: workVector, m0: workMatrix };
+        for (visitor.reset(); visitor.moveToNextFacet();) {
+            const facetData = PolygonOps.volumeBetweenPolygonAndPlane(visitor.point, plane, options);
+            signedVolumeTimes6 += facetData.volume6;
+            if (!skipMoments) {
+                assert(posSums !== undefined && negSums !== undefined && facetData.origin !== undefined && facetData.products !== undefined);
+                if (facetData.area2 > 0)
+                    posSums.accumulateProductsFromOrigin(facetData.origin, facetData.products, 1.0);
+                else
+                    negSums.accumulateProductsFromOrigin(facetData.origin, facetData.products, 1.0);
             }
         }
-        positiveAreaMomentSums.shiftOriginAndSumsToCentroidOfSums();
-        negativeAreaMomentSums.shiftOriginAndSumsToCentroidOfSums();
-        const positiveAreaMoments = MomentData.inertiaProductsToPrincipalAxes(positiveAreaMomentSums.origin, positiveAreaMomentSums.sums);
-        const negativeAreaMoments = MomentData.inertiaProductsToPrincipalAxes(negativeAreaMomentSums.origin, negativeAreaMomentSums.sums);
         return {
-            volume: signedVolumeSum / 6.0,
-            positiveProjectedFacetAreaMoments: positiveAreaMoments,
-            negativeProjectedFacetAreaMoments: negativeAreaMoments,
+            volume: signedVolumeTimes6 / 6.0,
+            positiveProjectedFacetAreaMoments: posSums ? MomentData.inertiaProductsToPrincipalAxes(posSums.origin, posSums.sums) : undefined,
+            negativeProjectedFacetAreaMoments: negSums ? MomentData.inertiaProductsToPrincipalAxes(negSums.origin, negSums.sums) : undefined,
         };
     }
     /** Return the inertia products [xx,xy,xz,xw,yw, etc] integrated over all all facets as viewed from origin. */
@@ -387,7 +375,7 @@ export class PolyfaceQuery {
      * 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 source facets.
      * @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.
@@ -403,19 +391,21 @@ export class PolyfaceQuery {
     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 vertices = source instanceof Polyface ? source.data.point : undefined;
+        const visitor = source instanceof Polyface ? source.createVisitor(1) : source;
+        visitor.setNumWrap(1);
         const centroidNormal = [];
         let normalCounter = 0;
-        while (visitor.moveToNextFacet()) {
+        for (visitor.reset(); visitor.moveToNextFacet();) {
             const numEdges = visitor.pointCount - 1;
             const normal = PolygonOps.centroidAreaNormal(visitor.point);
             if (normal === undefined)
                 return -2;
             centroidNormal.push(normal);
             for (let i = 0; i < numEdges; i++) {
-                edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), normalCounter);
+                const edge = edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), normalCounter);
+                if (!vertices) // decorate if we don't have vertices to query later
+                    edge.edgeVector = Vector3d.createStartEnd(visitor.point.getPoint3dAtUncheckedPointIndex(i), visitor.point.getPoint3dAtUncheckedPointIndex(i + 1));
             }
             normalCounter++;
         }
@@ -433,11 +423,16 @@ export class PolyfaceQuery {
         let numNegative = 0;
         const edgeVector = Vector3d.create();
         for (const cluster of manifoldClusters) {
-            const sideA = cluster[0];
-            const sideB = cluster[1];
-            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 (Array.isArray(cluster) && cluster.length === 2) {
+                const sideA = cluster[0];
+                const sideB = cluster[1];
+                if (vertices)
+                    vertices.vectorIndexIndex(sideA.startVertex, sideA.endVertex, edgeVector);
+                else
+                    edgeVector.setFrom(sideA.edgeVector);
+                const facetNormalA = centroidNormal[sideA.facetIndex].direction;
+                const facetNormalB = centroidNormal[sideB.facetIndex].direction;
+                const dihedralAngle = facetNormalA.signedAngleTo(facetNormalB, edgeVector);
                 if (dihedralAngle.isAlmostZero)
                     numPlanar++;
                 else if (dihedralAngle.radians > 0.0)
@@ -473,26 +468,50 @@ export class PolyfaceQuery {
     static isConvexByDihedralAngleCount(source, ignoreBoundaries = false) {
         return this.dihedralAngleSummary(source, ignoreBoundaries) > 0;
     }
+    /** Helper function to detect a subset visitor. */
+    static isSubsetVisitor(visitor) {
+        if (visitor instanceof Polyface)
+            return false;
+        const parentFacetCount = visitor.clientPolyface()?.facetCount;
+        const visitableFacetCount = visitor.getVisitableFacetCount?.();
+        if (parentFacetCount === undefined || visitableFacetCount === undefined)
+            return false;
+        return parentFacetCount > visitableFacetCount;
+    }
     /**
-     * Test edges pairing in `source` mesh.
-     * * For `allowSimpleBoundaries === false`, a return value of `true` means this is a closed 2-manifold surface.
-     * * For `allowSimpleBoundaries === true`, a return value of `true` means this is a 2-manifold surface which may have
-     * a boundary, but is still properly matched internally.
+     * Faster version of isPolyfaceManifold for specific input.
+     * @returns whether the mesh is manifold, or undefined if unsuccessful.
+     */
+    static isPolyfaceManifoldFast(source, allowSimpleBoundaries) {
+        if (allowSimpleBoundaries)
+            return undefined; // edgeMateIndex does not distinguish boundary edges from non-manifold edges so we can only speed things up if we search for both
+        if (this.isSubsetVisitor(source))
+            return false; // edgeMateIndex doesn't capture the facet subset boundary
+        const parentData = IndexedPolyface.hasEdgeMateIndex(source);
+        if (!parentData)
+            return undefined;
+        for (const edgeMate of parentData.edgeMateIndex) {
+            if (edgeMate === undefined)
+                return false; // found a boundary or non-manifold edge
+        }
+        return true; // this is a 2-manifold closed surface
+    }
+    /**
+     * Test edge pairing in `source` mesh.
      * * 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.
+     * * Any edge with 2 adjacent facets in the same direction triggers `false` return.
+     * * Null edges are ignored.
+     * @param source facet set to examine
+     * @param allowSimpleBoundaries if `false` (default), a return value of `true` means the facets form a closed
+     * 2-manifold surface; if `true`, a return value of `true` means the facets form a 2-manifold surface which may
+     * have a boundary, but is still properly matched internally.
     */
     static isPolyfaceManifold(source, allowSimpleBoundaries = false) {
-        const edges = new IndexedEdgeMatcher();
-        const visitor = source.createVisitor(1);
-        visitor.reset();
-        while (visitor.moveToNextFacet()) {
-            const numEdges = visitor.pointCount - 1;
-            for (let i = 0; i < numEdges; i++) {
-                edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), visitor.currentReadIndex());
-            }
-        }
+        const isManifold = this.isPolyfaceManifoldFast(source, allowSimpleBoundaries);
+        if (isManifold !== undefined)
+            return isManifold;
         const badClusters = [];
-        edges.sortAndCollectClusters(undefined, allowSimpleBoundaries ? undefined : badClusters, undefined, badClusters);
+        this.createIndexedEdges(source).sortAndCollectClusters(undefined, allowSimpleBoundaries ? undefined : badClusters, undefined, badClusters);
         return badClusters.length === 0;
     }
     /** Test if the facets in `source` occur in perfectly mated pairs, as is required for a closed manifold volume. */
@@ -500,50 +519,107 @@ export class PolyfaceQuery {
         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.
+     * Faster version of announceBoundaryEdges for specific input.
+     * @returns true if successfully announced boundary edges.
+     */
+    static announceBoundaryEdgesFast(source, announceEdge, includeTypical, includeMismatch, includeNull) {
+        if (includeTypical !== includeMismatch)
+            return false; // edgeMateIndex does not distinguish boundary edges from non-manifold edges
+        if (!includeTypical && !includeNull)
+            return true;
+        if (this.isSubsetVisitor(source))
+            return false; // edgeMateIndex doesn't capture the facet subset boundary
+        const parentData = IndexedPolyface.hasEdgeMateIndex(source);
+        if (!parentData)
+            return false;
+        const pointA = Point3d.create();
+        const pointB = Point3d.create();
+        for (let edgeIndex = 0; edgeIndex < parentData.edgeMateIndex.length; edgeIndex++) {
+            const edgeMate = parentData.edgeMateIndex[edgeIndex];
+            const announceBoundaryOrNonManifoldEdge = includeTypical && edgeMate === undefined;
+            const announceNullEdge = includeNull && edgeMate === edgeIndex;
+            if (announceBoundaryOrNonManifoldEdge || announceNullEdge) {
+                const facetIndex = parentData.parent.edgeIndexToFacetIndex(edgeIndex);
+                if (facetIndex !== undefined) { // should always be defined
+                    const pointIndexA = parentData.parent.data.pointIndex[edgeIndex];
+                    let nextEdgeIndex = edgeIndex + 1;
+                    if (nextEdgeIndex >= parentData.parent.facetIndex1(facetIndex))
+                        nextEdgeIndex = parentData.parent.facetIndex0(facetIndex);
+                    const pointIndexB = parentData.parent.data.pointIndex[nextEdgeIndex];
+                    parentData.parent.data.getPoint(pointIndexA, pointA);
+                    parentData.parent.data.getPoint(pointIndexB, pointB);
+                    announceEdge(pointA, pointB, pointIndexA, pointIndexB, facetIndex);
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Announce boundary edges of the facet set as line segments.
      * @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.
+     * start and end vertex indices, and facet index.
+     * @param includeTypical true to announce typical boundary edges with a single adjacent facet. Default is true.
+     * @param includeMismatch true to announce non-manifold edges (more than 2 adjacent facets, or mismatched
+     * orientations). Default is true.
+     * @param includeNull true to announce edges with identical start and end vertex indices. Default is true.
+     * @see [[announceBoundaryChainsAsLineString3d]] for boundary linestring announcement
+     * @see [[collectBoundaryEdges]] for boundary chain collection
+     * @see [[boundaryEdges]] for boundary edge collection
      */
     static announceBoundaryEdges(source, announceEdge, includeTypical = true, includeMismatch = true, includeNull = true) {
-        if (source === undefined || (!includeTypical && !includeMismatch && !includeNull))
+        if (this.announceBoundaryEdgesFast(source, announceEdge, includeTypical, includeMismatch, includeNull))
             return;
-        const edges = new IndexedEdgeMatcher();
+        if (!includeTypical && !includeMismatch && !includeNull)
+            return;
+        const vertices = source instanceof Polyface ? source.data.point : undefined;
         const visitor = source instanceof Polyface ? source.createVisitor(1) : source;
         visitor.setNumWrap(1);
-        visitor.reset();
-        while (visitor.moveToNextFacet()) {
+        const edges = new IndexedEdgeMatcher();
+        for (visitor.reset(); visitor.moveToNextFacet();) {
             const numEdges = visitor.pointCount - 1;
             for (let i = 0; i < numEdges; i++) {
-                edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), visitor.currentReadIndex());
+                const edge = edges.addEdge(visitor.clientPointIndex(i), visitor.clientPointIndex(i + 1), visitor.currentReadIndex());
+                if (!vertices) { // decorate if we don't have vertices to query later
+                    edge.pointA = visitor.point.getPoint3dAtUncheckedPointIndex(i);
+                    edge.pointB = visitor.point.getPoint3dAtUncheckedPointIndex(i + 1);
+                }
             }
         }
         const boundaryEdges = [];
-        edges.sortAndCollectClusters(undefined, includeTypical ? boundaryEdges : undefined, includeNull ? boundaryEdges : undefined, includeMismatch ? boundaryEdges : undefined);
+        const typicalEdges = includeTypical ? boundaryEdges : undefined;
+        const nullEdges = includeNull ? boundaryEdges : undefined;
+        const mismatchEdges = includeMismatch ? boundaryEdges : undefined;
+        edges.sortAndCollectClusters(undefined, typicalEdges, nullEdges, mismatchEdges);
         if (boundaryEdges.length === 0)
             return;
-        const sourcePolyface = visitor.clientPolyface();
         const pointA = Point3d.create();
         const pointB = Point3d.create();
         for (const e of boundaryEdges) {
-            const e1 = e instanceof SortableEdge ? e : e[0];
-            const indexA = e1.vertexIndexA;
-            const indexB = e1.vertexIndexB;
-            if (sourcePolyface.data.getPoint(indexA, pointA) && sourcePolyface.data.getPoint(indexB, pointB))
-                announceEdge(pointA, pointB, indexA, indexB, e1.facetIndex);
+            const e1 = e instanceof SortableEdge ? e : e[0]; // only report the first edge in a cluster!
+            const indexA = e1.startVertex;
+            const indexB = e1.endVertex;
+            if (vertices) {
+                vertices.getPoint3dAtUncheckedPointIndex(indexA, pointA);
+                vertices.getPoint3dAtUncheckedPointIndex(indexB, pointB);
+            }
+            else {
+                pointA.setFrom(e1.pointA);
+                pointB.setFrom(e1.pointB);
+            }
+            announceEdge(pointA, pointB, indexA, indexB, e1.facetIndex);
         }
     }
     /**
-     * Construct a CurveCollection containing boundary edges.
-     * * Each edge is a LineSegment3d.
+     * Collect boundary edges of the facet set as an unordered collection 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.
+     * @param includeTypical true to include typical boundary edges with a single adjacent facet. Default is true.
+     * @param includeMismatch true to include non-manifold edges (more than 2 adjacent facets, or mismatched
+     * orientations). Default is true.
+     * @param includeNull true to include edges with identical start and end vertex indices. Default is true.
+     * @see [[announceBoundaryChainsAsLineString3d]] for boundary linestring announcement
+     * @see [[collectBoundaryEdges]] for boundary chain collection
+     * @see [[announceBoundaryEdges]] for boundary edge announcement
      */
     static boundaryEdges(source, includeTypical = true, includeMismatch = true, includeNull = true) {
         const result = new BagOfCurves();
@@ -556,33 +632,32 @@ export class PolyfaceQuery {
         return result;
     }
     /**
-     * Collect boundary edges.
-     * * Return the edges as the simplest collection of chains of line segments.
+     * Collect boundary edges of the facet set as the simplest collection of chains of line segments.
      * @param source polyface or visitor.
-     * @param includeTypical true to 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.
+     * @param includeTypical true to include typical boundary edges with a single adjacent facet. Default is true.
+     * @param includeMismatch true to include non-manifold edges (more than 2 adjacent facets, or mismatched
+     * orientations). Default is true.
+     * @param includeNull true to include edges with identical start and end vertex indices. Default is true.
+     * @see [[announceBoundaryChainsAsLineString3d]] for boundary linestring announcement
+     * @see [[announceBoundaryEdges]] for boundary edge announcement
+     * @see [[boundaryEdges]] for boundary edge collection
      */
     static collectBoundaryEdges(source, includeTypical = true, includeMismatch = true, includeNull = true) {
         const collector = new MultiChainCollector(Geometry.smallMetricDistance, Geometry.smallMetricDistance);
-        PolyfaceQuery.announceBoundaryEdges(source, (ptA, ptB) => collector.captureCurve(LineSegment3d.create(ptA, ptB)), includeTypical, includeMismatch, includeNull);
+        const announceEdge = (ptA, ptB) => collector.captureCurve(LineSegment3d.create(ptA, ptB));
+        PolyfaceQuery.announceBoundaryEdges(source, announceEdge, 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.
-    */
+     * Load an IndexedEdgeMatcher from the edges of a mesh.
+     * @param polyface a mesh or visitor
+     */
     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());
-            }
-        }
+        const visitor = polyface instanceof Polyface ? polyface.createVisitor(1) : polyface;
+        visitor.setNumWrap(1);
+        for (visitor.reset(); visitor.moveToNextFacet();)
+            edges.addPath(visitor.pointIndex, visitor.currentReadIndex(), false);
         return edges;
     }
     /**
@@ -618,8 +693,8 @@ export class PolyfaceQuery {
         for (const pair of manifoldEdges) {
             if (!Array.isArray(pair) || pair.length !== 2)
                 continue;
-            const indexA = pair[0].vertexIndexA;
-            const indexB = pair[0].vertexIndexB;
+            const indexA = pair[0].startVertex;
+            const indexB = pair[0].endVertex;
             if (!mesh.data.getPoint(indexA, pointA) || !mesh.data.getPoint(indexB, pointB))
                 continue;
             const face0 = analyzeFace(pair[0].facetIndex);
@@ -794,7 +869,7 @@ export class PolyfaceQuery {
     }
     /**
      * Return the boundary of facets that are facing the eye.
-     * @param polyface the indexed polyface
+     * @param source polyface or visitor. Must be capable of constructing a subset visitor.
      * @param visibilitySubset selector among the visible facet sets extracted by partitionFacetIndicesByVisibilityVector
      *   * 0 ==> forward facing
      *   * 1 ==> rear facing
@@ -802,21 +877,29 @@ export class PolyfaceQuery {
      * @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);
+    static boundaryOfVisibleSubset(source, visibilitySelect, vectorToEye, sideAngleTolerance = Angle.createDegrees(1.0e-3)) {
+        const visitor = source instanceof Polyface ? source.createVisitor(0) : source;
+        if (!visitor.createSubsetVisitor)
+            return undefined;
+        const partitionedIndices = this.partitionFacetIndicesByVisibilityVector(source, vectorToEye, sideAngleTolerance);
         if (partitionedIndices[visibilitySelect].length === 0)
             return undefined;
-        const visitor = IndexedPolyfaceSubsetVisitor.createSubsetVisitor(polyface, partitionedIndices[visibilitySelect], 1);
-        return this.boundaryEdges(visitor, true, false, false);
+        const subsetVisitor = visitor.createSubsetVisitor(partitionedIndices[visibilitySelect], 1);
+        return this.boundaryEdges(subsetVisitor, true, false, false);
     }
     /**
-     * Search for edges with only 1 adjacent facet.
-     * * Accumulate them into chains.
-     * * Emit the chains to the `announceChain` callback.
+     * Announce boundary edges of the facet set as linestrings.
+     * * Ignores non-manifold interior edges and null edges.
+     * @param source polyface or visitor.
+     * @param announceChain function to be called with each chain of boundary edges.
+     * @see [[collectBoundaryEdges]] for boundary chain collection
+     * @see [[announceBoundaryEdges]] for boundary edge announcement
+     * @see [[boundaryEdges]] for boundary edge collection
      */
-    static announceBoundaryChainsAsLineString3d(mesh, announceChain) {
+    static announceBoundaryChainsAsLineString3d(source, announceChain) {
         const collector = new MultiChainCollector(Geometry.smallMetricDistance); // no planarity tolerance needed
-        PolyfaceQuery.announceBoundaryEdges(mesh, (pointA, pointB, _indexA, _indexB) => collector.captureCurve(LineSegment3d.create(pointA, pointB)), true, false, false);
+        const announceEdge = (ptA, ptB) => collector.captureCurve(LineSegment3d.create(ptA, ptB));
+        PolyfaceQuery.announceBoundaryEdges(source, announceEdge, true, false, false);
         collector.announceChainsAsLineString3d(announceChain);
     }
     /**
@@ -1161,94 +1244,99 @@ export class PolyfaceQuery {
         });
         return builder.claimPolyface(true);
     }
-    /** @deprecated in 4.x. Use [[sweepLineStringToFacetsXYReturnSweptFacets]] instead. */
+    /** @deprecated in 4.7.0 - will not be removed until after 2026-06-13. Use [[sweepLineStringToFacetsXYReturnSweptFacets]] instead. */
     static sweepLinestringToFacetsXYreturnSweptFacets(linestringPoints, polyface) {
         return this.sweepLineStringToFacetsXYReturnSweptFacets(linestringPoints, polyface);
     }
     /**
-     * Sweep the line string to intersections with a mesh.
-     * * Return collected line segments.
-     * * If no options are given, the default sweep direction is the z-axis, and chains are assembled and returned.
-     * * See [[SweepLineStringToFacetsOptions]] for input and output options, including filtering by forward/side/rear facets.
+     * Sweep the line string to intersections with a mesh and return collected line segments.
      * * Facets are ASSUMED to be convex and planar, and not overlap in the sweep direction.
+     * @param points the linestring to drape onto the mesh.
+     * @param source target facet set. For best results, facets should be convex and planar.
+     * @param options input, filtering, search, and output options.
+     * * If `undefined`, the default sweep direction is the positive z-axis, and chains are assembled and returned.
+     * * For faster _vertical_ sweep, a pre-computed range tree can be supplied in `options.searcher`.
+     * * For faster _non-vertical_ sweep, first transform inputs with the inverse of the transform
+     * `T = Transform.createRigidFromOriginAndVector(undefined, options.vectorToEye)`, construct the searcher on these
+     * local facets, call `sweepLineStringToFacets/XY` with these local inputs (and default sweep direction), and lastly,
+     * transform the returned draped linework back to world coordinates with `T`.
      */
-    static sweepLineStringToFacets(linestringPoints, polyfaceOrVisitor, options) {
+    static sweepLineStringToFacets(points, source, options) {
         let result = [];
-        // setup default options
         if (options === undefined)
-            options = SweepLineStringToFacetsOptions.create(Vector3d.unitZ(), Angle.createRadians(Geometry.smallAngleRadians), // tight geometry tolerance for vertical side facets
-            true, true, true, true);
+            options = SweepLineStringToFacetsOptions.create();
         let chainContext;
         if (options.assembleChains)
             chainContext = ChainMergeContext.create();
-        const context = ClipSweptLineStringContext.create(linestringPoints, options.vectorToEye);
-        if (context) {
-            let visitor;
-            if (polyfaceOrVisitor instanceof Polyface)
-                visitor = polyfaceOrVisitor.createVisitor(0);
-            else
-                visitor = polyfaceOrVisitor;
-            const workNormal = Vector3d.createZero();
-            for (visitor.reset(); visitor.moveToNextFacet();) {
-                if (options.collectFromThisFacetNormal(PolygonOps.areaNormalGo(visitor.point, workNormal))) {
-                    context.processPolygon(visitor.point.getArray(), (pointA, pointB) => {
-                        if (chainContext !== undefined)
-                            chainContext.addSegment(pointA, pointB);
-                        else
-                            result.push(LineSegment3d.create(pointA, pointB));
-                    });
+        const addSegment = chainContext ? (ptA, ptB) => chainContext.addSegment(ptA, ptB) : (ptA, ptB) => result.push(LineSegment3d.create(ptA, ptB));
+        const workNormal = Vector3d.createZero();
+        const visitor = source instanceof Polyface ? source.createVisitor(0) : source;
+        visitor.setNumWrap(0);
+        if (options.searcher && options.vectorToEye.isParallelTo(Vector3d.unitZ())) {
+            const searchRange = Range3d.createNull();
+            const workPoint0 = Point3d.createZero();
+            const workPoint1 = Point3d.createZero();
+            let edgeClipper;
+            const clipEdgeToConvexPolygon = (_facetRange, readIndex) => {
+                if (visitor.moveToReadIndex(readIndex) && (options.collectAll || options.collectFromThisFacetNormal(PolygonOps.areaNormalGo(visitor.point, workNormal))))
+                    edgeClipper?.processPolygon(visitor.point, (ptA, ptB) => addSegment(ptA, ptB));
+                return true;
+            };
+            for (let i = 1; i < points.length; i++) {
+                points.getPoint3dAtUncheckedPointIndex(i - 1, workPoint0);
+                points.getPoint3dAtUncheckedPointIndex(i, workPoint1);
+                if (edgeClipper = EdgeClipData.createPointPointSweep(workPoint0, workPoint1, options.vectorToEye)) {
+                    searchRange.setNull();
+                    searchRange.extend(workPoint0, workPoint1);
+                    options.searcher.searchRange2d(searchRange, clipEdgeToConvexPolygon);
                 }
             }
-            if (chainContext !== undefined) {
-                chainContext.clusterAndMergeVerticesXYZ();
-                result = chainContext.collectMaximalChains();
+        }
+        else {
+            const context = ClipSweptLineStringContext.create(points, options.vectorToEye);
+            if (context) {
+                for (visitor.reset(); visitor.moveToNextFacet();) {
+                    if (options.collectAll || options.collectFromThisFacetNormal(PolygonOps.areaNormalGo(visitor.point, workNormal)))
+                        context.processPolygon(visitor.point.getArray(), addSegment);
+                }
             }
         }
+        if (chainContext) {
+            chainContext.clusterAndMergeVerticesXYZ();
+            result = chainContext.collectMaximalChains();
+        }
         return result;
     }
     /**
      * 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.
-     * @example Using a 5x5 indexed search grid:
-     * ```
-     * const xyRange = Range2d.createFrom(myPolyface.range());
-     * const searcher = GriddedRaggedRange2dSetWithOverflow.create<number>(xyRange, 5, 5)!;
-     * for (const visitor = myPolyface.createVisitor(0); visitor.moveToNextFacet();) {
-     *   searcher.addRange(visitor.point.getRange(), visitor.currentReadIndex());
-     * }
-     * const drapedLineStrings = PolyfaceQuery.sweepLineStringToFacetsXY(lineString, myPolyface, searcher);
-     * ```
+     * @param points the linestring to drape onto the mesh.
+     * @param source target facet set. For best results, facets should be convex and planar.
+     * @param searcher object for searching facet 2D ranges tagged by mesh read index.
      * @returns the collected line strings.
+     * @see [[sweepLineStringToFacets]] for further options.
      */
-    static sweepLineStringToFacetsXY(lineStringPoints, polyfaceOrVisitor, searchByReadIndex) {
+    static sweepLineStringToFacetsXY(points, source, searcher) {
         const chainContext = ChainMergeContext.create();
-        const sweepVector = Vector3d.create(0, 0, 1);
+        const vectorToEye = Vector3d.unitZ();
         const searchRange = Range3d.create();
-        let visitor;
-        if (polyfaceOrVisitor instanceof Polyface)
-            visitor = polyfaceOrVisitor.createVisitor(0);
-        else
-            visitor = polyfaceOrVisitor;
-        let lineStringSource;
-        if (Array.isArray(lineStringPoints))
-            lineStringSource = new Point3dArrayCarrier(lineStringPoints);
-        else
-            lineStringSource = lineStringPoints;
+        const workPoint0 = Point3d.createZero();
+        const workPoint1 = Point3d.createZero();
+        const visitor = source instanceof Polyface ? source.createVisitor(0) : source;
+        visitor.setNumWrap(0);
+        let edgeClipper;
+        const clipEdgeToConvexPolygon = (_facetRange, readIndex) => {
+            if (visitor.moveToReadIndex(readIndex))
+                edgeClipper?.processPolygon(visitor.point, (ptA, ptB) => chainContext.addSegment(ptA, ptB));
+            return true;
+        };
+        const lineStringSource = Array.isArray(points) ? new Point3dArrayCarrier(points) : points;
         for (let i = 1; i < lineStringSource.length; i++) {
-            const point0 = lineStringSource.getPoint3dAtUncheckedPointIndex(i - 1);
-            const point1 = lineStringSource.getPoint3dAtUncheckedPointIndex(i);
-            const edgeClipper = EdgeClipData.createPointPointSweep(point0, point1, sweepVector);
-            if (edgeClipper !== undefined) {
-                Range3d.createNull(searchRange);
-                searchRange.extendPoint(point0);
-                searchRange.extendPoint(point1);
-                searchByReadIndex.searchRange2d(searchRange, (_facetRange, readIndex) => {
-                    if (visitor.moveToReadIndex(readIndex))
-                        edgeClipper.processPolygon(visitor.point, (pointA, pointB) => chainContext.addSegment(pointA, pointB));
-                    return true;
-                });
+            lineStringSource.getPoint3dAtUncheckedPointIndex(i - 1, workPoint0);
+            lineStringSource.getPoint3dAtUncheckedPointIndex(i, workPoint1);
+            if (edgeClipper = EdgeClipData.createPointPointSweep(workPoint0, workPoint1, vectorToEye)) {
+                searchRange.setNull();
+                searchRange.extend(workPoint0, workPoint1);
+                searcher.searchRange2d(searchRange, clipEdgeToConvexPolygon);
             }
         }
         chainContext.clusterAndMergeVerticesXYZ();
@@ -1259,24 +1347,20 @@ export class PolyfaceQuery {
       * * 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 [[PolyfaceQuery.sweepLineStringToFacets]] to get further options.
+      * @deprecated in 4.7.0 - will not be removed until after 2026-06-13. 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;
+        return PolyfaceQuery.sweepLineStringToFacets(linestringPoints, polyface, options);
     }
     /**
      * 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 [[PolyfaceQuery.sweepLineStringToFacets]] to get further options.
+     * * This calls [[sweepLineStringToFacets]] with default options.
+     * @deprecated in 4.7.0 - will not be removed until after 2026-06-13. 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;
+        return PolyfaceQuery.sweepLineStringToFacets(linestringPoints, polyface);
     }
     /**
      * Find segments (within the linestring) which project to facets.
@@ -1528,11 +1612,11 @@ export class PolyfaceQuery {
     static setEdgeVisibility(polyface, clusters, value) {
         for (const cluster of clusters) {
             if (cluster instanceof SortableEdge) {
-                this.setSingleEdgeVisibility(polyface, cluster.facetIndex, cluster.vertexIndexA, value);
+                this.setSingleEdgeVisibility(polyface, cluster.facetIndex, cluster.startVertex, value);
             }
             else if (Array.isArray(cluster)) {
                 for (const e1 of cluster)
-                    this.setSingleEdgeVisibility(polyface, e1.facetIndex, e1.vertexIndexA, value);
+                    this.setSingleEdgeVisibility(polyface, e1.facetIndex, e1.startVertex, value);
             }
         }
     }
@@ -1634,8 +1718,8 @@ export class PolyfaceQuery {
                         && undefined !== PolyfaceQuery.computeFacetUnitNormal(visitor, e1.facetIndex, normal1)) {
                         const edgeAngle = normal0.smallerUnorientedAngleTo(normal1);
                         if (edgeAngle.radians > sharpEdgeAngle.radians) {
-                            this.setSingleEdgeVisibility(mesh, e0.facetIndex, e0.vertexIndexA, true);
-                            this.setSingleEdgeVisibility(mesh, e1.facetIndex, e1.vertexIndexA, true);
+                            this.setSingleEdgeVisibility(mesh, e0.facetIndex, e0.startVertex, true);
+                            this.setSingleEdgeVisibility(mesh, e1.facetIndex, e1.startVertex, true);
                         }
                     }
                 }