@itwin/core-geometry 4.2.0-dev.9 → 4.3.0-dev.1

package/lib/esm/curve/CurveChainWithDistanceIndex.js

@@ -5,6 +5,7 @@
 /** @packageDocumentation
  * @module Curve
  */
+import { assert } from "@itwin/core-bentley";
 import { CurvePrimitive } from "../curve/CurvePrimitive";
 import { StrokeCountMap } from "../curve/Query/StrokeCountMap";
 import { Geometry } from "../Geometry";
@@ -17,14 +18,14 @@ import { PlaneAltitudeRangeContext } from "./internalContexts/PlaneAltitudeRange
 import { OffsetOptions } from "./OffsetOptions";
 import { Path } from "./Path";
 /**
- * Annotation of an interval of a curve.
+ * Annotation of a fragment, i.e. an interval of a curve.
  * * The interval is marked with two pairs of numbers:
- * * * fraction0, fraction1 = fraction parameters along the child curve
- * * * distance0,distance1 = distances within containing CurveChainWithDistanceIndex
+ * * * fraction0, fraction1 = fraction parameters along the child curve.
+ * * * distance0, distance1 = distances within containing CurveChainWithDistanceIndex.
  * @public
  */
 export class PathFragment {
-    /** Create a fragment with complete fraction, distance and child data. */
+    /** Create a fragment with complete fraction, distance, and child data. */
     constructor(childFraction0, childFraction1, distance0, distance1, childCurve, range) {
         this.childFraction0 = childFraction0;
         this.childFraction1 = childFraction1;
@@ -34,68 +35,64 @@ export class PathFragment {
         this.range = range;
         this.a = 0;
     }
-    /**
-     * Return true if the distance is within the distance limits of this fragment.
-     * @param distance
-     */
+    /** Return true if the distance is within the distance limits of this fragment. */
     containsChainDistance(distance) {
         return distance >= this.chainDistance0 && distance <= this.chainDistance1;
     }
-    /** Return a quick distance to the curve.  This may be SMALLER than true distance but may not be larger */
+    /**
+     * Return a quick minimum distance from spacePoint to the curve.
+     * * The returned distance is to the curve's range box if defined; otherwise, the true distance is computed.
+     * * Thus the returned distance may be SMALLER than the true distance to the curve, but not larger.
+     */
     quickMinDistanceToChildCurve(spacePoint) {
-        if (this.range) {
+        if (this.range)
             return this.range.distanceToPoint(spacePoint);
-        }
-        // ugh.  have to do real computation ..
         const detail = this.childCurve.closestPoint(spacePoint, false);
         if (detail)
             return detail.a;
         return 0;
     }
     /**
-     * Return an array with (references to) all the path fragments, sorted smallest to largest on the "a" value
-     * equal to the quick min distance to the fragment
+     * Return an array with (references to) all the input path fragments, sorted smallest to largest on the "a" value,
+     * initialized with `quickMinDistanceToChildCurve`
      */
     static collectSortedQuickMinDistances(fragments, spacePoint) {
         const sortedFragments = [];
-        for (const f of fragments) {
-            f.a = f.quickMinDistanceToChildCurve(spacePoint);
-            sortedFragments.push(f);
+        for (const frag of fragments) {
+            frag.a = frag.quickMinDistanceToChildCurve(spacePoint);
+            sortedFragments.push(frag);
         }
-        sortedFragments.sort((a, b) => a.a - b.a);
+        sortedFragments.sort((frag1, frag2) => frag1.a - frag2.a);
         return sortedFragments;
     }
-    /**
-     * Return true if this fragment addresses `curve` and brackets `fraction`
-     * @param distance
-     */
+    /** Return true if `this` fragment addresses `curve` and brackets `fraction`. */
     containsChildCurveAndChildFraction(curve, fraction) {
         return this.childCurve === curve && fraction >= this.childFraction0 && fraction <= this.childFraction1;
     }
     /**
-     * Convert distance to local fraction, and apply that to interpolate between the stored curve fractions.
-     * Note that proportional calculation does NOT account for nonuniform parameterization in the child curve.
+     * Convert distance to local fraction and apply that to interpolate between the stored curve fractions.
+     * Note that proportional calculation does NOT account for non-uniform parameterization in the child curve.
      */
     chainDistanceToInterpolatedChildFraction(distance) {
-        return Geometry.inverseInterpolate(this.childFraction0, this.chainDistance0, this.childFraction1, this.chainDistance1, distance, this.childFraction0); // the interval "must" have nonzero length, division should be safe . ..
+        return Geometry.inverseInterpolate(this.childFraction0, this.chainDistance0, this.childFraction1, this.chainDistance1, distance, this.childFraction0); // the interval must have nonzero length so division should be safe
     }
-    /** Convert chainDistance to true chidFraction, using detailed moveSignedDistanceFromFraction */
+    /** Convert the given chainDistance to a fraction along this childCurve using `moveSignedDistanceFromFraction`. */
     chainDistanceToAccurateChildFraction(chainDistance, allowExtrapolation) {
-        // The fragments are really expected to do good mappings in their distance range ...
         const childDetail = this.childCurve.moveSignedDistanceFromFraction(this.childFraction0, chainDistance - this.chainDistance0, allowExtrapolation ?? false);
         return childDetail.fraction;
     }
     /**
-     * Return the scale factor to map childCurve fraction derivatives to chain fraction derivatives
-     * @param globalDistance total length of the global curve.
+     * Return the scale factor to map childCurve fraction derivatives to chain fraction derivatives.
+     * @param globalDistance total length of the global curve
      */
     fractionScaleFactor(globalDistance) {
         return globalDistance * (this.childFraction1 - this.childFraction0) / (this.chainDistance1 - this.chainDistance0);
     }
     /**
      * Reverse the fraction and distance data.
-     * * each child fraction `f` is replaced by `1-f`
-     * * each `chainDistance` is replaced by `totalDistance-chainDistance`
+     * * Each child fraction `f` is replaced by `1-f`
+     * * Each `chainDistance` is replaced by `totalDistance - chainDistance`
+     * @param totalDistance the total distance
      */
     reverseFractionsAndDistances(totalDistance) {
         const f0 = this.childFraction0;
@@ -107,14 +104,14 @@ export class PathFragment {
         this.chainDistance0 = totalDistance - d1;
         this.chainDistance1 = totalDistance - d0;
     }
-    /** @deprecated in 3.x. Use childFractionToChainDistance */
+    /** @deprecated in 3.x. Use `PathFragment.childFractionToChainDistance`. */
     childFractionTChainDistance(fraction) {
         return this.childFractionToChainDistance(fraction);
     }
     /**
-     * Convert a fractional position on the childCurve to distance in the chain space.
-     * * Return value is SIGNED -- will be negative when fraction < this.childFraction0.
-     * @param fraction fraction along the curve within this fragment
+     * Convert a fractional position on the childCurve of this fragment to distance on the curve chain.
+     * * Return value is SIGNED and will be negative when `fraction < this.childFraction0`.
+     * @param fraction the fractional position on the childCurve of this fragment
      */
     childFractionToChainDistance(fraction) {
         let d = this.childCurve.curveLengthBetweenFractions(this.childFraction0, fraction);
@@ -123,7 +120,7 @@ export class PathFragment {
         return this.chainDistance0 + d;
     }
 }
-/** Non-instantiable class to build a distance index for a path. */
+/** Non-instantiable class to build a distance index for a curve chain. */
 class DistanceIndexConstructionContext {
     constructor() {
         this._accumulatedDistance = 0;
@@ -135,7 +132,6 @@ class DistanceIndexConstructionContext {
     endParentCurvePrimitive(_cp) { }
     endCurvePrimitive(_cp) { }
     announcePointTangent(_xyz, _fraction, _tangent) { }
-    /** Announce numPoints interpolated between point0 and point1, with associated fractions */
     announceSegmentInterval(cp, point0, point1, numStrokes, fraction0, fraction1) {
         const fragmentPoint0 = point0.clone();
         const fragmentPoint1 = point1.clone();
@@ -167,7 +163,10 @@ class DistanceIndexConstructionContext {
             this._fragments.push(new PathFragment(f0, f1, d0, this._accumulatedDistance, cp, range));
         }
     }
-    needPrimaryGeometryForStrokes() { return true; }
+    needPrimaryGeometryForStrokes() {
+        return true;
+    }
+    /** Create an array of PathFragment from input curve chain. */
     static createPathFragmentIndex(path, options) {
         const handler = new DistanceIndexConstructionContext();
         for (const curve of path.children) {
@@ -182,12 +181,11 @@ class DistanceIndexConstructionContext {
  * distance along a CurveChain.
  * * For example if the total length of the chain is `L`, then the distance along the chain from parameters `t0`
  * to `t1` is easily computed as `L*(t1-t0)`.
- * * The curve chain can be any type derived from CurveChain.
- * * * i.e. either a `Path` or a `Loop`
+ * * The curve chain can be any type derived from `CurveChain`, i.e., either a `Path` or a `Loop`.
  * @public
  */
 class CurveChainWithDistanceIndex extends CurvePrimitive {
-    /** Test if other is a `CurveChainWithDistanceIndex` */
+    /** Test if `other` is a `CurveChainWithDistanceIndex` */
     isSameGeometryClass(other) {
         return other instanceof CurveChainWithDistanceIndex;
     }
@@ -212,7 +210,7 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
     }
     /**
      * Reference to the contained path.
-     * * Do not modify the path.  The distance index will be wrong.
+     * * Do not modify the path. The distance index will be wrong.
      */
     get path() {
         return this._path;
@@ -306,14 +304,14 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
         }
         return true;
     }
-    /** Return the start point of the primitive.  The default implementation returns fractionToPoint (0.0) */
+    /** Return the start point of `this` curve. */
     startPoint(result) {
         const c = this._path.cyclicCurvePrimitive(0);
         if (c)
             return c.startPoint(result);
         return Point3d.createZero(result);
     }
-    /** Return the end point of the primitive. The default implementation returns fractionToPoint(1.0) */
+    /** Return the end point of of `this` curve. */
     endPoint(result) {
         const c = this._path.cyclicCurvePrimitive(-1);
         if (c)
@@ -349,7 +347,7 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
     /**
      * Return an array containing only the curve primitives.
      * @param collectorArray array to receive primitives (pushed -- the array is not cleared)
-     * @param smallestPossiblePrimitives if true, recurse on the (otherwise hidden) children. If false, only push `this`.
+     * @param smallestPossiblePrimitives if true, recurse on the children. If false, only push `this`.
      * @param explodeLinestrings (if smallestPossiblePrimitives is true) whether to push a [[LineSegment3d]] for each
      * segment of a [[LineString3d]] child. If false, push only the [[LineString3d]].
      */
@@ -376,21 +374,17 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
         CurvePrimitive.installStrokeCountMap(this, myMap, parentStrokeMap);
     }
     /**
-     * Second step of double dispatch:  call `this._path.dispatchToGeometryHandler (handler)`
+     * Second step of double dispatch: call `this._path.dispatchToGeometryHandler (handler)`
      * * Note that this exposes the children individually to the handler.
      */
     dispatchToGeometryHandler(handler) {
-        return this._path.dispatchToGeometryHandler(handler);
+        return handler.handleCurveChainWithDistanceIndex(this);
     }
-    /** Extend (increase) `rangeToExtend` as needed to include these curves (optionally transformed) */
+    /** Extend `rangeToExtend` as needed to include these curves (optionally transformed) */
     extendRange(rangeToExtend, transform) {
         this._path.extendRange(rangeToExtend, transform);
     }
-    /**
-     * Curve length is always positive.
-     * @returns Returns a (high accuracy) length of the curve between fractional positions
-     * @returns Returns the length of the curve.
-     */
+    /** Return a (high accuracy and positive) length of the curve between fractional positions */
     curveLengthBetweenFractions(fraction0, fraction1) {
         return Math.abs(fraction1 - fraction0) * this._totalLength;
     }
@@ -404,9 +398,10 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
         return result;
     }
     /**
-     * Resolve a fraction of the CurveChain to a PathFragment
-     * @param distance
-     * @param allowExtrapolation
+     * Return the PathFragment object at the given `distance` along the chain.
+     * @param distance distance along the chain.
+     * @param allowExtrapolation if `true`, returns first fragment for negative distances and returns last fragment
+     * for distances larger than curve length. If `false` returns `undefined` for those out of bound distances.
      */
     chainDistanceToFragment(distance, allowExtrapolation = false) {
         const i = this.chainDistanceToFragmentIndex(distance, allowExtrapolation);
@@ -415,9 +410,10 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
         return undefined;
     }
     /**
-     * Resolve a fraction of the CurveChain to a PathFragment index
-     * @param distance
-     * @param allowExtrapolation
+     * Return the index of the PathFragment at the given `distance` along the chain.
+     * @param distance distance along the chain.
+     * @param allowExtrapolation if `true`, returns 0 for negative distances and returns last fragment index for
+     * distances larger than curve length. If `false` returns `undefined` for those out of bound distances.
      */
     chainDistanceToFragmentIndex(distance, allowExtrapolation = false) {
         const numFragments = this._fragments.length;
@@ -427,7 +423,7 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
                 return allowExtrapolation ? 0 : undefined;
             if (distance > this._totalLength)
                 return allowExtrapolation ? (numFragments - 1) : undefined;
-            // humbug, linear search
+            // linear search (opportunity for improvement)
             for (let i = 0; i < numFragments; i++) {
                 if (fragments[i].containsChainDistance(distance))
                     return i;
@@ -437,33 +433,29 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
     }
     /**
      * Convert distance along the chain to fraction along the chain.
-     * @param distance distance along the chain
+     * @param distance distance along the chain.
      */
     chainDistanceToChainFraction(distance) {
         return distance / this._totalLength;
     }
-    /**
-     * Resolve a fraction within a specific curve to a fragment.
-     * @param curve
-     * @param fraction
-     */
+    /** Return the PathFragment object containing the point at the given `fraction` of the given child curve. */
     curveAndChildFractionToFragment(curve, fraction) {
         const numFragments = this._fragments.length;
         const fragments = this._fragments;
         if (numFragments > 0) {
-            // humbug, linear search
+            if (fraction < 0)
+                return fragments[0];
+            if (fraction > 1.0)
+                return fragments[numFragments - 1];
+            // linear search (opportunity for improvement)
             for (const fragment of fragments) {
                 if (fragment.containsChildCurveAndChildFraction(curve, fraction))
                     return fragment;
             }
-            if (fraction <= 0)
-                return fragments[0];
-            if (fraction > 1.0)
-                return fragments[numFragments - 1];
         }
         return undefined;
     }
-    /** Returns the total length of curves. */
+    /** Returns the total length of `this` curve. */
     curveLength() {
         return this._totalLength;
     }
@@ -476,52 +468,59 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
     }
     /**
      * Return the point (x,y,z) on the curve at fractional position along the chain.
-     * @param fraction fractional position along the geometry.
-     * @returns Returns a point on the curve.
+     * @param fraction fractional position along the curve.
+     * @returns a point on the curve.
      */
     fractionToPoint(fraction, result) {
-        const chainDistance = fraction * this._totalLength;
-        const fragment = this.chainDistanceToFragment(chainDistance, true);
+        const distanceAlongPath = fraction * this._totalLength;
+        const fragment = this.chainDistanceToFragment(distanceAlongPath, true);
         if (fragment) {
-            const childFraction = fragment.chainDistanceToAccurateChildFraction(chainDistance, true);
+            const childFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
             return fragment.childCurve.fractionToPoint(childFraction, result);
         }
-        // no fragment found.  Use _fragments[0]
-        //    fragment = this.chainDistanceToFragment(chainDistance, true);
+        assert(false); // we never expect to get here
+        // no fragment found. just return the first point on the curve.
         return this._fragments[0].childCurve.fractionToPoint(0.0, result);
     }
     /**
      * Return the point (x,y,z) and derivative on the curve at fractional position.
-     * * Note that this derivative is "derivative of xyz with respect to fraction."
-     * * this derivative shows the speed of the "fractional point" moving along the curve.
-     * * this is not generally a unit vector.  use fractionToPointAndUnitTangent for a unit vector.
+     * * Note that the derivative is "derivative of xyz with respect to fraction".
+     * * The derivative shows the speed of the "fractional point" moving along the curve.
+     * * The derivative is not generally a unit vector. Use `fractionToPointAndUnitTangent` for a unit vector.
      * @param fraction fractional position along the geometry.
-     * @returns Returns a ray whose origin is the curve point and direction is the derivative with respect to the fraction.
+     * @param result optional receiver for the result.
+     * @returns a ray whose origin is the curve point and direction is the derivative with respect to the fraction.
      */
     fractionToPointAndDerivative(fraction, result) {
         const distanceAlongPath = fraction * this._totalLength;
         const fragment = this.chainDistanceToFragment(distanceAlongPath, true);
-        const curveFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
-        result = fragment.childCurve.fractionToPointAndDerivative(curveFraction, result);
-        // Fractional arc length parameterization for the curve C is f=f(t)=s(t)/L, where
-        // L is total length of C, f'=||C'||/L, and inverse t=t(f), t'=1/f'=L/||C'||.
-        // Then d/df(C(t(f)))=C't'=C'L/||C'||. The fragment gave us C', so the
-        // derivative we seek is just a scale away.
-        const a = this._totalLength / result.direction.magnitude();
+        const childFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
+        result = fragment.childCurve.fractionToPointAndDerivative(childFraction, result);
+        // Recall the standard arclength formula s(t) for the curve C = C(t), with derivative s'(t) = ||C'||.
+        // Define fractional arclength for C by f = f(t) = s(t)/L, where L is the total length of C. Then f' = ||C'||/L.
+        // Denote the inverse of f by t = t(f). Then C = C(t(f)) is a parameterization of C by its fractional arclength f.
+        // Since the derivative of t is t'=1/f'=L/||C'||, the derivative we seek is d/df(C(t(f))) = C' t' = C' L/||C'||.
+        // The fragment gives us C', so we're just a scale away.
+        // Math details can be found at core/geometry/internaldocs/Curve.md
+        const a = this._totalLength / result.direction.magnitude(); // L/||C'||
         result.direction.scaleInPlace(a);
         return result;
     }
     /**
-     * Returns a ray whose origin is the curve point and direction is the unit tangent.
+     * Return the point (x,y,z) and normalized derivative on the curve at fractional position.
+     * * Note that the derivative is "derivative of xyz with respect to fraction".
+     * * The un-normalized derivative shows the speed of the "fractional point" moving along the curve.
+     * * To find the un-normalized derivative, use `fractionToPointAndDerivative`.
      * @param fraction fractional position on the curve
      * @param result optional receiver for the result.
-     * Returns a ray whose origin is the curve point and direction is the unit tangent.
+     * @returns a ray whose origin is the curve point and direction is the normalized derivative with respect to
+     * the fraction.
      */
     fractionToPointAndUnitTangent(fraction, result) {
         const distanceAlongPath = fraction * this._totalLength;
         const fragment = this.chainDistanceToFragment(distanceAlongPath, true);
-        const curveFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
-        result = fragment.childCurve.fractionToPointAndDerivative(curveFraction, result);
+        const childFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
+        result = fragment.childCurve.fractionToPointAndDerivative(childFraction, result);
         result.direction.normalizeInPlace();
         return result;
     }
@@ -530,34 +529,39 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
      * * origin at fractional position along the curve
      * * vectorU is the first derivative, i.e. tangent vector with length equal to the rate of change with respect to
      * the fraction.
-     * * vectorV is the second derivative, i.e.derivative of vectorU.
+     * * vectorV is the second derivative, i.e. derivative of vectorU which points in the direction of the curve's
+     * derivative's change.
      */
     fractionToPointAnd2Derivatives(fraction, result) {
         const distanceAlongPath = fraction * this._totalLength;
         const fragment = this.chainDistanceToFragment(distanceAlongPath, true);
-        const curveFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
-        result = fragment.childCurve.fractionToPointAnd2Derivatives(curveFraction, result);
+        const childFraction = fragment.chainDistanceToAccurateChildFraction(distanceAlongPath, true);
+        result = fragment.childCurve.fractionToPointAnd2Derivatives(childFraction, result);
         if (!result)
             return undefined;
-        // See fractionToPointAndDerivative for derivation of d/df(C(t(f)))=L C'/||C'||.
-        // For the 2nd deriv, use quotient rule, d/dt||x(t)||=x.x'/||x|| and ||x||^2=x.x :
-        // d/df(C'(t(f))) = L d/df(C'/||C'||)
-        //  = L (||C'|| d/df(C') - C' d/df||C'||) / ||C'||^2
+        // See fractionToPointAndDerivative, where we show d/df(C(t(f))) = L C'/||C'||.
+        // Here we seek the 2nd derivative. We'll use the quotient rule, and the identities
+        // d/dt||x(t)|| = x.x'/||x|| and ||x||^2 = x.x, where "." is the dot product.
+        // d2/df2(C(t(f))) = L d/df(C'/||C'||) = L (||C'|| d/df(C') - C' d/df||C'||) / ||C'||^2
         //  = L (||C'|| C" L/||C'|| - C' C'.C"/||C'|| L/||C'||) / ||C'||^2
-        //  = (L/||C'||)^2 (C" - C' C'.C"/C'.C' )
-        // We have C' and C" from the fragment.
-        const magU = result.vectorU.magnitude();
-        const dotUU = magU * magU;
-        const dotUV = result.vectorU.dotProduct(result.vectorV);
-        result.vectorV.addScaledInPlace(result.vectorU, -dotUV / dotUU);
-        const scale = this._totalLength / magU;
-        result.vectorU.scaleInPlace(scale);
-        result.vectorV.scaleInPlace(scale * scale);
+        //  = (L/||C'||)^2 (C" - C' C'.C"/C'.C' ), where C' and C" are given by the fragment.
+        // The second derivative that fractionToPointAnd2Derivatives returns is C", so the second
+        // derivative we seek is just few scales away.
+        // Math details can be found at core/geometry/internaldocs/Curve.md
+        const magU = result.vectorU.magnitude(); // ||C'||
+        const dotUU = magU * magU; // ||C'||^2
+        const dotUV = result.vectorU.dotProduct(result.vectorV); // C'.C"
+        result.vectorV.addScaledInPlace(result.vectorU, -dotUV / dotUU); // add -(C'*C'.C")/(||C'||^2) to vectorV
+        const scale = this._totalLength / magU; // L/||C'||
+        result.vectorU.scaleInPlace(scale); // scale vectorU by L/||C'||
+        result.vectorV.scaleInPlace(scale * scale); // scale vectorV by (L/||C'(t)||)^2
         return result;
     }
     /**
      * Attempt to transform in place.
-     * * Warning: If any child fails, this object becomes invalid.  But that should never happen.
+     * * Warning: If any child transform fails, `this` object becomes invalid but that should never happen.
+     * @param transform the transform to be applied.
+     * @returns true if all of child transforms succeed and false otherwise.
      */
     tryTransformInPlace(transform) {
         let numFail = 0;
@@ -570,48 +574,45 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
     /** Reverse the curve's data so that its fractional stroking moves in the opposite direction. */
     reverseInPlace() {
         this._path.reverseChildrenInPlace();
-        const totalLength = this._totalLength;
         for (const fragment of this._fragments) {
-            fragment.reverseFractionsAndDistances(totalLength);
+            fragment.reverseFractionsAndDistances(this._totalLength);
         }
         this._fragments.reverse();
     }
     /**
-     * Test for equality conditions:
-     * * Mismatched totalLength is a quick exit condition
-     * * If totalLength matches, recurse to the path for matching primitives.
-     * @param other
+     * Test for equality conditions.
+     * * Mismatched total length is a quick exit condition.
+     * * If total length matches, recurse to the path for matching primitives.
      */
     isAlmostEqual(other) {
         if (other instanceof CurveChainWithDistanceIndex) {
-            return Geometry.isSameCoordinate(this._totalLength, other._totalLength)
-                && this._path.isAlmostEqual(other._path);
+            return Geometry.isSameCoordinate(this._totalLength, other._totalLength) && this._path.isAlmostEqual(other._path);
         }
         return false;
     }
     /**
-     * Implement moveSignedDistanceFromFraction.
-     * * See `CurvePrimitive` for parameter details.
-     * * The returned location directly identifies fractional position along the CurveChainWithDistanceIndex, and
+     * (Attempt to) find a position on the curve at a signed distance from start fraction.
+     * * See `CurvePrimitive.moveSignedDistanceFromFraction` for parameter details.
+     * * The returned location directly identifies fractional position along the CurveChainWithDistanceIndex and
      * has pointer to an additional detail for the child curve.
      */
     moveSignedDistanceFromFraction(startFraction, signedDistance, allowExtension, result) {
         const distanceA = startFraction * this._totalLength;
         const distanceB = distanceA + signedDistance;
         const fragmentB = this.chainDistanceToFragment(distanceB, true);
-        const childDetail = fragmentB.childCurve.moveSignedDistanceFromFraction(fragmentB.childFraction0, distanceB - fragmentB.chainDistance0, allowExtension, result);
+        const childDetail = fragmentB.childCurve.moveSignedDistanceFromFraction(fragmentB.childFraction0, distanceB - fragmentB.chainDistance0, allowExtension, result); // local detail related to the child curve
         const endFraction = startFraction + (signedDistance / this._totalLength);
-        const chainDetail = CurveLocationDetail.createConditionalMoveSignedDistance(allowExtension, this, startFraction, endFraction, signedDistance, result);
+        const chainDetail = CurveLocationDetail.createConditionalMoveSignedDistance(allowExtension, this, startFraction, endFraction, signedDistance, result); // global detail related to the curve chain
         chainDetail.childDetail = childDetail;
         return chainDetail;
     }
     /**
+     * Return an object summarizing closest point test counts.
      * The returned object has
      * * numCalls = number of times closestPoint was called.
-     * * numCurvesTested = number of curves tested with full closestPoint
-     * * numAssigned = number of times a new minimum value was recorded
+     * * numCurvesTested = number of curves tested with full closestPoint.
+     * * numAssigned = number of times a new minimum value was recorded.
      * * numCandidate = number of curves that would be tested in worst case.
-     * return an object summarizing closest point test counts
      * @param clear if true, counts are cleared after the return object is formed.
      */
     static getClosestPointTestCounts(clear = true) {
@@ -628,13 +629,13 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
     }
     /**
      * Search for the curve point that is closest to the spacePoint.
-     * * The CurveChainWithDistanceIndex invokes the base class CurvePrimitive method, which
-     *     (via a handler) determines a CurveLocation detail among the children.
-     * * The returned detail directly identifies fractional position along the CurveChainWithDistanceIndex, and
+     * * The CurveChainWithDistanceIndex invokes the base class CurvePrimitive method, which (via a handler)
+     * determines a CurveLocation detail among the children.
+     * * The returned detail directly identifies fractional position along the CurveChainWithDistanceIndex and
      * has pointer to an additional detail for the child curve.
      * @param spacePoint point in space
      * @param extend true to extend the curve
-     * @returns Returns a CurveLocationDetail structure that holds the details of the close point.
+     * @returns a CurveLocationDetail structure that holds the details of the close point.
      */
     closestPoint(spacePoint, extend) {
         let childDetail;
@@ -645,44 +646,43 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
         }
         else {
             const sortedFragments = PathFragment.collectSortedQuickMinDistances(this._fragments, spacePoint);
-            const extend0 = [CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 0), CurveExtendMode.None];
-            const extend1 = [CurveExtendMode.None, CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 1)];
+            const extend0 = [
+                CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 0),
+                CurveExtendMode.None,
+            ];
+            const extend1 = [
+                CurveExtendMode.None,
+                CurveExtendOptions.resolveVariantCurveExtendParameterToCurveExtendMode(extend, 1),
+            ];
             const fragment0 = this._fragments[0];
             const fragment1 = this._fragments[this._fragments.length - 1];
             CurveChainWithDistanceIndex._numCalls++;
             CurveChainWithDistanceIndex._numCandidate += sortedFragments.length;
-            for (const f of sortedFragments) {
-                if (f.a > aMin)
+            let detailA;
+            for (const sortedFragment of sortedFragments) {
+                if (sortedFragment.a > aMin)
+                    // sortedFragments help early exit because it is likely that one of the first few fragments
+                    // in sortedFragments is the fragment with minimum distance from space point to the curve.
                     break;
                 CurveChainWithDistanceIndex._numTested++;
-                const child = f.childCurve;
-                const detailA = child.closestPoint(spacePoint, f === fragment0 ? extend0 : f === fragment1 ? extend1 : false);
+                const child = sortedFragment.childCurve;
+                detailA = child.closestPoint(spacePoint, sortedFragment === fragment0 ? extend0 : sortedFragment === fragment1 ? extend1 : false, detailA);
                 if (detailA && detailA.a < aMin) {
                     aMin = detailA.a;
-                    childDetail = CurveLocationDetail.createCurveFractionPoint(detailA.curve, detailA.fraction, detailA.point, childDetail);
-                    childDetail.a = detailA.a;
+                    childDetail = detailA.clone(childDetail);
                     CurveChainWithDistanceIndex._numAssigned++;
                 }
             }
         }
         if (!childDetail)
             return undefined;
-        const fragment = this.curveAndChildFractionToFragment(childDetail.curve, childDetail.fraction);
-        if (fragment) {
-            const chainDistance = fragment.childFractionToChainDistance(childDetail.fraction);
-            const chainFraction = this.chainDistanceToChainFraction(chainDistance);
-            const chainDetail = CurveLocationDetail.createCurveFractionPoint(this, chainFraction, childDetail.point);
-            chainDetail.childDetail = childDetail;
-            chainDetail.a = childDetail.a;
-            return chainDetail;
-        }
-        return undefined;
+        return this.computeChainDetail(childDetail);
     }
     /**
      * Construct an offset of each child as viewed in the xy-plane (ignoring z).
-     * * No attempt is made to join the offset children. Use RegionOps.constructCurveXYOffset() to return a fully
+     * * No attempt is made to join the offset children. Use RegionOps.constructCurveXYOffset to return a fully
      * joined offset.
-     * @param offsetDistanceOrOptions offset distance (positive to left of the instance curve), or options object
+     * @param offsetDistanceOrOptions offset distance (positive to left of the instance curve) or offset options object.
      */
     constructOffsetXY(offsetDistanceOrOptions) {
         const options = OffsetOptions.create(offsetDistanceOrOptions);
@@ -702,13 +702,32 @@ class CurveChainWithDistanceIndex extends CurvePrimitive {
      * Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters of
      * projection.
      * @param ray ray onto which the instance is projected. A `Vector3d` is treated as a `Ray3d` with zero origin.
-     * @param lowHigh optional receiver for output
+     * @param lowHigh optional receiver for output.
      * @returns range of fractional projection parameters onto the ray, where 0.0 is start of the ray and 1.0 is the
      * end of the ray.
      */
     projectedParameterRange(ray, lowHigh) {
         return PlaneAltitudeRangeContext.findExtremeFractionsAlongDirection(this, ray, lowHigh);
     }
+    /**
+     * Compute the global chain detail corresponding to a local child detail.
+     * @param childDetail the local detail, with respect to a child of this chain.
+     * @returns the global detail, with respect to this chain.
+     */
+    computeChainDetail(childDetail) {
+        if (!childDetail.curve)
+            return undefined;
+        const fragment = this.curveAndChildFractionToFragment(childDetail.curve, childDetail.fraction);
+        if (fragment) {
+            const chainDistance = fragment.childFractionToChainDistance(childDetail.fraction);
+            const chainFraction = this.chainDistanceToChainFraction(chainDistance);
+            const chainDetail = CurveLocationDetail.createCurveFractionPoint(this, chainFraction, childDetail.point);
+            chainDetail.childDetail = childDetail;
+            chainDetail.a = childDetail.a;
+            return chainDetail;
+        }
+        return undefined;
+    }
 }
 CurveChainWithDistanceIndex._numCalls = 0;
 CurveChainWithDistanceIndex._numTested = 0;