@itwin/core-geometry 4.3.0-dev.8 → 4.4.0-dev.1

package/lib/cjs/numerics/BezierPolynomials.js

@@ -425,13 +425,15 @@ 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_1.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)
@@ -441,9 +443,11 @@ 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++) {
@@ -459,33 +463,33 @@ 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_1.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_1.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;
     }
     /**
@@ -718,26 +722,29 @@ class Order2Bezier extends BezierCoffs {
     static solveCoffs(a0, a1) {
         return Geometry_1.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++) {
@@ -745,15 +752,16 @@ 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];
@@ -802,12 +810,14 @@ 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;
@@ -815,15 +825,16 @@ 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;
@@ -834,15 +845,16 @@ 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;
@@ -909,12 +921,14 @@ 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;
@@ -925,15 +939,16 @@ 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;
@@ -947,15 +962,16 @@ 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)
@@ -1062,10 +1078,11 @@ 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;
@@ -1079,15 +1096,16 @@ 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;
@@ -1104,15 +1122,16 @@ 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 ...