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

package/lib/esm/numerics/BezierPolynomials.js

@@ -420,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)
@@ -436,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++) {
@@ -454,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;
     }
     /**
@@ -712,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++) {
@@ -739,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];
@@ -795,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;
@@ -808,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;
@@ -827,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;
@@ -901,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;
@@ -917,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;
@@ -939,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)
@@ -1053,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;
@@ -1070,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;
@@ -1095,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 ...