@itwin/core-geometry 4.2.0-dev.3 → 4.2.0-dev.30

package/lib/esm/curve/{CurveCurveCloseApproachXY.js → internalContexts/CurveCurveCloseApproachXY.js}

@@ -5,32 +5,34 @@
 /** @packageDocumentation
  * @module Curve
  */
-import { BSplineCurve3d, BSplineCurve3dBase } from "../bspline/BSplineCurve";
-import { Geometry } from "../Geometry";
-import { NullGeometryHandler } from "../geometry3d/GeometryHandler";
-import { GrowableFloat64Array } from "../geometry3d/GrowableFloat64Array";
-import { Point3d, Vector3d } from "../geometry3d/Point3dVector3d";
-import { Range3d } from "../geometry3d/Range";
-import { AnalyticRoots, SmallSystem } from "../numerics/Polynomials";
-import { Arc3d } from "./Arc3d";
-import { CurveIntervalRole, CurveLocationDetail, CurveLocationDetailPair } from "./CurveLocationDetail";
-import { LineSegment3d } from "./LineSegment3d";
-import { LineString3d } from "./LineString3d";
+import { BSplineCurve3d, BSplineCurve3dBase } from "../../bspline/BSplineCurve";
+import { Geometry } from "../../Geometry";
+import { RecurseToCurvesGeometryHandler } from "../../geometry3d/GeometryHandler";
+import { GrowableFloat64Array } from "../../geometry3d/GrowableFloat64Array";
+import { Point3d, Vector3d } from "../../geometry3d/Point3dVector3d";
+import { Range3d } from "../../geometry3d/Range";
+import { AnalyticRoots, SmallSystem } from "../../numerics/Polynomials";
+import { Arc3d } from "../Arc3d";
+import { CurveCollection } from "../CurveCollection";
+import { CurveIntervalRole, CurveLocationDetail, CurveLocationDetailPair } from "../CurveLocationDetail";
+import { LineSegment3d } from "../LineSegment3d";
+import { LineString3d } from "../LineString3d";
 // cspell:word XYRR
 /**
  * Handler class for XY close approach between _geometryB and another geometry.
- * * Approach means the distance between _geometryB and another geometry.
- * * **NOTE:** GeometryQuery input (_geometryB) should really be AnyCurve.
+ * * Approach means the XY distance (z is ignored) between _geometryB and another geometry.
  * * Closest approach is a measure of the proximity of one curve to another. It's the length of the shortest line
  * segment perpendicular to both curves; if the curves intersect, the closest approach is zero. In the context of
  * this class, z-coordinates are ignored, so the closest approach is as seen in the top view. If you have coplanar
- * input curves, rotate them first into a plane parallel to the xy-plane, then afterward, you should rotate the
- * results back as required.
+ * input curves and want to find closest approach in their plane, rotate them first into a plane parallel to the
+ * xy-plane, then afterward, rotate the results back as required.
+ * * Close approach can also be from a curve endpoint perpendicular to another curve or from a curve endpoint to
+ * another curve endpoint.
  * * Instances are initialized and called from CurveCurve.
  * * geometryB is saved for later reference.
  * @internal
  */
