@itwin/core-geometry 5.0.0-dev.62 → 5.0.0-dev.65

package/lib/esm/bspline/BSplineCurve.js

@@ -28,83 +28,117 @@ import { BSplineCurveOps } from "./BSplineCurveOps";
 import { BSplineWrapMode, KnotVector } from "./KnotVector";
 /**
  * Base class for BSplineCurve3d and BSplineCurve3dH.
- * * A bspline curve consists of a set of knots and a set of poles.
- * * The bspline curve is a function of the independent "knot axis" variable
- * * The curve "follows" the poles loosely.
- * * The is a set of polynomial spans.
+ * * A B-spline curve consists of an array of `knots`, an array of `poles`, and a `degree`.
+ * * The knot array is a non-decreasing sequence of numbers. It is also called a "knot vector".
+ *   * The curve is a parametric function whose domain is a sub-range of its knots.
+ *   * The API sometimes refers to a domain parameter `u` as a "knot", even if `u` is not actually an entry in the
+ * knot array.
+ * * The curve loosely "follows" the line string formed by the poles, aka the "control polygon".
+ * * The curve is a chain of polynomial segments, aka "spans" or "fragments". B-spline theory identifies these as
+ * Bezier curves.
  * * The polynomial spans all have same `degree`.
- * * Within each span, the polynomial of that `degree` is controlled by `order = degree + 1` contiguous points called poles.
- * * The is a strict relationship between knot and poles counts:  `numPoles + order = numKnots + 2'
- * * The number of spans is `numSpan = numPoles - degree`
- * * For a given `spanIndex`:
- *   * The `order` poles begin at index `spanIndex`.
- *   * The `2*order` knots begin as span index
- *   * The knot interval for this span is from `knot[degree+span-1] to knot[degree+span]`
- * * The active part of the knot axis is `knot[degree-1] < knot < knot[degree-1 + numSpan]` i.e. `knot[degree-1] < knot < knot[numPoles]
+ * * Each span is controlled by `order = degree + 1` contiguous points in the pole array.
+ * * There is a strict relationship between knot and poles counts: `numPoles + order = numKnots + 2'.
+ * * The number of spans is `numSpan = numPoles - degree`.
+ * * For a span with index `spanIndex`:
+ *   * The `order` relevant poles begin at pole index `spanIndex`.
+ *   * The `2*degree` relevant knots begin at knot index `spanIndex`.
+ *   * The span domain is the knot range `[knot[spanIndex+degree-1], knot[spanIndex+degree]]`.
+ * * The curve domain is the knot range `[knot[degree-1], knot[numSpan+degree-1]]`, or equivalently
+ * `[knot[degree-1], knot[numPoles-1]]`. The API refers to this domain as the "active knot interval" of the curve.
  *
- * Nearly all bsplines are "clamped ".
- * * Clamping make the curve pass through its first and last poles, with tangents directed along the first and last edges of the control polygon.
- * * The knots for a clamped bspline have `degree` copies of the lowest knot value and `degree` copies of the highest knot value.
- * * For instance, the knot vector `[0,0,0,1,2,3,3,3]
- *   * can be evaluated from `0<=knot<=3`
- *   * has 3 spans: 0 to 1, 1 to 2, 2 to 3
+ * Nearly all B-spline curves are "clamped".
+ * * This means that in the `knots` array, the first `degree` knots are equal, and the last `degree` knots are equal.
+ * We say the smallest knot and the largest knot have multiplicity `degree`.
+ * * Clamping make the curve pass through its first and last poles, with tangents directed along the first and
+ * last edges of the control polygon.
+ * * For instance, a cubic B-spline curve with knot vector `[0,0,0,1,2,3,3,3]`
+ *   * can be evaluated at parameter values in the range `[0, 3]`
+ *   * has 3 spans, with domains `[0, 1]`, `[1, 2]`, and `[2, 3]`
  *   * has 6 poles
  *   * passes through its first and last poles.
- * * `create` methods may allow classic convention that has an extra knot at the beginning and end of the knot vector.
- *   * The extra knots (first and last) were never referenced by the bspline recurrence relations.
- *   * When the `create` methods recognize the classic setup (`numPoles + order = numKnots`), the extra knot is not saved with the BSplineCurve3dBase knots.
+ * * The `create` methods may allow the classic convention that has an extra knot at the beginning and end of the
+ * knot vector.
+ *   * These two extra knots are not actually needed to define the B-spline curve.
+ *   * When the `create` methods recognize the classic setup (`numPoles + order = numKnots`), the extra knots are
+ * not saved with the BSplineCurve3dBase knots.
  *
- * * The weighted variant has the problem that CurvePrimitive 3d typing does not allow undefined result where Point4d has zero weight.
- * * The convention for these is to return 000 in such places.
+ * * The weighted variant [[BSplineCurve3dH]] has the problem that `CurvePrimitive` 3D typing does not allow the
+ *  undefined result where a homogeneous pole has zero weight; the convention in this case is to return 000.
  *
  * * Note the class relationships:
- *   * BSpline1dNd knows the bspline recurrence relations for control points (poles) with no physical meaning.
- *   * BsplineCurve3dBase owns a protected BSpline1dNd
- *   * BsplineCurve3dBase is derived from CurvePrimitive, which creates obligation to act as a 3D curve, such as
- *     * evaluate fraction to point and derivatives wrt fraction
- *     * compute intersection with plane
- *   * BSplineCurve3d and BSplineCurve3dH have variant logic driven by whether or not there are "weights" on the poles.
- *     * For `BSplineCurve3d`, the xyz value of pole calculations are "final" values for 3d evaluation
+ *   * [[BSpline1dNd]] knows the definitional B-spline recurrence relation with no physical interpretation for the poles.
+ *   * BsplineCurve3dBase owns a protected BSpline1dNd.
+ *   * `BsplineCurve3dBase` is derived from [[CurvePrimitive]], which creates obligation to act as a 3D curve, e.g.,
+ *     * evaluate fraction to point and derivatives wrt fraction.
+ *     * compute intersection with plane.
+ *   * [[BSplineCurve3d]] and [[BSplineCurve3dH]] have variant logic driven by whether or not there are "weights" on the poles.
+ *     * For `BSplineCurve3d`, the xyz value of pole calculations are "final" values for 3d evaluation.
  *     * For `BSplineCurve3dH`, various `BSpline1dNd` results with xyzw have to be normalized back to xyz.
  *
  * * These classes do not support "periodic" variants.
- *   * Periodic curves need to have certain leading knots and poles replicated at the end
+ *   * Periodic curves historically have carried a flag (e.g., "closed") indicating that certain un-stored
+ * leading/trailing knots and poles are understood to wrap around periodically.
+ *   * Instead, these classes carry no such flag. They represent such curves with explicitly wrapped knots/poles.
+ *
+ * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/BSpline/
  * @public
  */
 export class BSplineCurve3dBase extends CurvePrimitive {
-    /** String name for schema properties */
+    /** String name for schema properties. */
     curvePrimitiveType = "bsplineCurve";
-    /** The underlying blocked-pole spline, with simple x,y,z poles */
+    /** The underlying blocked-pole spline, with simple x,y,z poles. */
     _bcurve;
     _definitionData;
-    set definitionData(data) { this._definitionData = data; }
-    get definitionData() { return this._definitionData; }
+    set definitionData(data) {
+        this._definitionData = data;
+    }
+    get definitionData() {
+        return this._definitionData;
+    }
     constructor(poleDimension, numPoles, order, knots) {
         super();
         this._bcurve = BSpline1dNd.create(numPoles, poleDimension, order, knots);
     }
-    /** Return the degree (one less than the order) of the curve */
-    get degree() { return this._bcurve.degree; }
-    /** Return the order (one more than degree) of the curve */
-    get order() { return this._bcurve.order; }
-    /** Return the number of bezier spans in the curve.  Note that this number includes the number of null spans at repeated knows */
-    get numSpan() { return this._bcurve.numSpan; }
-    /** Return the number of poles */
-    get numPoles() { return this._bcurve.numPoles; }
-    /** Return live reference to the packed control point coordinates of the curve. */
-    get polesRef() { return this._bcurve.packedData; }
-    /** Return live reference to the knots of the curve. */
-    get knotsRef() { return this._bcurve.knots.knots; }
-    /** Number of components per pole.
-     * * 3 for conventional (x,y,z) curve
-     * * 4 for weighted (wx,wy,wz,w) curve
+    /** Return the degree (one less than the order) of the curve. */
+    get degree() {
+        return this._bcurve.degree;
+    }
+    /** Return the order (one more than degree) of the curve. */
+    get order() {
+        return this._bcurve.order;
+    }
+    /**
+     * Return the number of Bezier spans in the curve. Note that this number includes the number of null
+     * spans at repeated knows.
      */
-    get poleDimension() { return this._bcurve.poleLength; }
+    get numSpan() {
+        return this._bcurve.numSpan;
+    }
+    /** Return the number of poles. */
+    get numPoles() {
+        return this._bcurve.numPoles;
+    }
+    /** Return live reference to the poles of the curve. */
+    get polesRef() {
+        return this._bcurve.packedData;
+    }
+    /** Return live reference to the knots of the curve. */
+    get knotsRef() {
+        return this._bcurve.knots.knots;
+    }
     /**
-     * return a simple array form of the knots.  optionally replicate the first and last
-     * in classic over-clamped manner
+     * Number of components per pole, e.g.,
+     * * 3 for conventional (x,y,z) curve.
+     * * 4 for weighted (wx,wy,wz,w) curve.
      */
-    copyKnots(includeExtraEndKnot) { return this._bcurve.knots.copyKnots(includeExtraEndKnot); }
+    get poleDimension() {
+        return this._bcurve.poleLength;
+    }
+    /** Return a simple array form of the knots. Optionally replicate the first and last in classic over-clamped manner. */
+    copyKnots(includeExtraEndKnot) {
+        return this._bcurve.knots.copyKnots(includeExtraEndKnot);
+    }
     /** Get the flag indicating the curve might be suitable for having wrapped "closed" interpretation. */
     getWrappable() {
         return this._bcurve.knots.wrappable;
@@ -114,7 +148,7 @@ export class BSplineCurve3dBase extends CurvePrimitive {
         this._bcurve.knots.wrappable = value;
     }
     /**
-     * Test knots and control points to determine if it is possible to close (aka "wrap") the curve.
+     * Test knots and poles to determine if it is possible to close (aka "wrap") the curve.
      * @returns the manner in which it is possible to close the curve. See `BSplineWrapMode` for particulars of each mode.
      */
     get isClosableCurve() {
@@ -127,25 +161,18 @@ export class BSplineCurve3dBase extends CurvePrimitive {
             return BSplineWrapMode.None;
         return mode;
     }
-    /** Evaluate the curve point at `fraction` */
+    /** Evaluate the curve point at the given fractional parameter. */
     fractionToPoint(fraction, result) {
         return this.knotToPoint(this._bcurve.knots.fractionToKnot(fraction), result);
     }
-    /** Construct a ray with
-     * * origin at the fractional position along the arc
-     * * direction is the first derivative, i.e. tangent along the curve
-     */
+    /** Evaluate the curve and derivative at the given fractional parameter. */
     fractionToPointAndDerivative(fraction, result) {
         const knot = this._bcurve.knots.fractionToKnot(fraction);
         result = this.knotToPointAndDerivative(knot, result);
         result.direction.scaleInPlace(this._bcurve.knots.knotLength01);
         return result;
     }
-    /** Construct a plane with
-     * * origin at the fractional position along the arc
-     * * x axis is the first derivative, i.e. tangent along the curve
-     * * y axis is the second derivative
-     */
+    /** Evaluate the curve and two derivatives at the given fractional parameter. */
     fractionToPointAnd2Derivatives(fraction, result) {
         const knot = this._bcurve.knots.fractionToKnot(fraction);
         result = this.knotToPointAnd2Derivatives(knot, result);
@@ -154,22 +181,23 @@ export class BSplineCurve3dBase extends CurvePrimitive {
         result.vectorV.scaleInPlace(a * a);
         return result;
     }
+    /** Return the start point of the curve. */
+    startPoint() {
+        return this.evaluatePointInSpan(0, 0.0);
+    }
+    /** Return the end point of the curve. */
+    endPoint() {
+        return this.evaluatePointInSpan(this.numSpan - 1, 1.0);
+    }
     /**
-     * Return the start point of the curve.
-     */
-    startPoint() { return this.evaluatePointInSpan(0, 0.0); }
-    /**
-     * Return the end point of the curve
-     */
-    endPoint() { return this.evaluatePointInSpan(this.numSpan - 1, 1.0); }
-    /** Reverse the curve in place.
-     * * Poles are reversed
-     * * knot values are mirrored around the middle of the
-     */
-    reverseInPlace() { this._bcurve.reverseInPlace(); }
-    /**
-     * Return an array with this curve's bezier fragments.
+     * Reverse the curve in place.
+     * * Poles are reversed.
+     * * Knot values are mirrored around the middle of the knot array.
      */
+    reverseInPlace() {
+        this._bcurve.reverseInPlace();
+    }
+    /** Return an array with this curve's Bezier fragments. */
     collectBezierSpans(prefer3dH) {
         const result = [];
         const numSpans = this.numSpan;
@@ -188,17 +216,18 @@ export class BSplineCurve3dBase extends CurvePrimitive {
             return poleIndex * this._bcurve.poleLength;
         return undefined;
     }
-    /** Search for the curve point that is closest to the spacePoint.
-     *
+    /**
+     * Search for the curve point that is closest to the spacePoint.
      * * If the space point is exactly on the curve, this is the reverse of fractionToPoint.
-     * * Since CurvePrimitive should always have start and end available as candidate points, this method should always succeed
-     * @param spacePoint point in space
+     * * Since CurvePrimitive should always have start and end available as candidate points, this method should always
+     * succeed.
+     * @param spacePoint point in space.
      * @param _extend ignored (pass false). A BSplineCurve3dBase cannot be extended.
      * @param result optional pre-allocated detail to populate and return.
      * @returns details of the closest point.
      */
     closestPoint(spacePoint, _extend, result) {
-        // seed at start point -- final point comes with final bezier perpendicular step.
+        // seed at start point; final point comes with final bezier perpendicular step
         const point = this.fractionToPoint(0);
         result = CurveLocationDetail.createCurveFractionPointDistance(this, 0.0, point, point.distance(spacePoint), result);
         let span;
@@ -207,9 +236,9 @@ export class BSplineCurve3dBase extends CurvePrimitive {
             if (this._bcurve.knots.isIndexOfRealSpan(i)) {
                 span = this.getSaturatedBezierSpan3dOr3dH(i, true, span);
                 if (span) {
-                    // umm ... if the bspline is discontinuous, both ends should be tested.  Ignore that possibility ...
+                    // if the B-spline is discontinuous, both ends should be tested; ignore that possibility
                     if (span.updateClosestPointByTruePerpendicular(spacePoint, result, false, true)) {
-                        // the detail records the span bezier -- promote it to the parent curve . ..
+                        // the detail records the span bezier; promote it to the parent curve
                         result.curve = this;
                         result.fraction = span.fractionToParentFraction(result.fraction);
                     }
@@ -220,13 +249,14 @@ export class BSplineCurve3dBase extends CurvePrimitive {
     }
     /** Return a transformed deep clone. */
     cloneTransformed(transform) {
-        const curve1 = this.clone();
-        curve1.tryTransformInPlace(transform);
-        return curve1;
+        const curve = this.clone();
+        curve.tryTransformInPlace(transform);
+        return curve;
     }
-    /** Return a curve primitive which is a portion of this curve.
-     * @param fractionA [in] start fraction
-     * @param fractionB [in] end fraction
+    /**
+     * Return a curve primitive which is a portion of this curve.
+     * @param fractionA start fraction.
+     * @param fractionB end fraction.
      */
     clonePartialCurve(fractionA, fractionB) {
         const clone = this.clone();
@@ -237,11 +267,8 @@ export class BSplineCurve3dBase extends CurvePrimitive {
         clone._bcurve.addKnot(knotB, clone.degree);
         if (origNumKnots === clone._bcurve.knots.knots.length)
             return clone; // full curve
-        if (knotA > knotB) {
-            const tmp = knotA;
-            knotA = knotB;
-            knotB = tmp;
-        }
+        if (knotA > knotB)
+            [knotA, knotB] = [knotB, knotA];
         // choose first/last knot and pole such that knotA/knotB has degree multiplicity in the new knot sequence
         const iStartKnot = clone._bcurve.knots.knotToLeftKnotIndex(knotA) - clone.degree + 1;
         const iStartPole = iStartKnot * clone._bcurve.poleLength;
@@ -251,15 +278,17 @@ export class BSplineCurve3dBase extends CurvePrimitive {
             iLastKnotLeftMultiple = iLastKnot + 1;
         const iEndPole = (iLastKnotLeftMultiple + 1) * clone._bcurve.poleLength; // one past last pole
         const iEndKnot = iLastKnotLeftMultiple + clone.degree; // one past last knot
-        // trim the arrays (leave knots unnormalized!)
+        // trim the arrays (leave knots unnormalized)
         clone._bcurve.knots.setKnotsCapture(clone._bcurve.knots.knots.slice(iStartKnot, iEndKnot));
         clone._bcurve.packedData = clone._bcurve.packedData.slice(iStartPole, iEndPole);
         clone.setWrappable(BSplineWrapMode.None); // always open
         return clone;
     }
-    /** Implement `CurvePrimitive.appendPlaneIntersections`
-     * @param plane A plane (e.g. specific type Plane3dByOriginAndUnitNormal or Point4d)
-     * @param result growing array of plane intersections
+    /**
+     * Implement `CurvePrimitive.appendPlaneIntersections` to compute intersections of the curve with a plane.
+     * @param plane the plane with which to intersect the curve. Concrete types include [[Plane3dByOriginAndUnitNormal]],
+     * [[Point4d]], etc.
+     * @param result growing array of plane intersections.
      * @return number of intersections appended to the array.
     */
     appendPlaneIntersectionPoints(plane, result) {
@@ -270,34 +299,32 @@ export class BSplineCurve3dBase extends CurvePrimitive {
         const point4d = Point4d.create();
         // compute all pole altitudes from the plane
         const minMax = Range1d.createNull();
-        // Put the altitudes of all the bspline poles in one array.
+        // put the altitudes of all the B-spline poles in one array
         for (let i = 0; i < numPole; i++) {
             allCoffs[i] = plane.weightedAltitude(this.getPolePoint4d(i, point4d));
             minMax.extendX(allCoffs[i]);
         }
-        // A univariate bspline through the altitude poles gives altitude as function of the bspline knot.
+        // A univariate B-spline through the altitude poles gives altitude as function of the B-spline knot.
         // The (bspline) altitude function for each span is `order` consecutive altitudes.
         // If those altitudes bracket zero, the span may potentially have a crossing.
-        // When that occurs,
         let univariateBezier;
         let numFound = 0;
         let previousFraction = -1000.0;
         if (minMax.containsX(0.0)) {
             for (let spanIndex = 0; spanIndex < numSpan; spanIndex++) {
-                if (this._bcurve.knots.isIndexOfRealSpan(spanIndex)) { // ignore trivial knot intervals.
+                if (this._bcurve.knots.isIndexOfRealSpan(spanIndex)) { // ignore trivial knot intervals
                     // outer range test ...
                     minMax.setNull();
                     minMax.extendArraySubset(allCoffs, spanIndex, order);
                     if (minMax.containsX(0.0)) {
-                        // pack the bspline support into a univariate bezier ...
+                        // pack the B-spline support into a univariate bezier
                         univariateBezier = UnivariateBezier.createArraySubset(allCoffs, spanIndex, order, univariateBezier);
                         // saturate and solve the bezier
                         Bezier1dNd.saturate1dInPlace(univariateBezier.coffs, this._bcurve.knots, spanIndex);
                         const roots = univariateBezier.roots(0.0, true);
                         if (roots) {
                             for (const spanFraction of roots) {
-                                // promote each local bezier fraction to global fraction.
-                                // save the curve evaluation at that fraction.
+                                // promote each local bezier fraction to global fraction and save the curve evaluation at that fraction
                                 numFound++;
                                 const fraction = this._bcurve.knots.spanFractionToFraction(spanIndex, spanFraction);
                                 if (!Geometry.isAlmostEqualNumber(fraction, previousFraction)) {
@@ -316,9 +343,7 @@ export class BSplineCurve3dBase extends CurvePrimitive {
     }
     /**
      * Construct an offset of the instance curve as viewed in the xy-plane (ignoring z).
-     * * No attempt is made to join the offsets of smaller constituent primitives. To construct a fully joined offset
-     *   for an aggregate instance (e.g., LineString3d, CurveChainWithDistanceIndex), use RegionOps.constructCurveXYOffset() instead.
-     * @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 options object.
      */
     constructOffsetXY(offsetDistanceOrOptions) {
         const options = OffsetOptions.create(offsetDistanceOrOptions);
@@ -326,18 +351,21 @@ export class BSplineCurve3dBase extends CurvePrimitive {
         this.emitStrokableParts(handler, options.strokeOptions);
         return handler.claimResult();
     }
-    /** Project instance geometry (via dispatch) onto the given ray, and return the extreme fractional parameters of projection.
+    /**
+     * 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
-     * @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.
+     * @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);
     }
 }
 /**
- * A BSplineCurve3d is a bspline curve whose poles are Point3d.
- * See BSplineCurve3dBase for description of knots, order, degree.
+ * A BSplineCurve3d is a B-spline curve whose poles are Point3d.
+ * See BSplineCurve3dBase for description of knots, order, degree, and poles.
  * @public
  */
 export class BSplineCurve3d extends BSplineCurve3dBase {
@@ -347,11 +375,19 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
             this._workBezier = BezierCurve3d.createOrder(this.order);
         return this._workBezier;
     }
-    /** test of `other` is an instance of BSplineCurve3d */
-    isSameGeometryClass(other) { return other instanceof BSplineCurve3d; }
+    constructor(numPoles, order, knots) {
+        super(3, numPoles, order, knots);
+    }
+    /** Test if `other` is an instance of BSplineCurve3d. */
+    isSameGeometryClass(other) {
+        return other instanceof BSplineCurve3d;
+    }
     /** Apply `transform` to the poles. */
-    tryTransformInPlace(transform) { Point3dArray.multiplyInPlace(transform, this._bcurve.packedData); return true; }
-    /** Get a pole as simple Point3d. */
+    tryTransformInPlace(transform) {
+        Point3dArray.multiplyInPlace(transform, this._bcurve.packedData);
+        return true;
+    }
+    /** Get a pole as a simple Point3d. */
     getPolePoint3d(poleIndex, result) {
         const k = this.poleIndexToDataIndex(poleIndex);
         if (k !== undefined) {
@@ -360,7 +396,7 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
         return undefined;
     }
-    /** Get a pole as Point4d with weight 1 */
+    /** Get a pole as Point4d with weight 1. */
     getPolePoint4d(poleIndex, result) {
         const k = this.poleIndexToDataIndex(poleIndex);
         if (k !== undefined) {
@@ -369,23 +405,26 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
         return undefined;
     }
-    /** Convert  `spanIndex` and `localFraction` to a knot. */
-    spanFractionToKnot(span, localFraction) {
-        return this._bcurve.spanFractionToKnot(span, localFraction);
-    }
-    constructor(numPoles, order, knots) {
-        super(3, numPoles, order, knots);
-    }
-    /** Return a simple array of arrays with the control points as `[[x,y,z],[x,y,z],..]` */
-    copyPoints() { return Point3dArray.unpackNumbersToNestedArrays(this._bcurve.packedData, 3); }
-    /** Return a simple array of the control points coordinates */
-    copyPointsFloat64Array() { return this._bcurve.packedData.slice(); }
     /**
-     * return a simple array form of the knots.  optionally replicate the first and last
-     * in classic over-clamped manner
+     * Convert the fractional position in the given span to a knot.
+     * * The returned value is not necessarily a knot, but it is a valid parameter in the domain of the B-spline curve.
      */
-    copyKnots(includeExtraEndKnot) { return this._bcurve.knots.copyKnots(includeExtraEndKnot); }
-    /** Create a bspline with uniform knots. */
+    spanFractionToKnot(spanIndex, spanFraction) {
+        return this._bcurve.spanFractionToKnot(spanIndex, spanFraction);
+    }
+    /** Return a simple array of arrays with the poles as `[[x,y,z],[x,y,z],..]`. */
+    copyPoints() {
+        return Point3dArray.unpackNumbersToNestedArrays(this._bcurve.packedData, 3);
+    }
+    /** Return a simple array of poles' coordinates. */
+    copyPointsFloat64Array() {
+        return this._bcurve.packedData.slice();
+    }
+    /** Return a simple array form of the knots. Optionally replicate the first and last in classic over-clamped manner. */
+    copyKnots(includeExtraEndKnot) {
+        return this._bcurve.knots.copyKnots(includeExtraEndKnot);
+    }
+    /** Create a B-spline with uniform knots. */
     static createUniformKnots(poles, order) {
         const numPoles = poles instanceof Float64Array ? poles.length / 3 : poles.length;
         if (order < 2 || numPoles < order)
@@ -409,9 +448,10 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
         return curve;
     }
-    /** Create a smoothly closed B-spline curve with uniform knots.
-     *  Note that the curve does not start at the first pole!
-    */
+    /**
+     * Create a smoothly closed B-spline curve with uniform knots.
+     * * Note that the curve does not start at the first pole.
+     */
     static createPeriodicUniformKnots(poles, order) {
         if (order < 2)
             return undefined;
@@ -482,21 +522,23 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         return BSplineCurveOps.createThroughPointsC2Cubic(options);
     }
     /**
-     *
+     * Create a B-spline curve from an Akima curve.
      * @param options collection of points and end conditions.
      */
     static createFromAkimaCurve3dOptions(options) {
         return BSplineCurveOps.createThroughPoints(options.fitPoints, 4); // temporary
     }
     /**
-     * Create a bspline with given knots.
+     * Create a B-spline curve with given knots.
      * * The poles have several variants:
-     *    * Float64Array(3 * numPoles) in blocks of [x,y,z]
-     *    * Point3d[]
-     *    * number[][], with inner dimension 3
+     *    * Float64Array(3 * numPoles) in blocks of [x,y,z].
+     *    * Point3d[].
+     *    * number[][], with inner dimension 3.
      * * Two count conditions are recognized:
-     *    * If poleArray.length + order === knotArray.length, the first and last are assumed to be the extraneous knots of classic clamping.
+     *    * If poleArray.length + order === knotArray.length, the first and last are assumed to be the extraneous knots
+     *      of classic clamping.
      *    * If poleArray.length + order === knotArray.length + 2, the knots are in modern form.
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/BSpline/
      */
     static create(poleArray, knotArray, order) {
         if (order < 2)
@@ -534,31 +576,42 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
         return curve;
     }
-    /** Return a deep clone */
+    /** Return a deep clone. */
     clone() {
-        const knotVector1 = this._bcurve.knots.clone();
-        const curve1 = new BSplineCurve3d(this.numPoles, this.order, knotVector1);
-        curve1._bcurve.packedData = this._bcurve.packedData.slice();
-        return curve1;
+        const knotVector = this._bcurve.knots.clone();
+        const curve = new BSplineCurve3d(this.numPoles, this.order, knotVector);
+        curve._bcurve.packedData = this._bcurve.packedData.slice();
+        return curve;
     }
-    /** Evaluate at a position given by fractional position within a span. */
+    /** Evaluate the curve at a fractional position within a given span. */
     evaluatePointInSpan(spanIndex, spanFraction) {
         this._bcurve.evaluateBuffersInSpan(spanIndex, spanFraction);
         return Point3d.createFrom(this._bcurve.poleBuffer);
     }
-    /** Evaluate point and derivative vector at a position given by fractional position within a span.
-     * * The derivative is with respect to the span fraction (NOT scaled to either global fraction or knot)
+    /**
+     * Evaluate the curve and derivative at a fractional position within a given span.
+     * * The derivative is with respect to the span fractional parameter, _not_ to the curve's parameter or fractional parameter.
      */
     evaluatePointAndDerivativeInSpan(spanIndex, spanFraction) {
         this._bcurve.evaluateBuffersInSpan1(spanIndex, spanFraction);
         return Ray3d.createCapture(Point3d.createFrom(this._bcurve.poleBuffer), Vector3d.createFrom(this._bcurve.poleBuffer1));
     }
-    /** Evaluate at a position given by a knot value.  */
+    /**
+     * Evaluate the curve at the given parameter.
+     * @param u parameter in curve domain.
+     * @param result optional result.
+     * @returns the point on the curve.
+     */
     knotToPoint(u, result) {
         this._bcurve.evaluateBuffersAtKnot(u);
         return Point3d.createFrom(this._bcurve.poleBuffer, result);
     }
-    /** Evaluate at a position given by a knot value.  */
+    /**
+     * Evaluate the curve and derivative at the given parameter.
+     * @param u parameter in curve domain.
+     * @param result optional result.
+     * @returns the ray with origin at the curve point and direction as the derivative.
+     */
     knotToPointAndDerivative(u, result) {
         this._bcurve.evaluateBuffersAtKnot(u, 1);
         if (!result)
@@ -567,12 +620,17 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         result.direction.setFrom(this._bcurve.poleBuffer1);
         return result;
     }
-    /** Evaluate at a position given by a knot value.  Return point with 2 derivatives. */
+    /**
+     * Evaluate the curve and two derivatives at the given parameter.
+     * @param u parameter in the curve domain.
+     * @param result optional result.
+     * @returns the plane with origin at the curve point, vectorU as the 1st derivative, and vectorV as the 2nd derivative.
+     */
     knotToPointAnd2Derivatives(u, result) {
         this._bcurve.evaluateBuffersAtKnot(u, 2);
         return Plane3dByOriginAndVectors.createOriginAndVectorsXYZ(this._bcurve.poleBuffer[0], this._bcurve.poleBuffer[1], this._bcurve.poleBuffer[2], this._bcurve.poleBuffer1[0], this._bcurve.poleBuffer1[1], this._bcurve.poleBuffer1[2], this._bcurve.poleBuffer2[0], this._bcurve.poleBuffer2[1], this._bcurve.poleBuffer2[2], result);
     }
-    /** test if almost the same curve as `other` */
+    /** Test if `this` is almost the same curve as `other`. */
     isAlmostEqual(other) {
         if (other instanceof BSplineCurve3d) {
             return this._bcurve.knots.isAlmostEqual(other._bcurve.knots)
@@ -580,15 +638,19 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
         return false;
     }
-    /** test if this curve is entirely within plane. */
+    /** Test if this curve lies entirely in the given plane. */
     isInPlane(plane) {
         return Point3dArray.isCloseToPlane(this._bcurve.packedData, plane);
     }
-    /** Return the control polygon length as approximation (always overestimate) of the curve length. */
-    quickLength() { return Point3dArray.sumEdgeLengths(this._bcurve.packedData); }
-    /** Emit beziers or strokes (selected by the stroke options) to the handler. */
+    /**
+     * Return the control polygon length as an approximation to the curve length.
+     * * The returned length is always an overestimate.
+     */
+    quickLength() {
+        return Point3dArray.sumEdgeLengths(this._bcurve.packedData);
+    }
+    /** Emit Beziers or strokes (selected by the stroke options) to the handler. */
     emitStrokableParts(handler, options) {
-        const needBeziers = handler.announceBezierCurve !== undefined;
         const workBezier = this.initializeWorkBezier();
         const numSpan = this.numSpan;
         let numStrokes;
@@ -596,7 +658,7 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
             const bezier = this.getSaturatedBezierSpan3dOr3dH(spanIndex, false, workBezier);
             if (bezier) {
                 numStrokes = bezier.computeStrokeCountForOptions(options);
-                if (needBeziers) {
+                if (handler.announceBezierCurve) {
                     handler.announceBezierCurve(bezier, numStrokes, this, spanIndex, this._bcurve.knots.spanFractionToFraction(spanIndex, 0.0), this._bcurve.knots.spanFractionToFraction(spanIndex, 1.0));
                 }
                 else {
@@ -621,7 +683,7 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         return numStroke;
     }
     /**
-     * Compute individual segment stroke counts.  Attach in a StrokeCountMap.
+     * Compute individual segment stroke counts. Attach in a StrokeCountMap.
      * @param options StrokeOptions that determine count
      * @param parentStrokeMap evolving parent map.
      * @alpha
@@ -640,7 +702,7 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
         CurvePrimitive.installStrokeCountMap(this, myData, parentStrokeMap);
     }
-    /** Append strokes to a linestring. */
+    /** Append strokes to the given linestring. */
     emitStrokes(dest, options) {
         const workBezier = this.initializeWorkBezier();
         const numSpan = this.numSpan;
@@ -651,16 +713,17 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         }
     }
     /**
-     * Test knots and control points to determine if it is possible to close (aka "wrap") the curve.
+     * Test knots and poles to determine if it is possible to close (aka "wrap") the curve.
      * @returns the manner in which it is possible to close the curve. See `BSplineWrapMode` for particulars of each mode.
      */
     get isClosable() {
         return this.isClosableCurve;
     }
     /**
-     * Return a BezierCurveBase for this curve.  The concrete return type may be BezierCurve3d or BezierCurve3dH according to this type.
-     * @param spanIndex
-     * @param result optional reusable curve.  This will only be reused if it is a BezierCurve3d with matching order.
+     * Return the Bezier fragment corresponding to the given span of this curve.
+     * * The concrete return type may be [[BezierCurve3d]] or [[BezierCurve3dH]] according to the instance type and `prefer3dH`.
+     * @param spanIndex index of span.
+     * @param result optional reusable curve. This will only be reused if its type and order matches.
      */
     getSaturatedBezierSpan3dOr3dH(spanIndex, prefer3dH, result) {
         if (prefer3dH)
@@ -668,9 +731,9 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         return this.getSaturatedBezierSpan3d(spanIndex, result);
     }
     /**
-     * Return a CurvePrimitive (which is a BezierCurve3d) for a specified span of this curve.
-     * @param spanIndex
-     * @param result optional reusable curve.  This will only be reused if it is a BezierCurve3d with matching order.
+     * Return the Bezier fragment corresponding to the given span of this curve.
+     * @param spanIndex index of span.
+     * @param result optional reusable curve. This will only be reused if its type and order matches.
      */
     getSaturatedBezierSpan3d(spanIndex, result) {
         if (spanIndex < 0 || spanIndex >= this.numSpan)
@@ -681,13 +744,13 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
         const bezier = result;
         bezier.loadSpanPoles(this._bcurve.packedData, spanIndex);
         if (bezier.saturateInPlace(this._bcurve.knots, spanIndex))
-            return result;
+            return bezier;
         return undefined;
     }
     /**
-     * Return a CurvePrimitive (which is a BezierCurve3dH) for a specified span of this curve.
-     * @param spanIndex
-     * @param result optional reusable curve.  This will only be reused if it is a BezierCurve3d with matching order.
+     * Return the Bezier fragment corresponding to the given span of this curve.
+     * @param spanIndex index of span.
+     * @param result optional reusable curve. This will only be reused if its type and order matches.
      */
     getSaturatedBezierSpan3dH(spanIndex, result) {
         if (spanIndex < 0 || spanIndex >= this.numSpan)
@@ -701,15 +764,16 @@ export class BSplineCurve3d extends BSplineCurve3dBase {
             return bezier;
         return undefined;
     }
-    /** Second step of double dispatch:  call `handler.handleBSplineCurve3d(this)` */
+    /** Second step of double dispatch: call `handler.handleBSplineCurve3d(this)`. */
     dispatchToGeometryHandler(handler) {
         return handler.handleBSplineCurve3d(this);
     }
     /**
-     * Extend a range so in includes the range of this curve
-     * * REMARK: this is based on the poles, not the exact curve.  This is generally larger than the true curve range.
-     * @param rangeToExtend
-     * @param transform transform to apply to points as they are entered into the range.
+     * Extend a range so it contains the range of this curve.
+     * * This computation is based on the poles, not the curve itself, so the returned range is generally larger than the
+     * tightest possible range.
+     * @param rangeToExtend range to extend.
+     * @param transform transform to apply to the poles as they are entered into the range.
      */
     extendRange(rangeToExtend, transform) {
         const buffer = this._bcurve.packedData;