@itwin/core-geometry 4.3.0-dev.2 → 4.3.0-dev.20

package/lib/esm/numerics/BezierPolynomials.js

@@ -86,14 +86,15 @@ export class BezierCoffs {
         for (let i = 0; i < this.coffs.length; i++)
             this.coffs[i] += a;
     }
-    /** Compute parameter values where the bezier value matches _targetValue.
+    /** Compute parameter values where the bezier value matches targetValue.
      * * The base class finds roots only in 01.  (i.e. ignores _restrictTo01)
-     * * Order-specific implementations apply special case  analytic logic, e.g. for degree 1,2,3,4.
+     * * Order-specific implementations apply special case analytic logic, e.g. for degree 1,2,3,4.
      */
     roots(targetValue, _restrictTo01) {
         const bezier = UnivariateBezier.create(this);
         bezier.addInPlace(-targetValue);
-        return UnivariateBezier.deflateRoots01(bezier);
+        const roots = UnivariateBezier.deflateRoots(bezier);
+        return this.filter01(roots, true);
     }
     /** Given an array of numbers, optionally remove those not in the 0..1 interval.
      * @param roots candidate values
@@ -121,7 +122,9 @@ export class BezierCoffs {
         return undefined;
     }
     /** zero out all coefficients. */
-    zero() { this.coffs.fill(0); }
+    zero() {
+        this.coffs.fill(0);
+    }
     /** Subdivide -- write results into caller-supplied bezier coffs (which must be of the same order) */
     subdivide(u, left, right) {
         const order = this.order;
@@ -417,13 +420,15 @@ export class UnivariateBezier extends BezierCoffs {
             this.coffs[i] += a;
         }
     }