-class CurveCurveCloseApproachXY extends NullGeometryHandler {
+class CurveCurveCloseApproachXY extends RecurseToCurvesGeometryHandler {
     setGeometryB(geometryB) {
         this._geometryB = geometryB;
         this._circularArcB = undefined;
@@ -56,13 +58,13 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         this._maxDistanceSquared = Geometry.smallMetricDistanceSquared;
         this.reinitialize();
     }
-    /** Set the (possibly undefined) max distance to accept. */
+    /** Set the (possibly undefined) max XY distance (z is ignored) to accept. */
     set maxDistanceToAccept(value) {
         this._maxDistanceToAccept = value;
         if (this._maxDistanceToAccept !== undefined && this._maxDistanceToAccept > 0)
             this._maxDistanceSquared = this._maxDistanceToAccept * this._maxDistanceToAccept;
     }
-    /** Access the (possibly undefined) max distance to accept. */
+    /** Access the (possibly undefined) max XY distance (z is ignored) to accept. */
     get maxDistanceToAccept() {
         return this._maxDistanceToAccept;
     }
@@ -74,7 +76,7 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
     resetGeometry(geometryB) {
         this.setGeometryB(geometryB);
     }
-    /** @returns whether the `fraction` is in [0,1] within tolerance */
+    /** returns true if `fraction` is in [0,1] within tolerance */
     acceptFraction(fraction, fractionTol = 1.0e-12) {
         if (fraction < -fractionTol)
             return false;
@@ -96,6 +98,10 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
     sameCurveAndFraction(cp, fraction, detail) {
         return cp === detail.curve && Geometry.isAlmostEqualNumber(fraction, detail.fraction);
     }
+    /**
+     * If distance between pointA and pointB is less than maxDistance, record CurveLocationDetailPair which is
+     * the approach from pointA to pointB.
+     */
     testAndRecordPointPairApproach(cpA, fA, pointA, cpB, fB, pointB, reversed) {
         const d2 = pointA.distanceSquaredXY(pointB);
         if (d2 < this._maxDistanceSquared) {
@@ -108,16 +114,24 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         }
     }
     /**
-     * Compute intersection of two line segments.
-     * Filter by extension rules.
-     * Record with fraction mapping.
+     * Create a close approach pair if XY distance is within maxDistance.
+     * @param localFractionA a fraction on first curve
+     * @param cpA the first curve
+     * @param fractionA0 start of the first curve
+     * @param fractionA1 end of the first curve
+     * @param localFractionB a fraction on second curve
+     * @param cpB the second curve
+     * @param fractionB0 start of the second curve
+     * @param fractionB1 end of the second curve
+     * @param reversed true to have order reversed in final structures
+     * @param intervalDetails optional CurveLocationDetailPair
      */
-    recordPointWithLocalFractions(localFractionA, cpA, fractionA0, fractionA1, localFractionB, // Computed intersection fraction
-    cpB, fractionB0, fractionB1, reversed, intervalDetails) {
+    recordPointWithLocalFractions(localFractionA, cpA, fractionA0, fractionA1, localFractionB, cpB, fractionB0, fractionB1, reversed, intervalDetails) {
         let globalFractionA, globalFractionB;
         let globalFractionA1, globalFractionB1;
-        const isInterval = (intervalDetails !== undefined) &&
-            intervalDetails.detailA.hasFraction1 && intervalDetails.detailB.hasFraction1;
+        const isInterval = intervalDetails !== undefined &&
+            intervalDetails.detailA.hasFraction1 &&
+            intervalDetails.detailB.hasFraction1;
         if (isInterval) {
             globalFractionA = Geometry.interpolate(fractionA0, intervalDetails.detailA.fraction, fractionA1);
             globalFractionB = Geometry.interpolate(fractionB0, intervalDetails.detailB.fraction, fractionB1);
@@ -128,7 +142,7 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             globalFractionA = globalFractionA1 = Geometry.interpolate(fractionA0, localFractionA, fractionA1);
             globalFractionB = globalFractionB1 = Geometry.interpolate(fractionB0, localFractionB, fractionB1);
         }
-        // ignore duplicate of most recent point .  ..
+        // ignore duplicate of most recent approach
         const numPrevious = this._results.length;
         if (numPrevious > 0 && !isInterval) {
             const oldDetailA = this._results[numPrevious - 1].detailA;
@@ -151,6 +165,9 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             detailB.captureFraction1Point1(globalFractionB1, cpB.fractionToPoint(globalFractionB1));
         }
         else {
+            const d2 = detailA.point.distanceSquaredXY(detailB.point);
+            if (d2 > this._maxDistanceSquared)
+                return;
             detailA.setIntervalRole(CurveIntervalRole.isolated);
             detailB.setIntervalRole(CurveIntervalRole.isolated);
         }
@@ -163,12 +180,21 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
     }
     /**
      * Capture a close approach pair that has point and local fraction but not curve.
-     * Record with fraction mapping.
+     * * Record the pair, each detail modified with global fraction and input curve.
+     * * Pair is neither modified nor recorded if it would be a duplicate of the last recorded pair.
+     * @param pair details computed with local fractions
+     * @param cpA curveA
+     * @param fractionA0 global start fraction on curveA
+     * @param fractionA1 global end fraction on curveA
+     * @param cpB curveB
+     * @param fractionB0 global start fraction on curveB
+     * @param fractionB1 global end fraction on curveB
+     * @param reversed whether to reverse the details in the pair
      */
     capturePairWithLocalFractions(pair, cpA, fractionA0, fractionA1, cpB, fractionB0, fractionB1, reversed) {
         const globalFractionA = Geometry.interpolate(fractionA0, pair.detailA.fraction, fractionA1);
         const globalFractionB = Geometry.interpolate(fractionB0, pair.detailB.fraction, fractionB1);
-        // ignore duplicate of most recent point .  ..
+        // ignore duplicate of most recent pair
         const numPrevious = this._results.length;
         if (numPrevious > 0) {
             const oldDetailA = this._results[numPrevious - 1].detailA;
@@ -184,18 +210,17 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
                     return;
             }
         }
+        if (reversed)
+            pair.swapDetails();
+        // recompute the points just in case
+        CurveLocationDetail.createCurveEvaluatedFraction(cpA, globalFractionA, pair.detailA);
+        CurveLocationDetail.createCurveEvaluatedFraction(cpB, globalFractionB, pair.detailB);
         pair.detailA.setIntervalRole(CurveIntervalRole.isolated);
         pair.detailB.setIntervalRole(CurveIntervalRole.isolated);
-        if (reversed) {
-            this._results.push(pair);
-        }
-        else {
-            pair.swapDetails();
-            this._results.push(pair);
-        }
+        this._results.push(pair);
     }
     /**
-     * Emit recordPoint for multiple pairs (on full curve!)
+     * Emit recordPoint for multiple pairs (on full curve) if within maxDistance.
      * @param cpA first curve primitive (possibly different from curve in detailA, but fraction compatible)
      * @param cpB second curve primitive (possibly different from curve in detailA, but fraction compatible)
      * @param pairs array of pairs
@@ -217,44 +242,40 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
     captureDetailPair(detailA, detailB, reversed) {
         if (detailA && detailB) {
             if (reversed) {
-                this._results.push(CurveLocationDetailPair.createCapture(detailA, detailB));
+                this._results.push(CurveLocationDetailPair.createCapture(detailB, detailA));
             }
             else {
-                this._results.push(CurveLocationDetailPair.createCapture(detailB, detailA));
+                this._results.push(CurveLocationDetailPair.createCapture(detailA, detailB));
             }
         }
     }
-    static updatePointToSegmentDistance(fractionA, pointA, pointB0, pointB1, fractionB, minDistanceSquared, closestApproach) {
+    static updatePointToSegmentDistance(fractionA, pointA, pointB0, pointB1, fractionB, maxDistanceSquared, closestApproach) {
+        let updated = false;
         if (fractionB < 0)
             fractionB = 0;
         else if (fractionB > 1)
             fractionB = 1;
         this._workPointB = pointB0.interpolate(fractionB, pointB1, this._workPointB);
         const distanceSquared = this._workPointB.distanceSquaredXY(pointA);
-        if (distanceSquared < minDistanceSquared) {
-            if (closestApproach === undefined || distanceSquared < closestApproach.detailA.a) {
-                if (closestApproach === undefined)
-                    closestApproach = CurveLocationDetailPair.createCapture(CurveLocationDetail.create(), CurveLocationDetail.create());
-                closestApproach.detailA.setFP(fractionA, pointA);
-                closestApproach.detailA.a = distanceSquared;
-                closestApproach.detailB.setFP(fractionB, this._workPointB);
-                closestApproach.detailA.a = distanceSquared;
-            }
+        if (distanceSquared <= Math.min(maxDistanceSquared, closestApproach.detailA.a)) {
+            closestApproach.detailA.setFP(fractionA, pointA, undefined, distanceSquared);
+            closestApproach.detailB.setFP(fractionB, this._workPointB, undefined, distanceSquared);
+            updated = true;
         }
-        return closestApproach;
+        return updated;
     }
     /**
-     * Return fractions of close approach within minDistance between two line segments (a0,a1) and (b0, b1).
-     * * minDistanceSquared is assumed positive.
-     * Return the fractional (not xy) coordinates in result.x, result.y
+     * Return fractions of close approach within maxDistance between two line segments (a0,a1) and (b0,b1).
+     * * Math details can be found at docs/learning/geometry/CurveCurve.md
      * @param a0 start point of line a
-     * @param a1  end point of line a
-     * @param b0  start point of line b
+     * @param a1 end point of line a
+     * @param b0 start point of line b
      * @param b1 end point of line b
-     * @param result point to receive fractional coordinates of intersection. result.x is fraction on line a.
+     * @param maxDistanceSquared maximum distance squared (assumed to be positive)
+     * @returns the fractional (not xy) coordinates in result.x and result.y. result.x is fraction on line a.
      * result.y is fraction on line b.
      */
-    static segmentSegmentBoundedApproach(a0, a1, b0, b1, minDistanceSquared) {
+    static segmentSegmentBoundedApproach(a0, a1, b0, b1, maxDistanceSquared) {
         const ux = a1.x - a0.x;
         const uy = a1.y - a0.y;
         const vx = b1.x - b0.x;
@@ -265,31 +286,61 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         const e01y = b1.y - a0.y;
         const e10x = b0.x - a1.x;
         const e10y = b0.y - a1.y;
-        const e11x = b1.x - a1.x;
-        const e11y = b1.y - a1.y;
         const hab0 = Geometry.crossProductXYXY(ux, uy, e00x, e00y);
         const hab1 = Geometry.crossProductXYXY(ux, uy, e01x, e01y);
         const hba0 = -Geometry.crossProductXYXY(vx, vy, e00x, e00y);
-        const hba1 = -Geometry.crossProductXYXY(vx, vy, e11x, e11y);
-        if (hab0 * hab1 < 0.0 && hba0 * hba1 < 0.0) {
-            // true intersection, strictly within both segments !!!
+        const hba1 = -Geometry.crossProductXYXY(vx, vy, e10x, e10y);
+        if (hab0 * hab1 < 0.0 && hba0 * hba1 < 0.0) { // true intersection, strictly within both segments
             const fractionA = -hba0 / (hba1 - hba0);
             const fractionB = -hab0 / (hab1 - hab0);
             return CurveLocationDetailPair.createCapture(CurveLocationDetail.createCurveFractionPoint(undefined, fractionA, a0.interpolate(fractionA, a1)), CurveLocationDetail.createCurveFractionPoint(undefined, fractionB, b0.interpolate(fractionB, b1)));
         }
-        let closestApproach;
+        // there's no intersection, so find the closest approach within maxDistance from an endpoint
+        const closestApproach = new CurveLocationDetailPair();
+        closestApproach.detailA.a = 2 * maxDistanceSquared; // init to an approach that's too far away
+        let reversed = false;
         const uu = Geometry.hypotenuseSquaredXY(ux, uy);
-        if (hab0 * hab0 < minDistanceSquared * uu)
-            closestApproach = this.updatePointToSegmentDistance(0, b0, a0, a1, Geometry.dotProductXYXY(ux, uy, e00x, e00y) / uu, minDistanceSquared, closestApproach);
-        if (hab1 * hab1 < minDistanceSquared * uu)
-            closestApproach = this.updatePointToSegmentDistance(1, b1, a0, a1, Geometry.dotProductXYXY(ux, uy, e01x, e01y) / uu, minDistanceSquared, closestApproach);
+        if (hab0 * hab0 <= maxDistanceSquared * uu) { // test distance of b0 to u
+            const fractionA = Geometry.dotProductXYXY(ux, uy, e00x, e00y) / uu;
+            if (this.updatePointToSegmentDistance(0, b0, a0, a1, fractionA, maxDistanceSquared, closestApproach))
+                reversed = true;
+        }
+        if (hab1 * hab1 <= maxDistanceSquared * uu) { // test distance of b1 to u
+            const fractionA = Geometry.dotProductXYXY(ux, uy, e01x, e01y) / uu;
+            if (this.updatePointToSegmentDistance(1, b1, a0, a1, fractionA, maxDistanceSquared, closestApproach))
+                reversed = true;
+        }
         const vv = Geometry.hypotenuseSquaredXY(vx, vy);
-        if (hba0 * hba0 < minDistanceSquared * vv)
-            closestApproach = this.updatePointToSegmentDistance(0, a0, b0, b1, -Geometry.dotProductXYXY(vx, vy, e00x, e00y) / vv, minDistanceSquared, closestApproach);
-        if (hba1 * hba1 < minDistanceSquared * vv)
-            closestApproach = this.updatePointToSegmentDistance(1, a1, b0, b1, -Geometry.dotProductXYXY(vx, vy, e10x, e10y) / vv, minDistanceSquared, closestApproach);
+        if (hba0 * hba0 <= maxDistanceSquared * vv) { // test distance of a0 to v
+            const fractionB = -Geometry.dotProductXYXY(vx, vy, e00x, e00y) / vv;
+            if (this.updatePointToSegmentDistance(0, a0, b0, b1, fractionB, maxDistanceSquared, closestApproach))
+                reversed = false;
+        }
+        if (hba1 * hba1 <= maxDistanceSquared * vv) { // test distance of a1 to v
+            const fractionB = -Geometry.dotProductXYXY(vx, vy, e10x, e10y) / vv;
+            if (this.updatePointToSegmentDistance(1, a1, b0, b1, fractionB, maxDistanceSquared, closestApproach))
+                reversed = false;
+        }
+        if (closestApproach.detailA.a > maxDistanceSquared)
+            return undefined;
+        if (reversed)
+            closestApproach.swapDetails();
         return closestApproach;
     }
+    /**
+     * Check different combination of fractions on curveA and curveB. If distance between points at 2 fractions
+     * is less than maxDistance, record CurveLocationDetailPair which is the approach between the 2 points.
+     * Optionally, record close approaches of one curve's points if they fall between the other curve's points.
+     * @param cpA curveA
+     * @param fA0 fraction0 on curveA
+     * @param fA1 fraction1 on curveA
+     * @param testProjectionOnA whether to record projections of the given curveB points onto curveA
+     * @param cpB curveB
+     * @param fB0 fraction0 on curveB
+     * @param fB1 fraction0 on curveB
+     * @param testProjectionOnB whether to record projections of the given curveA points onto curveB
+     * @param reversed true to have order reversed in final structures.
+     */
     testAndRecordFractionalPairApproach(cpA, fA0, fA1, testProjectionOnA, cpB, fB0, fB1, testProjectionOnB, reversed) {
         const pointA0 = cpA.fractionToPoint(fA0);
         const pointA1 = cpA.fractionToPoint(fA1);
@@ -308,12 +359,13 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             this.testAndRecordProjection(cpB, fB1, pointB1, cpA, fA0, fA1, !reversed);
         }
     }
+    /** Find the closest approach between pointA and cpB. Add the approach if it's within fB0 and fB1. */
     testAndRecordProjection(cpA, fA, pointA, cpB, fB0, fB1, reversed) {
         // NO NO NO -- this is 3D closest point --- need 2d !!
         const detail = cpB.closestPoint(pointA, false);
         if (detail) {
             const fB = Geometry.restrictToInterval(detail.fraction, fB0, fB1);
-            if (fB === detail.fraction) {
+            if (fB === detail.fraction) { // if fraction is within fB0 and fB1
                 this.testAndRecordPointPairApproach(cpA, fA, pointA, cpB, detail.fraction, detail.point, reversed);
             }
         }
@@ -325,53 +377,73 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
      * * The fraction mappings allow portions of a linestring to be passed here.
      */
     computeSegmentSegment3D(cpA, pointA0, fractionA0, pointA1, fractionA1, cpB, pointB0, fractionB0, pointB1, fractionB1, reversed) {
+        // compute a pair with fractions local to segments
         const approach = CurveCurveCloseApproachXY.segmentSegmentBoundedApproach(pointA0, pointA1, pointB0, pointB1, this._maxDistanceSquared);
-        if (approach)
+        // adjust the pair to refer to input curves and global fractions, then record it if new
+        if (approach) {
+            approach.detailA.setCurve(cpA);
+            approach.detailB.setCurve(cpB);
             this.capturePairWithLocalFractions(approach, cpA, fractionA0, fractionA1, cpB, fractionB0, fractionB1, reversed);
+        }
     }
-    // Caller accesses data from a line segment and passes to here.
-    // (The line segment in question might be (a) a full line segment or (b) a fragment within a linestring.
-    // The fraction and extend parameters allow all combinations to be passed in)
-    // This method applies transform.
+    /** Low level dispatch of segment with segment. */
     dispatchSegmentSegment(cpA, pointA0, fractionA0, pointA1, fractionA1, cpB, pointB0, fractionB0, pointB1, fractionB1, reversed) {
         this.computeSegmentSegment3D(cpA, pointA0, fractionA0, pointA1, fractionA1, cpB, pointB0, fractionB0, pointB1, fractionB1, reversed);
     }
-    // Caller accesses data from a linestring or segment and passes it here.
-    // (The line segment in question might be (a) a full line segment or (b) a fragment within a linestring.
-    // The fraction and extend parameters allow all combinations to be passed in)
+    /**
+     * Low level dispatch of segment with arc.
+     * Find close approaches within maxDistance between a line segments (pointA0, pointA1) and an arc.
+     * To consider:
+     * 1) intersection between arc and segment.
+     * 2) arc endpoints to segment endpoints or arc endpoints projection to the segment.
+     * 3) line parallel to arc tangent.
+     * @param cpA curve A (line segment or line string)
+     * @param pointA0 start point of the segment
+     * @param fractionA0 fraction of the start of the segment
+     * @param pointA1 end point of the segment
+     * @param fractionA1 fraction of the end of the segment
+     * @param arc the arc
+     * @param reversed true to have order reversed in final structures
+     */
     dispatchSegmentArc(cpA, pointA0, fractionA0, pointA1, fractionA1, arc, reversed) {
-        // To consider:
-        // 1) endpoint to endpoint or projection
-        // 2) true intersection
-        // 3) line parallel to arc tangent.
-        this.testAndRecordFractionalPairApproach(cpA, 0, 1, true, arc, 0, 1, false, reversed);
-        // Arc: X = C + cU + sV
-        // Line:  contains points A0,A1
-        // Arc point colinear with line if det (A0, A1, X) = 0
-        // with homogeneous xyw points and vectors.
-        // With equational X:   det (A0, A1, C) + c det (A0, A1,U) + s det (A0, A1, V) = 0.
+        // 1) intersection between arc and segment
+        // Suppose:
+        // Arc: X = C + cU + sV where c = cos(theta) and s = sin(theta)
+        // Line: contains points A0 and A1
+        // The arc intersects the line at point X if det(A0, A1, X) = 0 with homogeneous xyw points and vectors.
+        // With equational X:  det(A0, A1, C) + c*det(A0, A1, U) + s*det(A0, A1, V) = 0.
         // solve for theta.
         // evaluate points.
         // project back to line.
+        let intersectionFound = false;
         const data = arc.toTransformedVectors();
         const pointA0Local = pointA0;
         const pointA1Local = pointA1;
-        const alpha = Geometry.tripleProductXYW(pointA0Local, 1, pointA1Local, 1, data.center, 1);
-        const beta = Geometry.tripleProductXYW(pointA0Local, 1, pointA1Local, 1, data.vector0, 0);
-        const gamma = Geometry.tripleProductXYW(pointA0Local, 1, pointA1Local, 1, data.vector90, 0);
+        const alpha = Geometry.tripleProductXYW(pointA0Local, 1, pointA1Local, 1, data.center, 1); //  det(A0, A1, C)
+        const beta = Geometry.tripleProductXYW(pointA0Local, 1, pointA1Local, 1, data.vector0, 0); // det(A0, A1, U)
+        const gamma = Geometry.tripleProductXYW(pointA0Local, 1, pointA1Local, 1, data.vector90, 0); // det(A0, A1, V)
         const cosines = new GrowableFloat64Array(2);
         const sines = new GrowableFloat64Array(2);
         const radians = new GrowableFloat64Array(2);
-        const numRoots = AnalyticRoots.appendImplicitLineUnitCircleIntersections(alpha, beta, gamma, cosines, sines, radians);
+        const numRoots = AnalyticRoots.appendImplicitLineUnitCircleIntersections(// solve the equation
+        alpha, beta, gamma, cosines, sines, radians);
         for (let i = 0; i < numRoots; i++) {
             const arcPoint = data.center.plus2Scaled(data.vector0, cosines.atUncheckedIndex(i), data.vector90, sines.atUncheckedIndex(i));
             const arcFraction = data.sweep.radiansToSignedPeriodicFraction(radians.atUncheckedIndex(i));
             const lineFraction = SmallSystem.lineSegment3dXYClosestPointUnbounded(pointA0Local, pointA1Local, arcPoint);
+            // only add if the point is within the start and end fractions of both line segment and arc
             if (lineFraction !== undefined && this.acceptFraction(lineFraction) && this.acceptFraction(arcFraction)) {
                 this.recordPointWithLocalFractions(lineFraction, cpA, fractionA0, fractionA1, arcFraction, arc, 0, 1, reversed);
+                intersectionFound = true;
             }
         }
-        // line parallel to arc tangent.
+        if (intersectionFound)
+            return;
+        // 2) endpoints to endpoints or endpoints projection to the other curve
+        this.testAndRecordFractionalPairApproach(cpA, fractionA0, fractionA1, true, arc, 0, 1, false, reversed);
+        // 3) line parallel to arc tangent.
+        // If line does not intersect the arc, then the closest (and/or the furthest) point on arc to the line is a
+        // point where the tangent line on arc at that point is parallel to the line.
         const dotUT = data.vector0.crossProductStartEndXY(pointA0, pointA1);
         const dotVT = data.vector90.crossProductStartEndXY(pointA0, pointA1);
         const parallelRadians = Math.atan2(dotVT, dotUT);
@@ -379,53 +451,43 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             const arcPoint = data.center.plus2Scaled(data.vector0, Math.cos(radians1), data.vector90, Math.sin(radians1));
             const arcFraction = data.sweep.radiansToSignedPeriodicFraction(radians1);
             const lineFraction = SmallSystem.lineSegment3dXYClosestPointUnbounded(pointA0Local, pointA1Local, arcPoint);
+            // only add if the point is within the start and end fractions of both line segment and arc
             if (lineFraction !== undefined && this.acceptFraction(lineFraction) && this.acceptFraction(arcFraction)) {
                 this.recordPointWithLocalFractions(lineFraction, cpA, fractionA0, fractionA1, arcFraction, arc, 0, 1, reversed);
             }
         }
     }
-    // Caller accesses data from two arcs, ensures circular, and orders with radiusA >= radiusB
+    /** Low level dispatch of circular arc with circular arc. radiusA must be larger than or equal to radiusB. */
     dispatchCircularCircularOrdered(cpA, radiusA, cpB, radiusB, reversed) {
         const c = cpA.center.distance(cpB.center);
         const e = this._maxDistanceToAccept !== undefined ? this._maxDistanceToAccept : Geometry.smallMetricDistance;
-        if (c > radiusA + radiusB + e) // widely separated
+        if (c > radiusA + radiusB + e) // distance between circles is more than max distance
             return;
-        // To consider:
-        // 1) endpoint to endpoint or projection
-        // 2) true intersection
-        // 3) line parallel to arc tangent.
+        // TODO: 1) intersection between arcs
+        // 2) endpoints to endpoints
         this.testAndRecordFractionalPairApproach(cpA, 0, 1, false, cpB, 0, 1, false, reversed);
+        // 3) line from one arc to another (perpendicular to arc tangents along center-center line)
         if (!Geometry.isSmallMetricDistance(c)) {
-            // ?? endpoint hits are recorded.  Maybe also need overlap?
             const vectorAB = Vector3d.createStartEnd(cpA.center, cpB.center);
             vectorAB.scaleInPlace(1.0 / c);
-            if (c - radiusA - radiusB > e) {
-                // no approaches possible
-            }
-            else {
-                for (const rA of [-radiusA, radiusA]) {
-                    for (const rB of [-radiusB, radiusB]) {
-                        const tangentDistance = c - rA + rB;
-                        if (tangentDistance < e) {
-                            const detailA = this.resolveDirectionToArcXYFraction(cpA, vectorAB, rA);
-                            if (detailA) {
-                                const detailB = this.resolveDirectionToArcXYFraction(cpB, vectorAB, rB);
-                                if (detailB) {
-                                    this.captureDetailPair(detailA, detailB, reversed);
-                                }
-                            }
+            for (const rA of [-radiusA, radiusA]) {
+                for (const rB of [-radiusB, radiusB]) {
+                    const tangentDistance = c - rA + rB;
+                    if (tangentDistance < e) {
+                        const detailA = this.resolveDirectionToArcXYFraction(cpA, vectorAB, rA);
+                        if (detailA) {
+                            const detailB = this.resolveDirectionToArcXYFraction(cpB, vectorAB, rB);
+                            if (detailB)
+                                this.captureDetailPair(detailA, detailB, reversed);
                         }
                     }
                 }
             }
         }
     }
-    /**
-     * Find the fractional point (if any) on an arc, known to be circular and displayed from the center in the
-     * direction of a scaled vector.
-     */
+    /** Find the fractional point (if any) on the circular `arc` in the direction of `radialVector`. */
     resolveDirectionToArcXYFraction(arc, radialVector, scale) {
-        // The scale ultimately only affects the direction --- easiest way to use it is two multiplies
+        // The scale ultimately only affects the direction --- easiest way to use it is two multiplies.
         const c = scale * arc.matrixRef.columnDotXYZ(0, radialVector.x, radialVector.y, 0);
         const s = scale * arc.matrixRef.columnDotXYZ(1, radialVector.x, radialVector.y, 0);
         const radians = Math.atan2(s, c);
@@ -434,10 +496,13 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             return CurveLocationDetail.createCurveEvaluatedFraction(arc, fraction);
         return undefined;
     }
-    // Caller accesses data from two arcs.
-    // Selects the best conditioned arc (in xy parts) as "circle after inversion"
-    // Solves the arc-arc equations
+    /** Low level dispatch of arc with arc. Only circular arcs are supported. */
     dispatchArcArc(cpA, cpB, reversed) {
+        const rangeA = cpA.range();
+        const rangeB = cpB.range();
+        rangeA.expandInPlace(this._maxDistanceToAccept);
+        if (!rangeB.intersectsRangeXY(rangeA))
+            return;
         if (this._circularArcB) {
             const radiusB = this._circularRadiusB;
             const radiusA = cpA.circularRadiusXY();
@@ -450,17 +515,13 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             }
         }
     }
-    // Caller accesses data from two arcs.
-    // Selects the best conditioned arc (in xy parts) as "circle after inversion"
-    // Solves the arc-arc equations
+    /** Low level dispatch of arc with (beziers of) a bspline curve */
     dispatchArcBsplineCurve3d(cpA, cpB, reversed) {
         const ls = LineString3d.create();
         cpB.emitStrokes(ls);
         this.computeArcLineString(cpA, ls, reversed);
     }
-    // Caller accesses data from two arcs.
-    // Selects the best conditioned arc (in xy parts) as "circle after inversion"
-    // Solves the arc-arc equations
+    /** Low level dispatch of (beziers of) a bspline curve with (beziers of) a bspline curve */
     dispatchBSplineCurve3dBSplineCurve3d(bcurveA, bcurveB, reversed) {
         const lsA = LineString3d.create();
         bcurveA.emitStrokes(lsA);
@@ -475,66 +536,34 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         this.computeLineStringLineString(lsA, lsB, reversed);
     }
     /** Low level dispatch of segment with (beziers of) a bspline curve */
-    dispatchSegmentBsplineCurve(lsA, curveB, reversed) {
+    dispatchSegmentBsplineCurve(segA, curveB, reversed) {
         const lsB = LineString3d.create();
         curveB.emitStrokes(lsB);
-        this.computeSegmentLineString(lsA, lsB, reversed);
+        this.computeSegmentLineString(segA, lsB, reversed);
     }
     /** Detail computation for segment approaching linestring. */
-    computeSegmentLineString(lsA, lsB, reversed) {
-        const pointA0 = lsA.point0Ref;
-        const pointA1 = lsA.point1Ref;
-        let pointB0 = CurveCurveCloseApproachXY._workPointBB0;
-        let pointB1 = CurveCurveCloseApproachXY._workPointBB1;
-        let pointB2 = CurveCurveCloseApproachXY._workPointBB2;
-        let cross0, cross1, cross2;
-        let dot0, dot1, dot2;
-        const vectorA = CurveCurveCloseApproachXY._workVectorA;
-        Vector3d.createStartEnd(pointA0, pointA1, vectorA);
-        const aa = vectorA.magnitudeSquared();
+    computeSegmentLineString(segA, lsB, reversed) {
         const numB = lsB.numPoints();
-        lsB.packedPoints.getPoint3dAtUncheckedPointIndex(0, pointB0);
-        lsB.packedPoints.getPoint3dAtUncheckedPointIndex(1, pointB0);
-        cross0 = vectorA.crossProductStartEndXY(pointA0, pointB0);
-        cross1 = vectorA.crossProductStartEndXY(pointA0, pointB0);
-        dot0 = vectorA.dotProductStartEndXY(pointA0, pointB0);
-        dot1 = vectorA.dotProductStartEndXY(pointA0, pointB1);
-        for (let iB = 2; iB < numB; iB++) {
-            // project point B[iB] to segmentA.  If within limits, see if it is a local minimum distance . . .
-            lsB.packedPoints.getPoint3dAtUncheckedPointIndex(iB, pointB1);
-            cross2 = vectorA.crossProductStartEndXY(pointA0, pointB0);
-            dot2 = vectorA.dotProductStartEndXY(pointA0, pointB2);
-            if ((cross0 - cross1) * (cross2 - cross1) <= 0.0) {
-                // There is a true minimum at point1 ... see if it is within the line
-                if (dot1 >= 0.0 && dot1 <= aa) {
-                    const fractionA1 = dot1 / aa;
-                    const projection = pointA0.interpolate(dot1 / aa, pointA1);
-                    if (pointB1.distanceXY(projection) < this._maxDistanceToAccept) {
-                        const detailA = CurveLocationDetail.createCurveFractionPoint(lsA, fractionA1, projection);
-                        const detailB = CurveLocationDetail.createCurveFractionPoint(lsB, iB / (numB - 1), pointB2);
-                        const pair = CurveLocationDetailPair.createCaptureOptionalReverse(detailA, detailB, reversed);
-                        this._results.push(pair);
-                    }
-                }
-            }
-            const tempPoint = pointB0;
-            pointB0 = pointB1;
-            pointB1 = pointB2;
-            pointB2 = tempPoint;
-            const tempCross = cross0;
-            cross0 = cross1;
-            cross1 = cross2;
-            cross2 = tempCross;
-            const tempDot = dot0;
-            dot0 = dot1;
-            dot1 = dot2;
-            dot2 = tempDot;
-        }
-        this.testAndRecordFractionalPairApproach(lsA, 0, 1, true, lsB, 0, 1, false, reversed);
-        return undefined;
+        const deltaFracB = Geometry.safeDivideFraction(1, numB - 1, 0);
+        const pointA0 = segA.point0Ref;
+        const pointA1 = segA.point1Ref;
+        const pointB0 = CurveCurveCloseApproachXY._workPointBB0;
+        const pointB1 = CurveCurveCloseApproachXY._workPointBB1;
+        for (let i = 0; i < numB - 1; ++i) {
+            const fB0 = i * deltaFracB; // global linestring fractions
+            const fB1 = (i + 1 === numB - 1) ? 1.0 : (i + 1) * deltaFracB; // make sure we nail the end fraction
+            lsB.packedPoints.getPoint3dAtUncheckedPointIndex(i, pointB0);
+            lsB.packedPoints.getPoint3dAtUncheckedPointIndex(i + 1, pointB1);
+            this.dispatchSegmentSegment(segA, pointA0, 0.0, pointA1, 1.0, lsB, pointB0, fB0, pointB1, fB1, reversed);
+        }
     }
     /** Detail computation for arc approaching linestring. */
     computeArcLineString(arcA, lsB, reversed) {
+        const rangeA = arcA.range();
+        const rangeB = lsB.range();
+        rangeA.expandInPlace(this._maxDistanceToAccept);
+        if (!rangeB.intersectsRangeXY(rangeA))
+            return;
         const pointB0 = CurveCurveCloseApproachXY._workPointBB0;
         const pointB1 = CurveCurveCloseApproachXY._workPointBB1;
         const numB = lsB.numPoints();
@@ -552,6 +581,17 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         }
         return undefined;
     }
+    /** Low level dispatch of curve collection. */
+    dispatchCurveCollection(geomA, geomAHandler) {
+        const geomB = this._geometryB; // save
+        if (!geomB || !geomB.children || !(geomB instanceof CurveCollection))
+            return;
+        for (const child of geomB.children) {
+            this.resetGeometry(child);
+            geomAHandler(geomA);
+        }
+        this._geometryB = geomB; // restore
+    }
     /** Double dispatch handler for strongly typed segment. */
     handleLineSegment3d(segmentA) {
         if (this._geometryB instanceof LineSegment3d) {
@@ -567,6 +607,10 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         else if (this._geometryB instanceof BSplineCurve3d) {
             this.dispatchSegmentBsplineCurve(segmentA, this._geometryB, false);
         }
+        else if (this._geometryB instanceof CurveCollection) {
+            this.dispatchCurveCollection(segmentA, this.handleLineSegment3d.bind(this));
+        }
+        return undefined;
     }
     /**
      * Set bits for comparison to range xy
@@ -574,6 +618,13 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
      * * bit 0x02 => x larger than range.high.x
      * * bit 0x04 => y smaller than range.low.y
      * * bit 0x08 => y larger than range.high.y
+     * * If we divide XY plane into 9 areas using the range, the function returns 0 for points
+     * inside the range. Below is other binary numbers returned by the function for all 9 areas:
+     *   1001 | 1000 | 1010
+     *   ------------------
+     *    1   |  0   |  10
+     *   ------------------
+     *   101  | 100  | 110
      * @param xy point to test
      * @param range range for comparison
      */
@@ -583,12 +634,14 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
             result = 0x01;
         else if (x > range.high.x)
             result = 0x02;
+        // note the OR operation
         if (y < range.low.y)
             result |= 0x04;
         else if (y > range.high.y)
             result |= 0x08;
         return result;
     }
+    /** Low level dispatch of line string with line string. */
     computeLineStringLineString(lsA, lsB, reversed) {
         const rangeA = lsA.range();
         const rangeB = lsB.range();
@@ -605,7 +658,6 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         const numA = lsA.numPoints();
         const numB = lsB.numPoints();
         if (numA > 1 && numB > 1) {
-            lsA.pointAt(0, pointA0);
             const dfA = 1.0 / (numA - 1);
             const dfB = 1.0 / (numB - 1);
             let fA0 = 0.0;
@@ -615,6 +667,7 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
                 fA1 = ia * dfA;
                 fB0 = 0.0;
                 lsA.pointAt(ia, pointA1);
+                // rangeA1 is around line segment [A0,A1] expanded by max distance
                 rangeA1.setNull();
                 rangeA1.extendPoint(pointA0);
                 rangeA1.extendPoint(pointA1);
@@ -626,10 +679,10 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
                         lsB.pointAt(ib, pointB1);
                         bitB1 = this.classifyBitsPointRangeXY(pointB1.x, pointB1.y, rangeA1);
                         fB1 = ib * dfB;
-                        // Do NOT study the segment in detail if both bitB bits are on for any of the 4 planes . ..
-                        if ((bitB0 & bitB1) === 0) {
+                        // DO NOT study the segment in detail if both bitB bits are on for any of the 4 planes
+                        // (i.e., no intersection between rangeA1 and the range around line segment [B0,B1])
+                        if ((bitB0 & bitB1) === 0)
                             this.dispatchSegmentSegment(lsA, pointA0, fA0, pointA1, fA1, lsB, pointB0, fB0, pointB1, fB1, reversed);
-                        }
                     }
                 }
             }
@@ -650,6 +703,9 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         else if (this._geometryB instanceof BSplineCurve3d) {
             this.dispatchLineStringBSplineCurve(lsA, this._geometryB, false);
         }
+        else if (this._geometryB instanceof CurveCollection) {
+            this.dispatchCurveCollection(lsA, this.handleLineString3d.bind(this));
+        }
         return undefined;
     }
     /** Double dispatch handler for strongly typed arc. */
@@ -666,6 +722,9 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         else if (this._geometryB instanceof BSplineCurve3d) {
             this.dispatchArcBsplineCurve3d(arc0, this._geometryB, false);
         }
+        else if (this._geometryB instanceof CurveCollection) {
+            this.dispatchCurveCollection(arc0, this.handleArc3d.bind(this));
+        }
         return undefined;
     }
     /** Double dispatch handler for strongly typed bspline curve. */
@@ -682,6 +741,9 @@ class CurveCurveCloseApproachXY extends NullGeometryHandler {
         else if (this._geometryB instanceof BSplineCurve3dBase) {
             this.dispatchBSplineCurve3dBSplineCurve3d(curve, this._geometryB, false);
         }
+        else if (this._geometryB instanceof CurveCollection) {
+            this.dispatchCurveCollection(curve, this.handleBSplineCurve3d.bind(this));
+        }
         return undefined;
     }
     /** Double dispatch handler for strongly typed homogeneous bspline curve .. */
@@ -706,8 +768,6 @@ CurveCurveCloseApproachXY._workPointAA0 = Point3d.create();
 CurveCurveCloseApproachXY._workPointAA1 = Point3d.create();
 CurveCurveCloseApproachXY._workPointBB0 = Point3d.create();
 CurveCurveCloseApproachXY._workPointBB1 = Point3d.create();
-CurveCurveCloseApproachXY._workPointBB2 = Point3d.create();
-CurveCurveCloseApproachXY._workVectorA = Vector3d.create();
 CurveCurveCloseApproachXY._workPointB = Point3d.create();
 export { CurveCurveCloseApproachXY };
 //# sourceMappingURL=CurveCurveCloseApproachXY.js.map