@itwin/core-geometry 4.3.0-dev.13 → 4.3.0-dev.15

package/lib/cjs/geometry3d/Matrix3d.js

@@ -52,33 +52,39 @@ class PackedMatrix3dOps {
     }
     /**
      * Multiply 3x3 matrix `a*b`, store in `result`.
-     * * All params assumed length 9, allocated by caller.
-     * * c may alias either input.
+     * @param a left matrix in product. ASSUMED length 9.
+     * @param b right matrix in product. ASSUMED length 9.
+     * @param result optional destination array of length 9. If insufficient length, a new array is returned. May refer to same array as `a` or `b`.
+     * @return matrix product `a*b`
      */
     static multiplyMatrixMatrix(a, b, result) {
-        if (!result)
+        if (!result || result.length < 9)
             result = new Float64Array(9);
         PackedMatrix3dOps.loadMatrix(result, (a[0] * b[0] + a[1] * b[3] + a[2] * b[6]), (a[0] * b[1] + a[1] * b[4] + a[2] * b[7]), (a[0] * b[2] + a[1] * b[5] + a[2] * b[8]), (a[3] * b[0] + a[4] * b[3] + a[5] * b[6]), (a[3] * b[1] + a[4] * b[4] + a[5] * b[7]), (a[3] * b[2] + a[4] * b[5] + a[5] * b[8]), (a[6] * b[0] + a[7] * b[3] + a[8] * b[6]), (a[6] * b[1] + a[7] * b[4] + a[8] * b[7]), (a[6] * b[2] + a[7] * b[5] + a[8] * b[8]));
         return result;
     }
     /**
      * Multiply 3x3 matrix `a*bTranspose`, store in `result`.
-     * * All params assumed length 9, allocated by caller.
-     * * c may alias either input.
+     * @param a left matrix in product. ASSUMED length 9.
+     * @param b transpose of right matrix in product. ASSUMED length 9.
+     * @param result optional destination array of length 9. If insufficient length, a new array is returned. May refer to same array as `a` or `b`.
+     * @return matrix product `a*b^T`
      */
     static multiplyMatrixMatrixTranspose(a, b, result) {
-        if (!result)
+        if (!result || result.length < 9)
             result = new Float64Array(9);
         PackedMatrix3dOps.loadMatrix(result, (a[0] * b[0] + a[1] * b[1] + a[2] * b[2]), (a[0] * b[3] + a[1] * b[4] + a[2] * b[5]), (a[0] * b[6] + a[1] * b[7] + a[2] * b[8]), (a[3] * b[0] + a[4] * b[1] + a[5] * b[2]), (a[3] * b[3] + a[4] * b[4] + a[5] * b[5]), (a[3] * b[6] + a[4] * b[7] + a[5] * b[8]), (a[6] * b[0] + a[7] * b[1] + a[8] * b[2]), (a[6] * b[3] + a[7] * b[4] + a[8] * b[5]), (a[6] * b[6] + a[7] * b[7] + a[8] * b[8]));
         return result;
     }
     /**
      * Multiply 3x3 matrix `aTranspose*b`, store in `result`.
-     * * All params assumed length 9, allocated by caller.
-     * * c may alias either input.
+     * @param a transpose of left matrix in product. ASSUMED length 9.
+     * @param b right matrix in product. ASSUMED length 9.
+     * @param result optional destination array of length 9. If insufficient length, a new array is returned. May refer to same array as `a` or `b`.
+     * @return matrix product `a^T*b`
      */
     static multiplyMatrixTransposeMatrix(a, b, result) {
-        if (!result)
+        if (!result || result.length < 9)
             result = new Float64Array(9);
         PackedMatrix3dOps.loadMatrix(result, (a[0] * b[0] + a[3] * b[3] + a[6] * b[6]), (a[0] * b[1] + a[3] * b[4] + a[6] * b[7]), (a[0] * b[2] + a[3] * b[5] + a[6] * b[8]), (a[1] * b[0] + a[4] * b[3] + a[7] * b[6]), (a[1] * b[1] + a[4] * b[4] + a[7] * b[7]), (a[1] * b[2] + a[4] * b[5] + a[7] * b[8]), (a[2] * b[0] + a[5] * b[3] + a[8] * b[6]), (a[2] * b[1] + a[5] * b[4] + a[8] * b[7]), (a[2] * b[2] + a[5] * b[5] + a[8] * b[8]));
         return result;
@@ -96,16 +102,17 @@ class PackedMatrix3dOps {
         a[7] = q;
     }
     /**
-     * Returns the transpose of 3x3 matrix `a`
-     * * If `dest` is passed as argument, then the function copies the transpose of 3x3 matrix `a` into `dest`
-     * * `a` is not changed unless also passed as the dest, i.e., copyTransposed(a,a) transposes `a` in place
+     * Compute transpose of 3x3 matrix `a`, store in `dest`.
+     * @param a source matrix. ASSUMED length 9. Note that `a` is not changed unless also passed as `dest`, i.e., `copyTransposed(a,a)` transposes `a` in place.
+     * @param dest optional destination array of length 9. If insufficient length, a new array is returned. May refer to same array as `a`.
+     * @return matrix `a^T`
      */
     static copyTransposed(a, dest) {
         if (dest === a) {
             PackedMatrix3dOps.transposeInPlace(dest);
         }
         else {
-            if (!dest)
+            if (!dest || dest.length < 9)
                 dest = new Float64Array(9);
             dest[0] = a[0];
             dest[1] = a[3];
@@ -206,11 +213,10 @@ class Matrix3d {
     }
     /**
      * Constructor
-     * @param coffs optional coefficient array.
-     * * **WARNING:** coffs is captured (i.e., is now owned by the Matrix3d object and can be modified by it).
+     * @param coffs optional coefficient array of length at least 9 (CAPTURED). If undefined or insufficient length, a new array is created.
      */
     constructor(coffs) {
-        this.coffs = coffs ? coffs : new Float64Array(9);
+        this.coffs = (coffs && coffs.length >= 9) ? coffs : new Float64Array(9);
         this.inverseCoffs = undefined;
         this.inverseState = InverseMatrixState.unknown;
     }
@@ -373,13 +379,14 @@ class Matrix3d {
      * Create a Matrix3d with caller-supplied coefficients and optional inverse coefficients.
      * * The inputs are captured into (i.e., owned by) the new Matrix3d.
      * * The caller is responsible for validity of the inverse coefficients.
+     * * If either array is insufficiently sized, it is ignored.
      * @param coffs (required) array of 9 coefficients.
      * @param inverseCoffs (optional) array of 9 coefficients.
      * @returns a Matrix3d populated by a coffs array.
      */
     static createCapture(coffs, inverseCoffs) {
         const result = new Matrix3d(coffs);
-        if (inverseCoffs) {
+        if (inverseCoffs && inverseCoffs.length >= 9) {
             result.inverseCoffs = inverseCoffs;
             result.inverseState = InverseMatrixState.inverseStored;
         }
@@ -1613,10 +1620,10 @@ class Matrix3d {
      * @param y y part of multiplied point
      * @param z z part of multiplied point
      * @param w w part of multiplied point
-     * @param result optional preallocated result.
+     * @param result optional preallocated result. If length < 4, a new array is returned.
      */
     static xyzPlusMatrixTimesWeightedCoordinatesToFloat64Array(origin, matrix, x, y, z, w, result) {
-        if (!result)
+        if (!result || result.length < 4)
             result = new Float64Array(4);
         result[0] = matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z + origin.x * w;
         result[1] = matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z + origin.y * w;
@@ -1636,10 +1643,10 @@ class Matrix3d {
      * @param x x part of multiplied point
      * @param y y part of multiplied point
      * @param z z part of multiplied point
-     * @param result optional preallocated result.
+     * @param result optional preallocated result. If length < 3, a new array is returned.
      */
     static xyzPlusMatrixTimesCoordinatesToFloat64Array(origin, matrix, x, y, z, result) {
-        if (!result)
+        if (!result || result.length < 3)
             result = new Float64Array(3);
         result[0] = matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z + origin.x;
         result[1] = matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z + origin.y;