-    /** evaluate the basis functions at specified u.
+    /**
+     * Evaluate the basis functions at specified u.
      * @param u bezier parameter for evaluation.
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length `order`. If insufficient length, a new array is returned.
+     * @returns array of `order` basis function values.
      */
     basisFunctions(u, result) {
         this._basisValues = PascalCoefficients.getBezierBasisValues(this.order, u, this._basisValues);
-        if (!result || result.length !== this.order)
+        if (!result || result.length < this.order)
             result = new Float64Array(this.order);
         let i = 0;
         for (const a of this._basisValues)
@@ -433,9 +438,11 @@ export class UnivariateBezier extends BezierCoffs {
     /**
      * Sum weights[i] * data[...] in blocks of numPerBlock.
      * This is for low level use -- counts are not checked.
-     * @param weights
-     * @param data
-     * @param numPerBlock
+     * @param weights input array of length `numWeights`
+     * @param numWeights number of weights
+     * @param data input array of length `numWeights * numPerBlock`
+     * @param numPerBlock control point dimension
+     * @param result output array of length `numPerBlock`
      */
     static sumWeightedBlocks(weights, numWeights, data, numPerBlock, result) {
         for (let k0 = 0; k0 < numPerBlock; k0++) {
@@ -451,33 +458,33 @@ export class UnivariateBezier extends BezierCoffs {
         }
     }
     /**
-     * Given (multidimensional) control points, sum the control points weighted by the basis function values at parameter u.
+     * Sum the control points weighted by the basis function values at parameter u.
      * @param u bezier parameter
-     * @param polygon Array with coefficients in blocks.
-     * @param blockSize size of blocks
-     * @param result `blockSize` summed values.
+     * @param polygon packed multidimensional control points. ASSUMED contains `blockSize*order` values.
+     * @param blockSize dimension of control points
+     * @param result optional preallocated array of length `blockSize` to fill and return. If insufficient length, a newly created array is returned.
+     * @returns array of `blockSize` summed basis function values.
      */
     sumBasisFunctions(u, polygon, blockSize, result) {
-        const order = this._order;
-        if (!result)
-            result = new Float64Array(order);
+        if (!result || result.length < blockSize)
+            result = new Float64Array(blockSize);
         this._basisValues = PascalCoefficients.getBezierBasisValues(this.order, u, this._basisValues);
-        UnivariateBezier.sumWeightedBlocks(this._basisValues, order, polygon, blockSize, result);
+        UnivariateBezier.sumWeightedBlocks(this._basisValues, this.order, polygon, blockSize, result);
         return result;
     }
     /**
-     * Given (multidimensional) control points, sum the control points weighted by the basis function derivative values at parameter u.
+     * Sum the control points weighted by the basis function derivative values at parameter u.
      * @param u bezier parameter
-     * @param polygon Array with coefficients in blocks.
-     * @param blockSize size of blocks
-     * @param result `blockSize` summed values.
+     * @param polygon packed multidimensional control points. ASSUMED contains `blockSize*order` values.
+     * @param blockSize dimension of control points
+     * @param result optional preallocated array of length `blockSize` to fill and return. If insufficient length, a newly created array is returned.
+     * @returns array of `blockSize` summed basis function derivative values.
      */
     sumBasisFunctionDerivatives(u, polygon, blockSize, result) {
-        const order = this._order;
-        if (!result)
+        if (!result || result.length < blockSize)
             result = new Float64Array(blockSize);
         this._basisValues = PascalCoefficients.getBezierBasisDerivatives(this.order, u, this._basisValues);
-        UnivariateBezier.sumWeightedBlocks(this._basisValues, order, polygon, blockSize, result);
+        UnivariateBezier.sumWeightedBlocks(this._basisValues, this.order, polygon, blockSize, result);
         return result;
     }
     /**
@@ -644,11 +651,10 @@ export class UnivariateBezier extends BezierCoffs {
     // first c0*b0 = a0
     // last c[orderC-1]*b1 = a[orderA-1]
     /** Find roots of a bezier polynomial
-     * * Only look for roots in 0..1
      * * As roots are found, deflate the polynomial.
      * * bezier coffs are changed (and order reduced) at each step.
      */
-    static deflateRoots01(bezier) {
+    static deflateRoots(bezier) {
         const roots = [];
         const coffs = bezier.coffs;
         let a0, a1, segmentFraction, globalStartFraction, newtonFraction;
@@ -710,26 +716,29 @@ export class Order2Bezier extends BezierCoffs {
     static solveCoffs(a0, a1) {
         return Geometry.conditionalDivideFraction(-a0, (a1 - a0));
     }
-    /** evaluate the basis functions at specified u.
+    /**
+     * Evaluate the basis functions at specified u.
      * @param u bezier parameter for evaluation.
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length 2. If insufficient length, a new array is returned.
+     * @returns array of 2 basis function values.
      */
     basisFunctions(u, result) {
-        if (!result)
+        if (!result || result.length < 2)
             result = new Float64Array(2);
         result[0] = 1.0 - u;
         result[1] = u;
         return result;
     }
-    /** evaluate the basis functions at specified u.   Sum multidimensional control points with basis weights.
+    /**
+     * Sum the control points weighted by the basis function values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional preallocated array of length `n` to fill and return. If insufficient length, a newly created array is returned.
+     * @returns array of `n` summed basis function values.
      */
     sumBasisFunctions(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const v = 1.0 - u;
         for (let i = 0; i < n; i++) {
@@ -737,15 +746,16 @@ export class Order2Bezier extends BezierCoffs {
         }
         return result;
     }
-    /** evaluate the blocked derivative at u.
-     * @param u bezier parameter for evaluation.
+    /**
+     * Sum the control points weighted by the basis function derivative values at parameter u.
+     * @param _u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length `n`. If insufficient length, a new array is returned.
+     * @returns array of `n` summed basis function derivative values.
      */
     sumBasisFunctionDerivatives(_u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         for (let i = 0; i < n; i++) {
             result[i] = polygon[i + n] - polygon[i];
@@ -793,12 +803,14 @@ export class Order3Bezier extends BezierCoffs {
     clone() {
         return new Order3Bezier(this.coffs[0], this.coffs[1], this.coffs[2]);
     }
-    /** evaluate the basis functions at specified u.
+    /**
+     * Evaluate the basis functions at specified u.
      * @param u bezier parameter for evaluation.
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length 3. If insufficient length, a new array is returned.
+     * @returns array of 3 basis function values.
      */
     basisFunctions(u, result) {
-        if (!result)
+        if (!result || result.length < 3)
             result = new Float64Array(3);
         const v = 1.0 - u;
         result[0] = v * v;
@@ -806,15 +818,16 @@ export class Order3Bezier extends BezierCoffs {
         result[2] = u * u;
         return result;
     }
-    /** evaluate the basis functions at specified u.   Sum multidimensional control points with basis weights.
+    /**
+     * Sum the control points weighted by the basis function values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional preallocated array of length `n` to fill and return. If insufficient length, a newly created array is returned.
+     * @returns array of `n` summed basis function values.
      */
     sumBasisFunctions(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const v = 1 - u;
         const b0 = v * v;
@@ -825,15 +838,16 @@ export class Order3Bezier extends BezierCoffs {
         }
         return result;
     }
-    /** evaluate the blocked derivative at u.
+    /**
+     * Sum the control points weighted by the basis function derivative values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length `n`. If insufficient length, a new array is returned.
+     * @returns array of `n` summed basis function derivative values.
      */
     sumBasisFunctionDerivatives(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const f0 = 2 * (1 - u);
         const f1 = 2 * u;
@@ -899,12 +913,14 @@ export class Order4Bezier extends BezierCoffs {
     static createProductOrder3Order2(factorA, factorB) {
         return new Order4Bezier(factorA.coffs[0] * factorB.coffs[0], (factorA.coffs[0] * factorB.coffs[1] + 2.0 * factorA.coffs[1] * factorB.coffs[0]) / 3.0, (2.0 * factorA.coffs[1] * factorB.coffs[1] + factorA.coffs[2] * factorB.coffs[0]) / 3.0, factorA.coffs[2] * factorB.coffs[1]);
     }
-    /** evaluate the basis functions at specified u.
+    /**
+     * Evaluate the basis functions at specified u.
      * @param u bezier parameter for evaluation.
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length 4. If insufficient length, a new array is returned.
+     * @returns array of 4 basis function values.
      */
     basisFunctions(u, result) {
-        if (!result)
+        if (!result || result.length < 4)
             result = new Float64Array(4);
         const v = 1.0 - u;
         const uu = u * u;
@@ -915,15 +931,16 @@ export class Order4Bezier extends BezierCoffs {
         result[3] = u * uu;
         return result;
     }
-    /** evaluate the basis functions at specified u.   Sum multidimensional control points with basis weights.
+    /**
+     * Sum the control points weighted by the basis function values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional preallocated array of length `n` to fill and return. If insufficient length, a newly created array is returned.
+     * @returns array of `n` summed basis function values.
      */
     sumBasisFunctions(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const v = 1 - u;
         const uu = u * u;
@@ -937,15 +954,16 @@ export class Order4Bezier extends BezierCoffs {
         }
         return result;
     }
-    /** evaluate the blocked derivative at u.
+    /**
+     * Sum the control points weighted by the basis function derivative values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length `n`. If insufficient length, a new array is returned.
+     * @returns array of `n` summed basis function derivative values.
      */
     sumBasisFunctionDerivatives(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const v = 1 - u;
         // QUADRATIC basis functions applied to differences ... (with factor 3 for derivative)
@@ -1051,10 +1069,11 @@ export class Order5Bezier extends BezierCoffs {
     }
     /** evaluate the basis functions at specified u.
      * @param u bezier parameter for evaluation.
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length 5. If insufficient length, a new array is returned.
+     * @returns array of 5 basis function values.
      */
     basisFunctions(u, result) {
-        if (!result)
+        if (!result || result.length < 5)
             result = new Float64Array(5);
         const v = 1.0 - u;
         const uu = u * u;
@@ -1068,15 +1087,16 @@ export class Order5Bezier extends BezierCoffs {
         result[4] = uu * uu;
         return result;
     }
-    /** evaluate the basis functions at specified u.   Sum multidimensional control points with basis weights.
+    /**
+     * Sum the control points weighted by the basis function values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional preallocated array of length `n` to fill and return. If insufficient length, a newly created array is returned.
+     * @returns array of `n` summed basis function values.
      */
     sumBasisFunctions(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const v = 1.0 - u;
         const uu = u * u;
@@ -1093,15 +1113,16 @@ export class Order5Bezier extends BezierCoffs {
         }
         return result;
     }
-    /** evaluate the blocked derivative at u.
+    /**
+     * Sum the control points weighted by the basis function derivative values at parameter u.
      * @param u bezier parameter for evaluation.
+     * @param polygon packed multidimensional control points. ASSUMED contains `n*order` values.
      * @param n dimension of control points.
-     * @param polygon packed multidimensional control points.   ASSUMED contains `n*order` values.
-     * @param result optional destination for values.   ASSUMED size `order`
-     * @returns Return a (newly allocated) array of basis function values.
+     * @param result optional destination of length `n`. If insufficient length, a new array is returned.
+     * @returns array of `n` summed basis function derivative values.
      */
     sumBasisFunctionDerivatives(u, polygon, n, result) {
-        if (!result)
+        if (!result || result.length < n)
             result = new Float64Array(n);
         const v = 1 - u;
         // CUBIC basis functions applied to differences ...