@itwin/core-geometry 5.0.0-dev.8 → 5.0.0-dev.83

package/lib/esm/bspline/KnotVector.js

@@ -5,6 +5,7 @@
 /** @packageDocumentation
  * @module Bspline
  */
+import { assert } from "@itwin/core-bentley";
 import { Geometry } from "../Geometry";
 import { NumberArray } from "../geometry3d/PointHelpers";
 /**
@@ -16,59 +17,89 @@ export var BSplineWrapMode;
 (function (BSplineWrapMode) {
     /** No conversion performed. */
     BSplineWrapMode[BSplineWrapMode["None"] = 0] = "None";
-    /** The B-spline was opened up by adding degree wrap-around control points to the legacy periodic data.
-     * * This is typical of B-splines constructed with maximum (degree - 1) continuity.
+    /**
+     * The legacy periodic B-spline data was opened up by adding `degree` wrap-around poles.
+     * * This is typical of B-spline curves and surfaces constructed with maximum `degree - 1` continuity.
      * * Knots are unaffected by this conversion.
      */
     BSplineWrapMode[BSplineWrapMode["OpenByAddingControlPoints"] = 1] = "OpenByAddingControlPoints";
-    /** The B-spline was opened up by removing degree extreme knots from the legacy periodic data.
+    /**
+     * The legacy periodic B-spline data was opened up by removing `degree` exterior knots.
      * * This is typical of rational B-spline curves representing full circles and ellipses.
      * * Poles are unaffected by this conversion.
      */
     BSplineWrapMode[BSplineWrapMode["OpenByRemovingKnots"] = 2] = "OpenByRemovingKnots";
 })(BSplineWrapMode || (BSplineWrapMode = {}));
 /**
- * Array of non-decreasing numbers acting as a knot array for B-splines.
+ * Array of non-decreasing numbers acting as a knot vector for B-spline curves and surfaces.
  *
  * * Essential identity: numKnots = numPoles + order - 2 = numPoles + degree - 1
- * * Various B-spline libraries have confusion over how many "end knots" are needed. Many libraries (including MicroStation and Parasolid)
- * demand order knots at each end for clamping. But only order-1 are really needed. This class uses the order-1 convention.
+ * * Various B-spline libraries have confusion over how many "end knots" are needed. Many libraries (including MicroStation
+ * and Parasolid) demand order knots at each end for clamping. However, only order-1 are really needed. This class uses the
+ * order-1 convention.
  * * A span is a single interval of the knots.
- * * The left knot of span {k} is knot {k+degree-1}.
+ * * The left knot of the span with index `k>=0` is the knot with index `k+degree-1`.
+ * * A knot vector is clamped when the first `degree` knots are equal and the last `degree` knots are equal.
+ * * The "active knot interval" is the subset of the knot vector sans its first and last `degree-1` knots, and serves as
+ * the parametric domain of the associated B-spline object.
  * * This class provides queries to convert among spanIndex, knotIndex, spanFraction, fraction of knot range, and knot.
- * * Core computations (evaluateBasisFunctions) have leftKnotIndex and global knot value as inputs.  Callers need to
- * know their primary values (global knot, spanFraction).
+ * * Callers need to distinguish core computational inputs such as left knot index, knot value, span index, and span fraction.
  * @public
  */
 export class KnotVector {
-    /** Return the leftmost knot value (of the active interval, ignoring unclamped leading knots)*/
-    get leftKnot() { return this._knot0; }
-    /** Return the rightmost knot value (of the active interval, ignoring unclamped leading knots)*/
-    get rightKnot() { return this._knot1; }
-    /** Return the index of the leftmost knot of the active interval */
-    get leftKnotIndex() { return this.degree - 1; }
-    /** Return the index of the rightmost knot of the active interval */
-    get rightKnotIndex() { return this.knots.length - this.degree; }
-    /** Whether this KnotVector was created by converting legacy periodic data during deserialization. The conversion used is specified by BSplineWrapMode, and is reversed at serialization time. */
-    get wrappable() { return this._wrapMode === undefined ? BSplineWrapMode.None : this._wrapMode; }
-    set wrappable(value) { this._wrapMode = value; }
-    /** Return the number of bezier spans.  Note that this includes zero-length spans if there are repeated knots. */
-    get numSpans() { return this.rightKnotIndex - this.leftKnotIndex; }
+    /** The simple array of knot values. */
+    knots;
+    /** The degree of basis functions defined in these knots. */
+    degree;
+    /** The leftmost knot value (of the active interval, ignoring unclamped leading knots). */
+    _knot0;
+    /** The rightmost knot value (of the active interval, ignoring unclamped leading knots). */
+    _knot1;
+    _wrapMode;
+    /** Tolerance for considering two knots to be the same. */
+    static knotTolerance = 1.0e-9;
+    /** Return the leftmost knot value (of the active interval, ignoring unclamped leading knots). */
+    get leftKnot() {
+        return this._knot0;
+    }
+    /** Return the rightmost knot value (of the active interval, ignoring unclamped leading knots). */
+    get rightKnot() {
+        return this._knot1;
+    }
+    /** Return the index of the leftmost knot of the active interval. */
+    get leftKnotIndex() {
+        return this.degree - 1;
+    }
+    /** Return the index of the rightmost knot of the active interval. */
+    get rightKnotIndex() {
+        return this.knots.length - this.degree;
+    }
+    /**
+     * Whether this KnotVector was created by converting legacy periodic data during deserialization. The conversion used
+     * is specified by BSplineWrapMode, and is reversed at serialization time.
+     */
+    get wrappable() {
+        return this._wrapMode === undefined ? BSplineWrapMode.None : this._wrapMode;
+    }
+    set wrappable(value) {
+        this._wrapMode = value;
+    }
+    /** Return the number of Bezier spans. Note that this includes zero-length spans if there are repeated knots. */
+    get numSpans() {
+        return this.rightKnotIndex - this.leftKnotIndex;
+    }
     /**
-     *
-     * * If knots is a number array or Float64Array, the those values become the local knot array.
-     * * If knots is a simple number, the local knot array is allocated to that size but left as zeros.
-     * @param knots
-     * @param degree
+     * Private constructor.
+     * * If `knots` is a number array or Float64Array, then its values are copied to the instance array.
+     * * If `knots` is a number, the instance array is allocated to this size but left as zeros.
      */
     constructor(knots, degree, wrapMode) {
         this.degree = degree;
         this._wrapMode = wrapMode;
-        // default values to satisfy compiler -- real values happen in setupFixedValues, or final else defers to user
+        // default values to satisfy compiler; real values happen in setupFixedValues or the final else clause defers to user
         this._knot0 = 0.0;
         this._knot1 = 1.0;
-        // satisfy the initialize checker ..
-        if (Array.isArray(knots)) { // remark:  This ctor is private.  The callers (as of April 2019) do not use this path.
+        if (Array.isArray(knots)) {
             this.knots = new Float64Array(knots.length);
             this.setKnots(knots);
             this.setupFixedValues();
@@ -77,23 +108,32 @@ export class KnotVector {
             this.knots = knots.slice();
             this.setupFixedValues();
         }
-        else { // caller is responsible for filling array separately ...
-            this.knots = new Float64Array(knots);
+        else { // caller is responsible for filling array separately
+            const knotSize = knots;
+            this.knots = new Float64Array(knotSize);
         }
     }
-    /** copy degree and knots to a new KnotVector. */
-    clone() { return new KnotVector(this.knots, this.degree, this.wrappable); }
+    /** Copy degree and knots to a new KnotVector. */
+    clone() {
+        return new KnotVector(this.knots, this.degree, this.wrappable);
+    }
     setupFixedValues() {
         if (this.degree > 0 && this.knots.length > this.degree) {
             this._knot0 = this.knots[this.degree - 1];
             this._knot1 = this.knots[this.knots.length - this.degree];
         }
     }
-    /** Return the total knot distance from beginning to end. */
-    get knotLength01() { return this._knot1 - this._knot0; }
     /**
-     * Returns true if all numeric values have wraparound conditions that allow the knots to be closed with specified wrap mode.
-     * @param mode optional test mode.  If undefined, use this.wrappable.
+     * Return the length of the active knot interval.
+     * * This is the size of (one dimension of) the parametric domain for the associated B-spline object.
+     */
+    get knotLength01() {
+        return this._knot1 - this._knot0;
+    }
+    /**
+     * Returns true if all numeric values have wraparound conditions that allow the knots to be closed with specified
+     * wrap mode.
+     * @param mode optional test mode. If undefined, use this.wrappable.
      */
     testClosable(mode) {
         if (mode === undefined)
@@ -127,7 +167,7 @@ export class KnotVector {
         }
         return false;
     }
-    /** Test matching degree and knot values */
+    /** Test matching degree and knot values. */
     isAlmostEqual(other) {
         if (this.degree !== other.degree)
             return false;
@@ -167,8 +207,9 @@ export class KnotVector {
         }
         return m;
     }
-    /** Transform knots to span [0,1].
-     * @returns false if and only if this.knotLength01 is trivial
+    /**
+     * Transform knots such that the active knot range becomes [0,1].
+     * @returns false if and only if `this.knotLength01` is trivial.
      */
     normalize() {
         if (this.knotLength01 < KnotVector.knotTolerance)
@@ -186,8 +227,7 @@ export class KnotVector {
         this.setupFixedValues();
         return true;
     }
-    /** install knot values from an array, optionally ignoring first and last.
-     */
+    /** Install knot values from an array, optionally ignoring first and last. */
     setKnots(knots, skipFirstAndLast) {
         const numAllocate = skipFirstAndLast ? knots.length - 2 : knots.length;
         if (numAllocate !== this.knots.length)
@@ -202,17 +242,17 @@ export class KnotVector {
         }
         this.setupFixedValues();
     }
-    /** Set knots to input array (CAPTURED)  */
+    /** Set knots to input array (CAPTURED).  */
     setKnotsCapture(knots) {
         this.knots = knots;
         this.setupFixedValues();
     }
     /**
      * Create knot vector with {degree-1} replicated knots at start and end, and uniform knots between.
-     * @param numPoles Number of poles
-     * @param degree degree of polynomial
-     * @param a0 left knot value for active interval
-     * @param a1 right knot value for active interval
+     * @param numPoles number of poles.
+     * @param degree degree of polynomial.
+     * @param a0 left knot value for active interval.
+     * @param a1 right knot value for active interval.
      */
     static createUniformClamped(numPoles, degree, a0, a1) {
         const knots = new KnotVector(numPoles + degree - 1, degree);
@@ -229,24 +269,26 @@ export class KnotVector {
     }
     /**
      * Create knot vector with wraparound knots at start and end, and uniform knots between.
-     * @param  numInterval number of intervals in knot space.  (NOT POLE COUNT)
-     * @param degree degree of polynomial
-     * @param a0 left knot value for active interval
-     * @param a1 right knot value for active interval
+     * @param numInterval the number of intervals into which to uniformly divide the active knot interval `[a0,a1]`,
+     * creating `numInterval-1` equally spaced interior knots between `a0` and `a1`.
+     * This number is equal to the number of Bezier spans in the associated B-spline object.
+     * It is _not_ the pole count.
+     * @param degree degree of polynomial.
+     * @param a0 left knot value for active interval.
+     * @param a1 right knot value for active interval.
      */
     static createUniformWrapped(numInterval, degree, a0, a1) {
         const knots = new KnotVector(numInterval + 2 * degree - 1, degree);
         const du = 1.0 / numInterval;
-        for (let i = 1 - degree, k = 0; i < numInterval + degree; i++, k++) {
+        for (let i = 1 - degree, k = 0; i < numInterval + degree; i++, k++)
             knots.knots[k] = Geometry.interpolate(a0, i * du, a1);
-        }
         knots.setupFixedValues();
         return knots;
     }
     /**
      * Create knot vector with given knot values and degree.
-     * @param knotArray knot values
-     * @param degree degree of polynomial
+     * @param knotArray knot values.
+     * @param degree degree of polynomial.
      * @param skipFirstAndLast true to skip copying the first and last knot values.
      */
     static create(knotArray, degree, skipFirstAndLast) {
@@ -257,19 +299,24 @@ export class KnotVector {
     }
     /**
      * Return the average of degree consecutive knots beginning at knotIndex.
+     * * If `knotIndex` is negative, return `leftKnot`.
+     * * If `knotIndex > rightKnotIndex` return `rightKnot`.
      */
     grevilleKnot(knotIndex) {
         if (knotIndex < 0)
             return this.leftKnot;
         if (knotIndex > this.rightKnotIndex)
             return this.rightKnot;
+        knotIndex = Math.floor(knotIndex);
         let sum = 0.0;
         for (let i = knotIndex; i < knotIndex + this.degree; i++)
             sum += this.knots[i];
         return sum / this.degree;
     }
-    /** Return an array sized for a set of the basis function values. */
-    createBasisArray() { return new Float64Array(this.degree + 1); }
+    /** Return an array of size `degree + 1`, e.g., to hold the set of relevant basis function values at a parameter. */
+    createBasisArray() {
+        return new Float64Array(this.degree + 1);
+    }
     /** Convert localFraction within the interval following an indexed knot to a knot value. */
     baseKnotFractionToKnot(knotIndex0, localFraction) {
         const knot0 = this.knots[knotIndex0];
@@ -292,29 +339,38 @@ export class KnotVector {
         fraction = Geometry.clamp(fraction, 0, 1); // B-splines are not extendable
         return Geometry.interpolate(this.knots[this.degree - 1], fraction, this.knots[this.knots.length - this.degree]);
     }
+    isKnotInValidSpan(knotIndex0, u) {
+        const spanIsValid = knotIndex0 >= this.degree - 1 && knotIndex0 + this.degree < this.knots.length;
+        const uIsInSpan = this.knots[knotIndex0] <= u && u <= this.knots[knotIndex0 + 1];
+        return spanIsValid && uIsInSpan;
+    }
     /**
-     * Evaluate basis functions f[] at knot value u.
-     *
-     * @param u knot value for evaluation
-     * @param f preallocated output array of order basis function values
-     * @returns true if and only if output array is sufficiently sized
+     * Evaluate the B-spline basis functions f[] at a parameter u in a knot span.
+     * * This method implements the Mansfield-Cox-de Boor recurrence relation.
+     * @param knotIndex0 index of the left knot of the span.
+     * @param u value in the knot span: knot[knotIndex0] <= u <= knot[knotIndex0 + 1].
+     * @param f preallocated output array of order basis function values.
+     * @returns true if and only if output array is sufficiently sized.
      */
     evaluateBasisFunctions(knotIndex0, u, f) {
         if (f.length < this.degree + 1)
             return false;
+        assert(() => this.isKnotInValidSpan(knotIndex0, u), "knot is in a valid span");
         f[0] = 1.0;
         if (this.degree < 1)
             return true;
-        // direct compute for linear part ...
+        // direct compute for linear part
         const u0 = this.knots[knotIndex0];
         const u1 = this.knots[knotIndex0 + 1];
         f[1] = (u - u0) / (u1 - u0);
         f[0] = 1.0 - f[1];
         if (this.degree < 2)
             return true;
+        // each iteration of the outer loop evaluates the basis functions of degree depth+1 using
+        // one or two values of the basis functions of one less degree from the preceding iteration
         for (let depth = 1; depth < this.degree; depth++) {
             let kLeft = knotIndex0 - depth;
-            let kRight = kLeft + depth + 1;
+            let kRight = knotIndex0 + 1;
             let gCarry = 0.0;
             for (let step = 0; step <= depth; step++) {
                 const tLeft = this.knots[kLeft++];
@@ -326,17 +382,20 @@ export class KnotVector {
                 gCarry = g1;
             }
             f[depth + 1] = gCarry;
+            // at this point, the head of f[] contains the depth+2 values at u
+            // of the basis functions of degree depth+1 with support over [u0,u1)
         }
         return true;
     }
     /**
-     * Evaluate basis functions f[], derivatives df[], and optional second derivatives ddf[] at knot value u.
-     *
-     * @param u knot value for evaluation
-     * @param f preallocated output array of order basis function values
-     * @param df preallocated output array of order basis derivative values
-     * @param ddf optional preallocated output array of order basis second derivative values
-     * @returns true if and only if output arrays are sufficiently sized
+     * Evaluate basis functions f[], derivatives df[], and optional second derivatives ddf[] at a parameter u
+     * in a knot span.
+     * @param knotIndex0 index of the left knot of the span.
+     * @param u value in the knot span: knot[knotIndex0] <= u <= knot[knotIndex0 + 1].
+     * @param f preallocated output array of order basis function values.
+     * @param df preallocated output array of order basis derivative values.
+     * @param ddf optional preallocated output array of order basis second derivative values.
+     * @returns true if and only if output arrays are sufficiently sized.
      */
     evaluateBasisFunctions1(knotIndex0, u, f, df, ddf) {
         if (f.length < this.degree + 1)
@@ -345,15 +404,16 @@ export class KnotVector {
             return false;
         if (ddf && ddf.length < this.degree + 1)
             return false;
+        assert(() => this.isKnotInValidSpan(knotIndex0, u), "knot is in a valid span");
         f[0] = 1.0;
         df[0] = 0.0;
         if (this.degree < 1)
             return true;
-        // direct compute for linear part ...
+        // direct compute for linear part
         const u0 = this.knots[knotIndex0];
         const u1 = this.knots[knotIndex0 + 1];
-        // ah = 1/(u1-u0)      is the derivative of fraction0
-        // (-ah) is the derivative of fraction1.
+        // ah = 1/(u1-u0) is the derivative of fraction0
+        // -ah is the derivative of fraction1
         let ah = 1.0 / (u1 - u0);
         f[1] = (u - u0) * ah;
         f[0] = 1.0 - f[1];
@@ -372,7 +432,7 @@ export class KnotVector {
             let dgCarry = 0.0;
             let ddgCarry = 0.0;
             // f, df, ddf, are each row vectors with product of `step` linear terms.
-            // f is multiplied on the right by matrix V.  Each row has 2 nonzero entries (which sum to 1)  (0,0,1-fraction, fraction,0,0,0)
+            // f is multiplied on the right by matrix V.  Each row has 2 nonzero entries (which sum to 1) (0,0,1-fraction, fraction,0,0,0)
             //    Each row of the derivative dV is two entries (0,0, -1/h, 1/h,0,0,0)
             // Hence fnew = f * V
             //      dfnew = df * V + f * dV
@@ -394,7 +454,7 @@ export class KnotVector {
                 df[step] = dgCarry + dg0;
                 gCarry = g1;
                 dgCarry = dg1;
-                if (ddf) { // do the backward reference to df before rewriting df !!!
+                if (ddf) { // do the backward reference to df before rewriting df
                     const ddg1 = ddf[step] * fraction + dfSave;
                     const ddg0 = ddf[step] * fraction1 - dfSave;
                     ddf[step] = ddgCarry + ddg0;
@@ -408,9 +468,10 @@ export class KnotVector {
         }
         return true;
     }
-    /** Find the knot span bracketing knots[i] <= u < knots[i+1] and return i.
+    /**
+     * Find the knot span bracketing knots[i] <= u < knots[i+1] and return i.
      * * If u has no such bracket, return the smaller index of the closest nontrivial bracket.
-     * @param u value to bracket
+     * @param u value to bracket.
      */
     knotToLeftKnotIndex(u) {
         for (let i = this.leftKnotIndex; i < this.rightKnotIndex; ++i) {
@@ -426,7 +487,7 @@ export class KnotVector {
     }
     /**
      * Given a span index, return the index of the knot at its left.
-     * @param spanIndex index of span
+     * @param spanIndex index of span.
      */
     spanIndexToLeftKnotIndex(spanIndex) {
         const d = this.degree;
@@ -441,7 +502,8 @@ export class KnotVector {
     }
     /**
      * Given a span index, test if it is within range and has nonzero length.
-     * * note that a false return does not imply there are no more spans.  This may be a double knot (zero length span) followed by more real spans
+     * * note that a false return does not imply there are no more spans. This may be a double knot (zero length span)
+     * followed by more real spans
      * @param spanIndex index of span to test.
      */
     isIndexOfRealSpan(spanIndex) {
@@ -449,7 +511,7 @@ export class KnotVector {
             return !Geometry.isSmallMetricDistance(this.spanIndexToSpanLength(spanIndex));
         return false;
     }
-    /** Reflect all knots so `leftKnot` and `rightKnot` are maintained but interval lengths reverse. */
+    /** Reflect all knots so `leftKnot` and `rightKnot` are maintained but interval lengths are reversed. */
     reflectKnots() {
         const a = this.leftKnot;
         const b = this.rightKnot;
@@ -490,6 +552,4 @@ export class KnotVector {
         return KnotVector.copyKnots(this.knots, this.degree, includeExtraEndKnot, wrapMode);
     }
 }
-/** tolerance for considering two knots to be the same. */
-KnotVector.knotTolerance = 1.0e-9;
 //# sourceMappingURL=KnotVector.js.map