@itwin/core-geometry 4.0.0-dev.37 → 4.0.0-dev.39

package/lib/esm/geometry3d/Matrix3d.js

@@ -12,7 +12,7 @@ import { Point2d } from "./Point2dVector2d";
 import { Point3d, Vector3d } from "./Point3dVector3d";
 import { Transform } from "./Transform";
 /* eslint-disable @itwin/prefer-get */
-// cSpell:words XXYZ YXYZ ZXYZ SaeedTorabi
+// cSpell:words XXYZ YXYZ ZXYZ SaeedTorabi arctan newcommand
 /**
  * PackedMatrix3dOps contains static methods for matrix operations where the matrix is a Float64Array.
  * * The Float64Array contains the matrix entries in row-major order
@@ -308,7 +308,7 @@ export class Matrix3d {
             /**
              * Here we rotate this.columnX() around this.columnZ() by "angle" and expect to get other.columnX().
              * Then we rotate this.columnY() around this.columnZ() by the same "angle" and if we get other.columnY(),
-             * that means this` and `other` have X and Y columns differing only by a rotation around that Z.
+             * that means `this` and `other` have X and Y columns differing only by a rotation around column Z.
              */
             let column = Vector3d.createRotateVectorAroundVector(columnX, columnZ, angle);
             if (other.isAlmostEqualColumnXYZ(0, column.x, column.y, column.z, tol)) {
@@ -757,14 +757,16 @@ export class Matrix3d {
     static createColumnsXYW(vectorU, u, vectorV, v, vectorW, w, result) {
         return Matrix3d.createRowValues(vectorU.x, vectorV.x, vectorW.x, vectorU.y, vectorV.y, vectorW.y, u, v, w, result);
     }
-    /** Create a matrix from "as viewed" right and up vectors.
-     * * ColumnX points in the rightVector direction
-     * * ColumnY points in the upVector direction
+    /**
+     * Create a matrix from "as viewed" right and up vectors.
+     * * ColumnX points in the rightVector direction.
+     * * ColumnY points in the upVector direction.
      * * ColumnZ is a unit cross product of ColumnX and ColumnY.
      * * Optionally rotate by 45 degrees around `upVector` to bring its left or right vertical edge to center.
      * * Optionally rotate by arctan(1/sqrt(2)) ~ 35.264 degrees around `rightVector` to bring the top or bottom
      * horizontal edge of the view to the center (for isometric views).
-     * * This is expected to be used with various principal unit vectors that are perpendicular to each other.
+     *
+     * This is expected to be used with various principal unit vectors that are perpendicular to each other.
      * * STANDARD TOP VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitY(), 0, 0)
      * * STANDARD FRONT VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitZ(), 0, 0)
      * * STANDARD BACK VIEW: createViewedAxes(Vector3d.unitX(-1), Vector3d.unitZ(), 0, 0)
@@ -1253,6 +1255,18 @@ export class Matrix3d {
             + this.coffs[3] * this.coffs[4]
             + this.coffs[6] * this.coffs[7];
     }
+    /** Return the dot product of column X with column Z */
+    columnXDotColumnZ() {
+        return this.coffs[0] * this.coffs[2]
+            + this.coffs[3] * this.coffs[5]
+            + this.coffs[6] * this.coffs[8];
+    }
+    /** Return the dot product of column Y with column Z */
+    columnYDotColumnZ() {
+        return this.coffs[1] * this.coffs[2]
+            + this.coffs[4] * this.coffs[5]
+            + this.coffs[7] * this.coffs[8];
+    }
     /**
      * Dot product of an indexed column with a vector given as x,y,z
      * @param columnIndex index of column. Must be 0,1,2.
@@ -1547,7 +1561,7 @@ export class Matrix3d {
      * \text{Treating U as a row to the left of untransposed matrix\: return row}&\rowSubXYZ{V}&=&\rowSubXYZ{U}\matrixXY{A}
      * \end{matrix}
      * ```
-     * @return the vector result (optional)
+     * @param result the vector result (optional)
      */
     multiplyTransposeVector(vector, result) {
         result = result ? result : new Vector3d();
@@ -1561,7 +1575,7 @@ export class Matrix3d {
     }
     /**
      * Multiply the matrix * [x,y,z], i.e. the vector [x,y,z] is a column vector on the right.
-     * @return the vector result (optional)
+     * @param result the vector result (optional)
      */
     multiplyXYZ(x, y, z, result) {
         result = result ? result : new Vector3d();
@@ -1586,7 +1600,7 @@ export class Matrix3d {
     }
     /**
      * Multiply the matrix * [x,y,0], i.e. the vector [x,y,0] is a column vector on the right.
-     * @return the vector result (optional)
+     * @param result the vector result (optional)
      */
     multiplyXY(x, y, result) {
         result = result ? result : new Vector3d();
@@ -1597,7 +1611,7 @@ export class Matrix3d {
     }
     /**
      * Compute origin + the matrix * [x,y,0].
-     * @return the vector result (optional)
+     * @param result the Point3d result (optional)
      */
     originPlusMatrixTimesXY(origin, x, y, result) {
         return Point3d.create(origin.x + this.coffs[0] * x + this.coffs[1] * y, origin.y + this.coffs[3] * x + this.coffs[4] * y, origin.z + this.coffs[6] * x + this.coffs[7] * y, result);
@@ -1605,7 +1619,7 @@ export class Matrix3d {
     /**
      * Multiply the matrix * (x,y,z) in place, i.e. the vector (x,y,z) is a column vector on the right and
      * the multiplication updates the vector values.
-     * @param xyzData the vector data
+     * @param xyzData the vector data.
      */
     multiplyVectorInPlace(xyzData) {
         const x = xyzData.x;
@@ -1619,7 +1633,7 @@ export class Matrix3d {
      * Multiply the transpose matrix times [x,y,z] in place, i.e. the vector [x,y,z] is a column vector on
      * the right and the multiplication updates the vector values.
      * * This is equivalent to `multiplyTransposeVector` but always returns the result directly in the input.
-     * @param xyzData the vector data
+     * @param vectorU the vector data
      */
     multiplyTransposeVectorInPlace(vectorU) {
         const x = vectorU.x;
@@ -1640,7 +1654,7 @@ export class Matrix3d {
      * \phantom{8888}\text{and return V as a Vector3d} & & &
      * \end{matrix}
      * ````
-     * @return the vector result (optional)
+     * @param result the vector result (optional)
      */
     multiplyTransposeXYZ(x, y, z, result) {
         result = result ? result : new Vector3d();
@@ -1651,8 +1665,8 @@ export class Matrix3d {
     }
     /**
      * Solve `matrix * result = vector` for an unknown `result`.
-     * * This is equivalent to multiplication `result = inverse matrix * vector`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * * This is equivalent to multiplication `result = matrixInverse * vector`.
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      */
     multiplyInverse(vector, result) {
         this.computeCachedInverse(true);
@@ -1667,7 +1681,7 @@ export class Matrix3d {
     /**
      * Solve `matrixTranspose * result = vector` for an unknown `result`.
      * * This is equivalent to multiplication `result = matrixInverseTranspose * vector`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      */
     multiplyInverseTranspose(vector, result) {
         this.computeCachedInverse(true);
@@ -1682,7 +1696,7 @@ export class Matrix3d {
     /**
      * Multiply `matrixInverse * [x,y,z]`.
      * * This is equivalent to solving `matrix * result = [x,y,z]` for an unknown `result`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      * @return result as a Vector3d or undefined (if the matrix is singular).
      */
     multiplyInverseXYZAsVector3d(x, y, z, result) {
@@ -1695,7 +1709,7 @@ export class Matrix3d {
     /**
      * Multiply `matrixInverse * [x,y,z]` and return result as `Point4d` with given weight.
      * * Equivalent to solving `matrix * result = [x,y,z]` for an unknown `result`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      * @return result as a Point4d with the same weight.
      */
     multiplyInverseXYZW(x, y, z, w, result) {
@@ -1708,7 +1722,7 @@ export class Matrix3d {
     /**
      * Multiply `matrixInverse * [x,y,z]` and return result as `Point3d`.
      * * Equivalent to solving `matrix * result = [x,y,z]` for an unknown `result`.
-     * @return result as a Point3d or undefined (if the matrix is singular).
+     * @return result as a Point3d or `undefined` (if the matrix is singular).
      */
     multiplyInverseXYZAsPoint3d(x, y, z, result) {
         this.computeCachedInverse(true);
@@ -1719,7 +1733,7 @@ export class Matrix3d {
     }
     /**
      * Invoke a given matrix*matrix operation to compute the inverse matrix and set this.inverseCoffs
-     * * If either input coffA or coffB is undefined, set state to `InverseMatrixState.unknown` but
+     * * If either input coffA or coffB is `undefined`, set state to `InverseMatrixState.unknown` but
      * leave the inverseCoffs untouched.
      * @param f the given matrix*matrix operation that is called by this function to compute the inverse.
      * `f` must be a matrix*matrix operation. Otherwise, the function does not generate the inverse properly.
@@ -1941,10 +1955,12 @@ export class Matrix3d {
      * * [A   B   C] ===> [A   B   AxB] ===> [A   (AxB)xA   AxB]
      *
      * This means that in the final matrix:
-     * * column A is same as original column A.
-     * * column B is linear combination of original A and B (i.e., is in the plane of original A and B).
-     * * column C is perpendicular to A and B of both the original and final.
+     * * first column is same as original column A.
+     * * second column is linear combination of original A and B (i.e., is in the plane of original A and B).
+     * * third column is perpendicular to first and second columns of both the original and final.
      * * original column C is overwritten and does not participate in the result.
+     *
+     * The final matrix will have 3 orthogonal columns.
      */
     axisOrderCrossProductsInPlace(axisOrder) {
         switch (axisOrder) {
@@ -1982,35 +1998,35 @@ export class Matrix3d {
     }
     /**
      * Normalize each column in place.
-     * @param originalRowMagnitudes optional vector to store original column magnitudes.
-     * @returns Return true if all columns have non-zero lengths. Otherwise, return false.
-     * * If false is returned, the magnitudes are stored in the `originalRowMagnitudes` vector but no columns
+     * @param originalColumnMagnitudes optional vector to store original column magnitudes.
+     * @returns return true if all columns have non-zero lengths. Otherwise, return false.
+     * * If false is returned, the magnitudes are stored in the `originalColumnMagnitudes` vector but no columns
      * are altered.
      */
-    normalizeColumnsInPlace(originalRowMagnitudes) {
+    normalizeColumnsInPlace(originalColumnMagnitudes) {
         const ax = this.columnXMagnitude();
         const ay = this.columnYMagnitude();
         const az = this.columnZMagnitude();
-        if (originalRowMagnitudes)
-            originalRowMagnitudes.set(ax, ay, az);
+        if (originalColumnMagnitudes)
+            originalColumnMagnitudes.set(ax, ay, az);
         if (Geometry.isSmallMetricDistance(ax) || Geometry.isSmallMetricDistance(ay) || Geometry.isSmallMetricDistance(az))
             return false;
         this.scaleColumns(1.0 / ax, 1.0 / ay, 1.0 / az, this);
         return true;
     }
     /**
-   * Normalize each row in place.
-   * @param originalColumnMagnitudes optional vector to store original row magnitudes.
-   * @returns Return true if all rows have non-zero lengths. Otherwise, return false.
-   * * If false is returned, the magnitudes are stored in the `originalColumnMagnitudes` vector but no rows
-   * are altered.
-   */
-    normalizeRowsInPlace(originalColumnMagnitudes) {
+     * Normalize each row in place.
+     * @param originalRowMagnitudes optional vector to store original row magnitudes.
+     * @returns return true if all rows have non-zero lengths. Otherwise, return false.
+     * * If false is returned, the magnitudes are stored in the `originalRowMagnitudes` vector but no rows
+     * are altered.
+     */
+    normalizeRowsInPlace(originalRowMagnitudes) {
         const ax = this.rowXMagnitude();
         const ay = this.rowYMagnitude();
         const az = this.rowZMagnitude();
-        if (originalColumnMagnitudes)
-            originalColumnMagnitudes.set(ax, ay, az);
+        if (originalRowMagnitudes)
+            originalRowMagnitudes.set(ax, ay, az);
         if (Geometry.isSmallMetricDistance(ax) || Geometry.isSmallMetricDistance(ay) || Geometry.isSmallMetricDistance(az))
             return false;
         this.scaleRows(1.0 / ax, 1.0 / ay, 1.0 / az, this);
@@ -2032,7 +2048,7 @@ export class Matrix3d {
      * Compute the inverse of `this` Matrix3d. The inverse is stored in `this.inverseCoffs` for later use.
      * @param useCacheIfAvailable if `true`, use the previously computed inverse if available. If `false`,
      * recompute the inverse.
-     * @returns Return `true` if the inverse is computed. Return `false` if matrix is singular.
+     * @returns return `true` if the inverse is computed. Return `false` if matrix is singular.
      */
     computeCachedInverse(useCacheIfAvailable) {
         if (useCacheIfAvailable && Matrix3d.useCachedInverse && this.inverseState !== InverseMatrixState.unknown) {
@@ -2045,10 +2061,11 @@ export class Matrix3d {
         const inverseCoffs = this.inverseCoffs;
         /**
          * We calculate the inverse using cross products.
-         * Math details can be found at
-         * https://www.chilimath.com/lessons/advanced-algebra/determinant-3x3-matrix/
-         * In summary, if M = [A   B   C] then inverse of M = (1/det)[BxC   CxA   AxB] where det is the
-         * determinant of matrix M and can be calculated by "A dot BxC".
+         * Math details can be found at docs/learning/matrix/Matrix.md
+         *                    [   A   ]
+         * In summary, if M = [   B   ] then inverse of M = (1/det)[BxC   CxA   AxB] where
+         *                    [   C   ]
+         * det is the determinant of matrix M (which is equal to "A dot BxC").
          */
         Matrix3d.indexedRowCrossProduct(coffs, 3, 6, inverseCoffs, 0); // BxC
         Matrix3d.indexedRowCrossProduct(coffs, 6, 0, inverseCoffs, 1); // CxA
@@ -2090,19 +2107,30 @@ export class Matrix3d {
         this.coffs[Matrix3d.flatIndexOf(row, column)] = value;
         this.inverseState = InverseMatrixState.unknown;
     }
-    /** create a Matrix3d whose columns are scaled copies of this Matrix3d.
-     * @param scaleX scale factor for column x
-     * @param scaleY scale factor for column y
-     * @param scaleZ scale factor for column z
-     * @param result optional preallocated result.
+    /**
+     * Create a Matrix3d whose values are uniformly scaled from `this` Matrix3d.
+     * @param scale scale factor to apply.
+     * @param result optional result.
+     * @returns return the scaled matrix.
+     */
+    scale(scale, result) {
+        return Matrix3d.createRowValues(this.coffs[0] * scale, this.coffs[1] * scale, this.coffs[2] * scale, this.coffs[3] * scale, this.coffs[4] * scale, this.coffs[5] * scale, this.coffs[6] * scale, this.coffs[7] * scale, this.coffs[8] * scale, result);
+    }
+    /**
+     * Create a Matrix3d whose columns are scaled copies of `this` Matrix3d.
+     * @param scaleX scale factor for column 0
+     * @param scaleY scale factor for column 1
+     * @param scaleZ scale factor for column 2
+     * @param result optional result
      */
     scaleColumns(scaleX, scaleY, scaleZ, result) {
         return Matrix3d.createRowValues(this.coffs[0] * scaleX, this.coffs[1] * scaleY, this.coffs[2] * scaleZ, this.coffs[3] * scaleX, this.coffs[4] * scaleY, this.coffs[5] * scaleZ, this.coffs[6] * scaleX, this.coffs[7] * scaleY, this.coffs[8] * scaleZ, result);
     }
-    /** Scale the columns of this Matrix3d.
-     * @param scaleX scale factor for column x
-     * @param scaleY scale factor for column y
-     * @param scaleZ scale factor for column z
+    /**
+     * Scale the columns of `this` Matrix3d in place.
+     * @param scaleX scale factor for column 0
+     * @param scaleY scale factor for column 1
+     * @param scaleZ scale factor for column 2
      */
     scaleColumnsInPlace(scaleX, scaleY, scaleZ) {
         this.coffs[0] *= scaleX;
@@ -2134,18 +2162,55 @@ export class Matrix3d {
                 this.inverseState = InverseMatrixState.singular;
         }
     }
-    /** create a Matrix3d whose rows are scaled copies of this Matrix3d.
-     * @param scaleX scale factor for row x
-     * @param scaleY scale factor for row y
-     * @param scaleZ scale factor for row z
-     * @param result optional preallocated result.
+    /**
+     * Create a Matrix3d whose rows are scaled copies of `this` Matrix3d.
+     * @param scaleX scale factor for row 0
+     * @param scaleY scale factor for row 1
+     * @param scaleZ scale factor for row 2
+     * @param result optional result
      */
     scaleRows(scaleX, scaleY, scaleZ, result) {
         return Matrix3d.createRowValues(this.coffs[0] * scaleX, this.coffs[1] * scaleX, this.coffs[2] * scaleX, this.coffs[3] * scaleY, this.coffs[4] * scaleY, this.coffs[5] * scaleY, this.coffs[6] * scaleZ, this.coffs[7] * scaleZ, this.coffs[8] * scaleZ, result);
     }
     /**
-     * add scaled values from other Matrix3d to this Matrix3d
-     * @param other Matrix3d with values to be added
+     * Scale the rows of `this` Matrix3d in place.
+     * @param scaleX scale factor for row 0
+     * @param scaleY scale factor for row 1
+     * @param scaleZ scale factor for row 2
+     */
+    scaleRowsInPlace(scaleX, scaleY, scaleZ) {
+        this.coffs[0] *= scaleX;
+        this.coffs[1] *= scaleX;
+        this.coffs[2] *= scaleX;
+        this.coffs[3] *= scaleY;
+        this.coffs[4] *= scaleY;
+        this.coffs[5] *= scaleY;
+        this.coffs[6] *= scaleZ;
+        this.coffs[7] *= scaleZ;
+        this.coffs[8] *= scaleZ;
+        if (this.inverseState === InverseMatrixState.inverseStored && this.inverseCoffs !== undefined) {
+            // apply reciprocal scales to the COLUMNs of the inverse
+            const divX = Geometry.conditionalDivideFraction(1.0, scaleX);
+            const divY = Geometry.conditionalDivideFraction(1.0, scaleY);
+            const divZ = Geometry.conditionalDivideFraction(1.0, scaleZ);
+            if (divX !== undefined && divY !== undefined && divZ !== undefined) {
+                this.inverseCoffs[0] *= divX;
+                this.inverseCoffs[1] *= divY;
+                this.inverseCoffs[2] *= divZ;
+                this.inverseCoffs[3] *= divX;
+                this.inverseCoffs[4] *= divY;
+                this.inverseCoffs[5] *= divZ;
+                this.inverseCoffs[6] *= divX;
+                this.inverseCoffs[7] *= divY;
+                this.inverseCoffs[8] *= divZ;
+            }
+            else
+                this.inverseState = InverseMatrixState.singular;
+        }
+    }
+    /**
+     * Add scaled values from `other` Matrix3d to `this` Matrix3d.
+     * @param other Matrix3d with values to be added.
      * @param scale scale factor to apply to the added values.
      */
     addScaledInPlace(other, scale) {
@@ -2154,18 +2219,19 @@ export class Matrix3d {
         this.inverseState = InverseMatrixState.unknown;
     }
     /**
-     * add scaled values from an outer product.
-     * * The scaled outer product is a "rank 1" matrix.
+     * Add scaled values from an outer product of vectors U and V.
+     * * The scaled outer product is a matrix with `rank 1` (all columns/rows are linearly dependent).
      * * This is useful in constructing mirrors and directional scales.
      * ```
      * equation
      * A += s \columnSubXYZ{U}\rowSubXYZ{V}
      * \\ \matrixXY{A} += s \begin{bmatrix}
-     * U_x * V_x & U_y * V_x & U_z * V_x \\
-     * U_x * V_y & U_y * V_y & U_z * V_y \\
-     * U_x * V_z & U_y * V_z & U_z * V_z \end{bmatrix}
+     * U_x * V_x & U_x * V_y & U_x * V_z \\
+     * U_y * V_x & U_y * V_y & U_y * V_z \\
+     * U_z * V_x & U_z * V_y & U_z * V_z \end{bmatrix}
      * ```
-     * @param other Matrix3d with values to be added
+     * @param vectorU first vector in the outer product.
+     * @param vectorV second vector in the outer product.
      * @param scale scale factor to apply to the added values.
      */
     addScaledOuterProductInPlace(vectorU, vectorV, scale) {
@@ -2180,14 +2246,6 @@ export class Matrix3d {
         this.coffs[8] += scale * vectorU.z * vectorV.z;
         this.inverseState = InverseMatrixState.unknown;
     }
-    /** create a Matrix3d whose values are uniformly scaled from this.
-     * @param scale scale factor to apply.
-     * @param result optional preallocated result.
-     * @returns Return the new or repopulated matrix
-     */
-    scale(scale, result) {
-        return Matrix3d.createRowValues(this.coffs[0] * scale, this.coffs[1] * scale, this.coffs[2] * scale, this.coffs[3] * scale, this.coffs[4] * scale, this.coffs[5] * scale, this.coffs[6] * scale, this.coffs[7] * scale, this.coffs[8] * scale, result);
-    }
     /**
      * Create a rigid matrix (columns and rows are unit length and pairwise perpendicular) for
      * the given eye coordinate.
@@ -2210,7 +2268,6 @@ export class Matrix3d {
                 result.scaleColumnsInPlace(1.0, -1.0, -1.0);
         }
         else {
-            // if coordinate is (x,y,0), i.e., Front or Back or Left or Right view
             /**
              * The matrix that the "else" statement creates is
              *        [-s   -s1*c    c1*c]
@@ -2240,57 +2297,56 @@ export class Matrix3d {
         }
         return result;
     }
-    /** Return the determinant of this matrix. */
+    /** Return the determinant of `this` matrix. */
     determinant() {
         return this.coffs[0] * this.coffs[4] * this.coffs[8]
-            - this.coffs[0] * this.coffs[7] * this.coffs[5]
-            + this.coffs[3] * this.coffs[7] * this.coffs[2]
-            - this.coffs[3] * this.coffs[1] * this.coffs[8]
-            + this.coffs[6] * this.coffs[1] * this.coffs[5]
-            - this.coffs[6] * this.coffs[4] * this.coffs[2];
+            - this.coffs[0] * this.coffs[5] * this.coffs[7]
+            - this.coffs[1] * this.coffs[3] * this.coffs[8]
+            + this.coffs[1] * this.coffs[5] * this.coffs[6]
+            + this.coffs[2] * this.coffs[3] * this.coffs[7]
+            - this.coffs[2] * this.coffs[4] * this.coffs[6];
     }
-    /** Return an estimate of how independent the columns are.  Near zero is bad. Near 1 is good
+    /**
+     * Return an estimate of how independent the columns of `this` matrix are. Near zero is bad (i.e.,
+     * columns are almost dependent and matrix is nearly singular). Near 1 is good (i.e., columns are
+     * almost independent and matrix is invertible).
      */
     conditionNumber() {
         const determinant = this.determinant();
-        const columnMagnitudeProduct = Geometry.hypotenuseXYZ(this.coffs[0], this.coffs[3], this.coffs[6])
+        const columnMagnitudeSum = Geometry.hypotenuseXYZ(this.coffs[0], this.coffs[3], this.coffs[6])
             + Geometry.hypotenuseXYZ(this.coffs[1], this.coffs[4], this.coffs[7])
             + Geometry.hypotenuseXYZ(this.coffs[2], this.coffs[5], this.coffs[8]);
-        return Geometry.safeDivideFraction(determinant, columnMagnitudeProduct, 0.0);
+        return Geometry.safeDivideFraction(determinant, columnMagnitudeSum, 0.0);
     }
     /** Return the sum of squares of all entries */
     sumSquares() {
-        let i = 0;
         let sum = 0;
-        for (i = 0; i < 9; i++)
+        for (let i = 0; i < 9; i++)
             sum += this.coffs[i] * this.coffs[i];
         return sum;
     }
     /** Return the sum of squares of diagonal entries */
     sumDiagonalSquares() {
-        let i = 0;
         let sum = 0;
-        for (i = 0; i < 9; i += 4)
+        for (let i = 0; i < 9; i += 4)
             sum += this.coffs[i] * this.coffs[i];
         return sum;
     }
-    /** Return the sum of diagonal entries (also known as the trace) */
+    /** Return the matrix `trace` (sum of diagonal entries) */
     sumDiagonal() {
         return this.coffs[0] + this.coffs[4] + this.coffs[8];
     }
     /** Return the Maximum absolute value of any single entry */
     maxAbs() {
-        let i = 0;
         let max = 0;
-        for (i = 0; i < 9; i++)
+        for (let i = 0; i < 9; i++)
             max = Math.max(max, Math.abs(this.coffs[i]));
         return max;
     }
     /** Return the maximum absolute difference between corresponding entries of `this` and `other` */
     maxDiff(other) {
-        let i = 0;
         let max = 0;
-        for (i = 0; i < 9; i++)
+        for (let i = 0; i < 9; i++)
             max = Math.max(max, Math.abs(this.coffs[i] - other.coffs[i]));
         return max;
     }
@@ -2309,86 +2365,102 @@ export class Matrix3d {
     get hasCachedInverse() {
         return this.inverseState === InverseMatrixState.inverseStored && this.inverseCoffs !== undefined;
     }
-    /** Test if the below diagonal entries are all nearly zero */
+    /** Test if the below diagonal entries (3,6,7) are all nearly zero */
     get isUpperTriangular() {
         const sumAll = this.sumSquares();
         const sumLow = Geometry.hypotenuseSquaredXYZ(this.coffs[3], this.coffs[6], this.coffs[7]);
         return Math.sqrt(sumLow) <= Geometry.smallAngleRadians * (1.0 + Math.sqrt(sumAll));
     }
-    /** If the matrix is diagonal and all diagonals are within tolerance, return the first diagonal.  Otherwise return undefined.
+    /** Test if the above diagonal entries (1,2,5) are all nearly zero */
+    get isLowerTriangular() {
+        const sumAll = this.sumSquares();
+        const sumLow = Geometry.hypotenuseSquaredXYZ(this.coffs[1], this.coffs[2], this.coffs[75]);
+        return Math.sqrt(sumLow) <= Geometry.smallAngleRadians * (1.0 + Math.sqrt(sumAll));
+    }
+    /**
+     * If the matrix is diagonal and all diagonals are almost equal, return the first diagonal (entry 0
+     * which is same as entry 4 and 8). Otherwise return `undefined`.
      */
     sameDiagonalScale() {
         const sumAll = this.sumSquares();
         const sumDiagonal = this.sumDiagonalSquares();
         const sumOff = Math.abs(sumAll - sumDiagonal);
         if (Math.sqrt(sumOff) <= Geometry.smallAngleRadians * (1.0 + Math.sqrt(sumAll))
-            && Geometry.isSameCoordinate(this.coffs[0], this.coffs[4]) && Geometry.isSameCoordinate(this.coffs[0], this.coffs[8]))
+            && Geometry.isSameCoordinate(this.coffs[0], this.coffs[4])
+            && Geometry.isSameCoordinate(this.coffs[0], this.coffs[8]))
             return this.coffs[0];
         return undefined;
     }
-    /** Sum of squared differences between symmetric pairs */
+    /** Sum of squared differences between symmetric pairs (entry 1 and 3 - 2 and 6 - 5 and 7) */
     sumSkewSquares() {
         return Geometry.hypotenuseSquaredXYZ(this.coffs[1] - this.coffs[3], this.coffs[2] - this.coffs[6], this.coffs[5] - this.coffs[7]);
     }
-    /** Test if the matrix is a pure rotation.
-     * @param allowMirror whether to widen the test to return true if the matrix is orthogonal (a pure rotation or a mirror)
+    /**
+     * Test if all rows and columns are unit length and are perpendicular to each other, i.e., the matrix is either
+     * a `pure rotation` (determinant is +1) or is a `mirror` (determinant is -1).
+     * * **Note:** such a matrix is called `orthogonal` and its inverse is its transpose.
+     */
+    testPerpendicularUnitRowsAndColumns() {
+        const product = this.multiplyMatrixMatrixTranspose(this);
+        return product.isIdentity;
+    }
+    /**
+     * Test if the matrix is a `rigid` matrix (or `pure rotation`, i.e., columns and rows are unit length and
+     * pairwise perpendicular and determinant is +1).
+     * @param allowMirror whether to widen the test to return true if the matrix is a `mirror` (determinant is -1).
     */
     isRigid(allowMirror = false) {
         return this.testPerpendicularUnitRowsAndColumns() && (allowMirror || this.determinant() > 0);
     }
-    /** Test if all rows and columns are perpendicular to each other and have equal length.
-     * If so, the length (or its negative) is the scale factor from a set of rigid axes to these axes.
-     * * result.rigidAxes is the rigid axes (with the scale factor removed)
-     * * result.scale is the scale factor
+    /**
+     * Test if all rows and columns are perpendicular to each other and have equal length.
+     * If so, the length (or its negative) is the `scale` factor from a set of `orthonormal axes` to
+     * the set of axes created by columns of `this` matrix. Otherwise, returns `undefined`.
+     * @returns returns `{ rigidAxes, scale }` where `rigidAxes` is a Matrix3d with its columns as the rigid axes
+     * (with the scale factor removed) and `scale` is the scale factor.
+     * * Note that determinant of a rigid matrix is +1.
+     * * The context for this method is to determine if the matrix is the product a `rotation` matrix and a uniform
+     * `scale` matrix (diagonal matrix with all diagonal entries the same nonzero number).
      */
     factorRigidWithSignedScale() {
         const product = this.multiplyMatrixMatrixTranspose(this);
-        const ss = product.sameDiagonalScale();
-        if (ss === undefined || ss <= 0.0)
+        const scaleSquare = product.sameDiagonalScale();
+        if (scaleSquare === undefined || scaleSquare <= 0.0)
             return undefined;
-        const s = this.determinant() > 0 ? Math.sqrt(ss) : -Math.sqrt(ss);
-        const divS = 1.0 / s;
-        const result = { rigidAxes: this.scaleColumns(divS, divS, divS), scale: s };
+        const scale = this.determinant() > 0 ? Math.sqrt(scaleSquare) : -Math.sqrt(scaleSquare);
+        const scaleInverse = 1.0 / scale;
+        const result = { rigidAxes: this.scaleColumns(scaleInverse, scaleInverse, scaleInverse), scale };
         return result;
     }
-    /** Test if the matrix is shuffles and negates columns. */
+    /** Test if `this` matrix reorders and/or negates the columns of the `identity` matrix. */
     get isSignedPermutation() {
         let count = 0;
         for (let row = 0; row < 3; row++)
             for (let col = 0; col < 3; col++) {
                 const q = this.at(row, col);
-                if (q === 0) { // This comment makes the block non-empty
+                if (q === 0) {
+                    // do nothing
                 }
                 else if (q === 1 || q === -1) {
-                    // the rest of this row and column should be 0.
-                    // "at" will apply cyclic indexing.
                     count++;
-                    if (this.at(row + 1, col) !== 0)
-                        return false;
-                    if (this.at(row + 2, col) !== 0)
-                        return false;
-                    if (this.at(row, col + 1) !== 0)
-                        return false;
-                    if (this.at(row, col + 2) !== 0)
+                    // if the rest of this row and column should be 0 ("at" will apply cyclic indexing)
+                    if ((this.at(row + 1, col) !== 0) || (this.at(row + 2, col) !== 0) ||
+                        (this.at(row, col + 1) !== 0) || (this.at(row, col + 2) !== 0))
                         return false;
                 }
-                else { // entry is not from 0,1,-1 . . .
+                else { // entry is not 0, 1, or -1
                     return false;
                 }
             }
         return count === 3;
     }
-    /** Test if all rows and columns are length 1 and are perpendicular to each other.  (I.e. the matrix is either a pure rotation with uniform scale factor of 1 or -1) */
-    testPerpendicularUnitRowsAndColumns() {
-        const product = this.multiplyMatrixMatrixTranspose(this);
-        return product.isIdentity;
-    }
-    /** Adjust the matrix in place so that:
-     * * columns are perpendicular and have unit length
-     * * transpose equals inverse
-     * * mirroring is removed
+    /**
+     * Adjust the matrix in place to make is a `rigid` matrix so that:
+     * * columns are perpendicular and have unit length.
+     * * transpose equals inverse.
+     * * mirroring is removed.
      * @param axisOrder how to reorder the matrix columns
-     * @return whether the instance is rigid on return
+     * @return whether the adjusted matrix is `rigid` on return
      */
     makeRigid(axisOrder = AxisOrder.XYZ) {
         const maxAbs = this.maxAbs();
@@ -2409,22 +2481,13 @@ export class Matrix3d {
             return result;
         return undefined;
     }
-    static computeQuatTerm(numerator, denomCoff, reciprocal, diagSum) {
-        let coff;
-        const diagTol = 0.500;
-        if (diagSum > diagTol) {
-            coff = Math.sqrt(diagSum) * 0.5;
-            if (denomCoff * numerator < 0.0)
-                coff = -coff;
-        }
-        else {
-            coff = numerator * reciprocal;
-        }
-        return coff;
-    }
-    /** create a matrix from a quaternion.
-     * **WARNING:** There is frequent confusion over whether a "from quaternion" matrix is organized by rows and columns.
-     * **WARNING:** If you find that the matrix seems to rotate by the opposite angle expect it, transpose it.
+    /**
+     * Create a matrix from a quaternion.
+     * **WARNING:** There is frequent confusion over whether a "from quaternion" matrix is organized by
+     * rows or columns. If you find that the matrix seems to rotate by the opposite angle, transpose it.
+     *
+     * Some math details can be found at
+     * http://marc-b-reynolds.github.io/quaternions/2017/08/08/QuatRotMatrix.html
      */
     static createFromQuaternion(quat) {
         const qqx = quat.x * quat.x;
@@ -2437,31 +2500,57 @@ export class Matrix3d {
         }
         else {
             const a = 1.0 / mag2;
-            const matrix = Matrix3d.createRowValues(a * (qqw + qqx - qqy - qqz), 2.0 * a * (quat.w * quat.z + quat.x * quat.y), 2.0 * a * (quat.x * quat.z - quat.w * quat.y), 2.0 * a * (quat.x * quat.y - quat.w * quat.z), a * (qqw - qqx + qqy - qqz), 2.0 * a * (quat.w * quat.x + quat.y * quat.z), 2.0 * a * (quat.x * quat.z + quat.w * quat.y), 2.0 * a * (quat.y * quat.z - quat.w * quat.x), a * (qqw - qqx - qqy + qqz));
+            const matrix = Matrix3d.createRowValues(
+            // first row
+            a * (qqw + qqx - qqy - qqz), 2.0 * a * (quat.w * quat.z + quat.x * quat.y), 2.0 * a * (quat.x * quat.z - quat.w * quat.y), 
+            // second row
+            2.0 * a * (quat.x * quat.y - quat.w * quat.z), a * (qqw - qqx + qqy - qqz), 2.0 * a * (quat.w * quat.x + quat.y * quat.z), 
+            // third row
+            2.0 * a * (quat.x * quat.z + quat.w * quat.y), 2.0 * a * (quat.y * quat.z - quat.w * quat.x), a * (qqw - qqx - qqy + qqz));
             return matrix;
         }
     }
-    /** convert the matrix to a quaternion.
-     * @note This calculation requires the matrix to have unit length rows and columns.
-     * **WARNING:** There is frequent confusion over whether a "from quaternion" matrix is organized by rows and columns.
-     * **WARNING:** If you find that the matrix seems to rotate by the opposite angle expect it, transpose it.
+    /** Calculate quaternion terms used to convert matrix to a quaternion */
+    static computeQuatTerm(numerator, denomCoff, reciprocal, diagSum) {
+        let coff;
+        const diagTol = 0.500;
+        if (diagSum > diagTol) {
+            coff = 0.5 * Math.sqrt(diagSum);
+            if (denomCoff * numerator < 0.0)
+                coff = -coff;
+        }
+        else {
+            coff = numerator * reciprocal;
+        }
+        return coff;
+    }
+    /**
+     * Create `this` matrix to a quaternion.
+     * **Note:** This calculation requires `this` matrix to have unit length rows and columns.
+     * **WARNING:** There is frequent confusion over whether a "from quaternion" matrix is organized by
+     * rows or columns. If you find that the matrix seems to rotate by the opposite angle, transpose it.
+     *
+     * Some math details can be found at
+     * http://marc-b-reynolds.github.io/quaternions/2017/08/08/QuatRotMatrix.html
      */
     toQuaternion() {
         const result = Point4d.createZero();
-        const props = [[this.coffs[0], this.coffs[3], this.coffs[6]],
+        const props = [
+            [this.coffs[0], this.coffs[3], this.coffs[6]],
             [this.coffs[1], this.coffs[4], this.coffs[7]],
-            [this.coffs[2], this.coffs[5], this.coffs[8]]];
+            [this.coffs[2], this.coffs[5], this.coffs[8]],
+        ];
         const xx = props[0][0];
         const yy = props[1][1];
         const zz = props[2][2];
         const dSum = [];
-        let denom, maxIndex, i;
         dSum[0] = 1.0 + xx - yy - zz;
         dSum[1] = 1.0 - xx + yy - zz;
         dSum[2] = 1.0 - xx - yy + zz;
         dSum[3] = 1.0 + xx + yy + zz;
-        maxIndex = 0;
-        for (i = 1; i < 4; i++) {
+        let denom;
+        let maxIndex = 0;
+        for (let i = 1; i <= 3; i++) {
             if (dSum[i] > dSum[maxIndex])
                 maxIndex = i;
         }