@itwin/core-geometry 4.0.0-dev.4 → 4.0.0-dev.41

package/lib/esm/geometry3d/Matrix3d.js

@@ -12,6 +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 arctan newcommand diagonalization
 /**
  * PackedMatrix3dOps contains static methods for matrix operations where the matrix is a Float64Array.
  * * The Float64Array contains the matrix entries in row-major order
@@ -307,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)) {
@@ -421,9 +422,20 @@ export class Matrix3d {
         return result;
     }
     /**
-   * Copy the transpose of the coffs to the inverseCoffs.
-   * * Mark the matrix as inverseStored.
-   */
+     * Create the inverseCoffs member (filled with zeros)
+     * This is for use by matrix * matrix multiplications which need to be sure the member is there to be
+     * filled with method-specific content.
+     */
+    createInverseCoffsWithZeros() {
+        if (!this.inverseCoffs) {
+            this.inverseState = InverseMatrixState.unknown;
+            this.inverseCoffs = new Float64Array(9);
+        }
+    }
+    /**
+     * Copy the transpose of the coffs to the inverseCoffs.
+     * * Mark the matrix as inverseStored.
+     */
     setupInverseTranspose() {
         const coffs = this.coffs;
         this.inverseState = InverseMatrixState.inverseStored;
@@ -639,8 +651,10 @@ export class Matrix3d {
         return undefined;
     }
     /**
-     * Construct a rigid matrix using vectorA and its 2 perpendicular.
+     * Construct a rigid matrix (orthogonal matrix with +1 determinant) using vectorA and its 2 perpendicular.
+     * * If axisOrder is not passed then `AxisOrder = AxisOrder.ZXY` is used as default.
      * * This function internally uses createPerpendicularVectorFavorXYPlane and createRigidFromColumns.
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/2PerpendicularVectorsTo1Vector
      */
     static createRigidHeadsUp(vectorA, axisOrder = AxisOrder.ZXY, result) {
         const vectorB = Matrix3d.createPerpendicularVectorFavorXYPlane(vectorA);
@@ -651,7 +665,14 @@ export class Matrix3d {
         }
         return Matrix3d.createIdentity(result);
     }
-    /** Return the matrix for rotation of `angle` around `axis` */
+    /**
+     * Return the matrix for rotation of `angle` around desired `axis`
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/CubeRotationAroundAnAxis
+     * @param axis the axis of rotation
+     * @param angle the angle of rotation
+     * @param result caller-allocated matrix (optional)
+     * @returns the `rotation matrix` or `undefined` (if axis magnitude is near zero).
+     */
     static createRotationAroundVector(axis, angle, result) {
         // Rodriguez formula (matrix form), https://mathworld.wolfram.com/RodriguesRotationFormula.html
         const c = angle.cos();
@@ -665,7 +686,7 @@ export class Matrix3d {
         }
         return undefined;
     }
-    /** Returns a rotation of specified angle around an axis
+    /** Returns a rotation of specified angle around one of the main axis (X,Y,Z).
      * @param axisIndex index of axis (AxisIndex.X, AxisIndex.Y, AxisIndex.Z) kept fixed by the rotation.
      * @param angle angle of rotation
      * @param result optional result matrix.
@@ -688,14 +709,33 @@ export class Matrix3d {
         return myResult;
     }
     /**
-   * Replace current columns Ui and Uj with (c*Ui - s*Uj) and (c*Uj + s*Ui).
-   * * There is no checking for i,j being 0,1,2.
-   * * This is used in compute intensive inner loops
-   * @param i first row index. **must be 0,1,2** (unchecked)
-   * @param j second row index. **must be 0,1,2** (unchecked)
-   * @param c fist coefficient
-   * @param s second coefficient
-   */
+     * Replace current rows Ui and Uj with (c*Ui + s*Uj) and (c*Uj - s*Ui).
+     * * There is no checking for i,j being 0,1,2.
+     * @param i first row index. **must be 0,1,2** (unchecked)
+     * @param j second row index. **must be 0,1,2** (unchecked)
+     * @param c fist coefficient
+     * @param s second coefficient
+     */
+    applyGivensRowOp(i, j, c, s) {
+        let ii = 3 * i;
+        let jj = 3 * j;
+        const limit = ii + 3;
+        for (; ii < limit; ii++, jj++) {
+            const a = this.coffs[ii];
+            const b = this.coffs[jj];
+            this.coffs[ii] = a * c + b * s;
+            this.coffs[jj] = -a * s + b * c;
+        }
+    }
+    /**
+     * Replace current columns Ui and Uj with (c*Ui + s*Uj) and (c*Uj - s*Ui).
+     * * There is no checking for i,j being 0,1,2.
+     * * This is used in compute intensive inner loops
+     * @param i first row index. **must be 0,1,2** (unchecked)
+     * @param j second row index. **must be 0,1,2** (unchecked)
+     * @param c fist coefficient
+     * @param s second coefficient
+     */
     applyGivensColumnOp(i, j, c, s) {
         const limit = i + 9;
         for (; i < limit; i += 3, j += 3) {
@@ -706,12 +746,12 @@ export class Matrix3d {
         }
     }
     /**
-   * Create a matrix from column vectors.
-   * ```
-   * equation
-   * \begin{bmatrix}U_x & V_x & W_x \\ U_y & V_y & W_y \\ U_z & V_z & W_z \end{bmatrix}
-   * ```
-   */
+     * Create a matrix from column vectors.
+     * ```
+     * equation
+     * \begin{bmatrix}U_x & V_x & W_x \\ U_y & V_y & W_y \\ U_z & V_z & W_z \end{bmatrix}
+     * ```
+     */
     static createColumns(vectorU, vectorV, vectorW, result) {
         return Matrix3d.createRowValues(vectorU.x, vectorV.x, vectorW.x, vectorU.y, vectorV.y, vectorW.y, vectorU.z, vectorV.z, vectorW.z, result);
     }
@@ -724,29 +764,36 @@ 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 the standard cube by 45 degrees ccw around Y to bring its left or right vertical edge to center.
-     * * Optionally rotate the standard cube by 35.264 degrees ccw around X (isometric rotation).
-     * * This is expected to be used with various principal unit vectors that are perpendicular to each other.
+     * * 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.
      * * 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)
      * * STANDARD RIGHT VIEW: createViewedAxes(Vector3d.unitY(), Vector3d.unitZ(), 0, 0)
      * * STANDARD LEFT VIEW: createViewedAxes(Vector3d.unitY(-1), Vector3d.unitZ(), 0, 0)
      * * STANDARD BOTTOM VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitY(-1), 0, 0)
+     * * STANDARD ISO VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitZ(), -1, 1)
+     * * STANDARD RIGHT ISO VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitZ(), 1, 1)
+     * * Front, right, back, left, top, and bottom standard views are views from faces of the cube
+     * and iso and right iso standard views are views from corners of the cube.
      * * Note: createViewedAxes is column-based so always returns local to world
      *
      * @param rightVector ColumnX of the returned matrix. Expected to be perpendicular to upVector.
      * @param upVector ColumnY of the returned matrix. Expected to be perpendicular to rightVector.
-     * @param leftNoneRight Specifies the ccw rotation around Y axis. Normally one of "-1", "0", and "1", where
-     * "-1" indicates rotation by 45 degrees to bring the left vertical edge to center, "0" means no rotation,
+     * @param leftNoneRight Specifies the ccw rotation around `upVector` axis. Normally one of "-1", "0", and "1",
+     * where "-1" indicates rotation by 45 degrees to bring the left vertical edge to center, "0" means no rotation,
      * and "1" indicates rotation by 45 degrees to bring the right vertical edge to center. Other numbers are
      * used as multiplier for this 45 degree rotation.
-     * @param topNoneBottom Specifies the ccw rotation around X axis. Normally one of "-1", "0", and "1", where
-     * "-1" indicates isometric rotation (35.264 degrees) to bring the bottom upward, "0" means no rotation,
+     * @param topNoneBottom Specifies the ccw rotation around `rightVector` axis. Normally one of "-1", "0", and "1",
+     * where "-1" indicates isometric rotation (35.264 degrees) to bring the bottom upward, "0" means no rotation,
      * and "1" indicates isometric rotation (35.264 degrees) to bring the top downward. Other numbers are
      * used as multiplier for the 35.264 degree rotation.
      * @returns matrix = [rightVector, upVector, rightVector cross upVector] with the applied rotations specified
@@ -784,9 +831,11 @@ export class Matrix3d {
      * * Default is TOP view (`local X = world X`, `local Y = world Y`, `local Z = world Z`).
      * * To change view from the TOP to one of the other 7 standard views, we need to multiply "world data" to
      * the corresponding matrix1 provided by `createStandardWorldToView(index, false)` and then
-     * `matrix1.multiply(world data)` will returns "local data".
+     * `matrix1.multiply(world data)` will return "local data".
      * * To change view back to the TOP, we need to multiply "local data" to the corresponding matrix2 provided
      * by `createStandardWorldToView(index, true)` and then `matrix2.multiply(local data)` will returns "world data".
+     * * Note: No matter how you rotate the world axis, local X is always pointing right, local Y is always pointing up,
+     * and local Z is always pointing toward you.
      *
      * @param index standard view index `StandardViewIndex.Top, Bottom, Left, Right, Front, Back, Iso, RightIso`
      * @param invert if false (default), the return matrix is world to local (view) and if true, the the return
@@ -795,200 +844,388 @@ export class Matrix3d {
      */
     static createStandardWorldToView(index, invert = false, result) {
         switch (index) {
-            // start with TOP view, ccw rotation by 180 degrees around X
+            // Start with TOP view, ccw rotation by 180 degrees around X
             case StandardViewIndex.Bottom:
                 result = Matrix3d.createRowValues(1, 0, 0, 0, -1, 0, 0, 0, -1);
                 break;
-            // start with TOP view, ccw rotation by -90 degrees around X and by 90 degrees around Z
+            // Start with TOP view, ccw rotation by -90 degrees around X and by 90 degrees around Z
             case StandardViewIndex.Left:
                 result = Matrix3d.createRowValues(0, -1, 0, 0, 0, 1, -1, 0, 0);
                 break;
-            // start with TOP view, ccw rotation by -90 degrees around X and by -90 degrees around Z
+            // Start with TOP view, ccw rotation by -90 degrees around X and by -90 degrees around Z
             case StandardViewIndex.Right:
                 result = Matrix3d.createRowValues(0, 1, 0, 0, 0, 1, 1, 0, 0);
                 break;
-            // start with TOP view, ccw rotation by -90 degrees around X
+            // Start with TOP view, ccw rotation by -90 degrees around X
             case StandardViewIndex.Front:
                 result = Matrix3d.createRowValues(1, 0, 0, 0, 0, 1, 0, -1, 0);
                 break;
-            // start with TOP view, ccw rotation by -90 degrees around X and by 180 degrees around Z
+            // Start with TOP view, ccw rotation by -90 degrees around X and by 180 degrees around Z
             case StandardViewIndex.Back:
                 result = Matrix3d.createRowValues(-1, 0, 0, 0, 0, 1, 0, 1, 0);
                 break;
+            /**
+             * Isometric view
+             * Start with FRONT view, ccw rotation by -45 degrees around Y and by arctan(1/sqrt(2)) ~ 35.264 degrees around X
+             * cos(45) = 1/sqrt(2) = 0.70710678118 and sin(45) = 1/sqrt(2) = 0.70710678118
+             * cos(35.264) = 2/sqrt(6) = 0.81649658092 and sin(35.264) = 1/sqrt(3) = 0.57735026919
+             * More info: https://en.wikipedia.org/wiki/Isometric_projection
+             */
             case StandardViewIndex.Iso:
-                // start with FRONT view, ccw rotation by -45 degrees around Y and by 35.264 degrees around X
                 result = Matrix3d.createRowValues(0.707106781186548, -0.70710678118654757, 0.00000000000000000, 0.408248290463863, 0.40824829046386302, 0.81649658092772603, -0.577350269189626, -0.57735026918962573, 0.57735026918962573);
                 break;
+            // Start with FRONT view, ccw rotation by 45 degrees around Y and by 35.264 degrees around X
             case StandardViewIndex.RightIso:
                 result = Matrix3d.createRowValues(0.707106781186548, 0.70710678118654757, 0.00000000000000000, -0.408248290463863, 0.40824829046386302, 0.81649658092772603, 0.577350269189626, -0.57735026918962573, 0.57735026918962573);
                 break;
-            case StandardViewIndex.Top: // no rotation
+            // no rotation
+            case StandardViewIndex.Top:
             default:
                 result = Matrix3d.createIdentity(result);
         }
         if (invert)
-            result.transposeInPlace();
+            result.transposeInPlace(); // matrix is rigid so transpose and inverse are the same
         return result;
     }
-    /*
-    // this implementation has problems distinguishing failure (normalize) from small angle.
-    public getAxisAndAngleOfRotation(): { axis: Vector3d, angle: Angle, error: boolean } {
-  
-      const result = { axis: Vector3d.unitZ(), angle: Angle.createRadians(0), error: true };
-      if (this.isIdentity) {
-        result.error = false;
-        return result;
-      }
-      if (!this.isRigid())
-        return result;
-      const QMinusI = this.clone();
-      QMinusI.coffs[0] -= 1.0;
-      QMinusI.coffs[4] -= 1.0;
-      QMinusI.coffs[8] -= 1.0;
-      // Each column of (Q - I) is the motion of the corresponding axis vector
-      // during the rotation.
-      // Only one of the three axes can really be close to the rotation axis.
-      const delta0 = QMinusI.columnX();
-      const delta1 = QMinusI.columnY();
-      const delta2 = QMinusI.columnZ();
-      const cross01 = delta0.crossProduct(delta1);
-      const cross12 = delta1.crossProduct(delta2);
-      const cross20 = delta2.crossProduct(delta0);
-  
-      const aa01 = cross01.magnitudeSquared();
-      const aa12 = cross12.magnitudeSquared();
-      const aa20 = cross20.magnitudeSquared();
-  
-      const cross = cross01.clone(); // This will end up as the biggest cross product
-      const v0 = delta0.clone();  // This will end up as one of the two largest delta vectors
-      let aaMax = aa01;
-      if (aa12 > aaMax) {
-        cross.setFrom(cross12);
-        aaMax = aa12;
-        v0.setFrom(delta1);
-      }
-      if (aa20 > aaMax) {
-        cross.setFrom(cross20);
-        aaMax = aa20;
-        v0.setFrom(delta2);
-      }
-  
-      if (aaMax === 0.0) {
-        // The vectors did not move.  Just accept the zero rotation, with error flag set.
-        return result;
-      }
-  
-      v0.normalizeInPlace();
-      // V0 is a unit vector perpendicular to the rotation axis.
-      // Rotate it.   Its image V1 is also a unit vector, and the angle from V0 to V1 is the quat angle.
-      // CrossProduct is axis vector times sine of angle.
-      // Dot Product is cosine of angle.
-      // V2 is zero in 180 degree case, so we use the Cross from the search as the axis
-      //   as direction, being careful to keep sine positive.
-      const v1 = this.multiplyVector(v0);
-      const v2 = v0.crossProduct(v1);
-      const sine = v2.magnitude();
-      if (v2.dotProduct(cross) < 0.0)
-        cross.scaleInPlace(-1.0);
-      const cosine = v0.dotProduct(v1);
-      result.angle.setRadians(Math.atan2(sine, cosine));
-      result.axis.setFrom(cross);
-      result.error = !result.axis.tryNormalizeInPlace();
-      return result
-    }
-  */
-    /**
-     * Compute the (unit vector) axis and angle of rotation.
+    /**
+     * Apply (in place) a jacobi eigenvalue algorithm.
+     * @param i row index of zeroed member
+     * @param j column index of zeroed member
+     * @param leftEigenvectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     * @param lambda a matrix that its diagonal entries will be filled by eigenvalues and its non-diagonal elements
+     * converge to 0 (allocated by caller, computed and filled by this function).
+     */
+    applySymmetricJacobi(i, j, leftEigenvectors, lambda) {
+        const sii = lambda.at(i, i);
+        const sjj = lambda.at(j, j);
+        const sij = lambda.at(i, j);
+        if (Math.abs(sij) < 1.0e-15 * (sii + sjj))
+            return 0.0;
+        const jacobi = Angle.trigValuesToHalfAngleTrigValues(sii - sjj, 2.0 * sij);
+        const c = jacobi.c;
+        const s = jacobi.s;
+        /**
+         * The following check does not exist in applyFastSymmetricJacobi because here if we don't return
+         * early, the matrix remains untouched. However, applyFastSymmetricJacobi zeroes-out elements ij
+         * and ji. Therefore, if we return early in applyFastSymmetricJacobi, zeroing-out wont happen.
+         */
+        if (Math.abs(s) < 2.0e-15)
+            return 0.0;
+        /**
+         * If you apply the following 2 lines to a symmetric matrix, you get same lines used in
+         * applyFastSymmetricJacobi. There are 2 differences which make applyFastSymmetricJacobi
+         * more efficient. First, we directly set elements ij and ji equal to zero rather than
+         * calculation them. Second, we copy symmetric elements from upper triangle to lower
+         * instead of calculating them.
+         */
+        lambda.applyGivensRowOp(i, j, c, s);
+        lambda.applyGivensColumnOp(i, j, c, s);
+        leftEigenvectors.applyGivensColumnOp(i, j, c, s);
+        return Math.abs(sij);
+    }
+    /**
+     * Factor `this` matrix as a product `U * lambda * UT` where `U` is an orthogonal matrix and `lambda`
+     * is a diagonal matrix.
+     *
+     * * **Note 1:** You must apply this function to a `symmetric` matrix. Otherwise, the lower triangle is ignored
+     * and the upper triangle is mirrored to the lower triangle to enforce symmetry.
+     * * **Note 2:** This function is replaced by a faster method called `fastSymmetricEigenvalues` so consider
+     * using the fast version instead.
+     * @param leftEigenvectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     * @param lambda a vector that its entries will be filled by eigenvalues of `this` Matrix3d (allocated by
+     * caller, computed and filled by this function).
+     */
+    symmetricEigenvalues(leftEigenvectors, lambda) {
+        const matrix = this.clone();
+        leftEigenvectors.setIdentity();
+        matrix.coffs[3] = matrix.coffs[1];
+        matrix.coffs[6] = matrix.coffs[2];
+        matrix.coffs[7] = matrix.coffs[5];
+        const tolerance = 1.0e-12 * this.sumSquares();
+        const numberOfIterations = 7;
+        for (let iteration = 0; iteration < numberOfIterations; iteration++) {
+            const sum = this.applySymmetricJacobi(0, 1, leftEigenvectors, matrix)
+                + this.applySymmetricJacobi(0, 2, leftEigenvectors, matrix)
+                + this.applySymmetricJacobi(1, 2, leftEigenvectors, matrix);
+            if (sum < tolerance) {
+                lambda.set(matrix.at(0, 0), matrix.at(1, 1), matrix.at(2, 2));
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Apply (in place) a jacobi eigenvalue algorithm that diagonalize `this` matrix, i.e., zeros out this.at(i,j).
+     * * During diagonalization, the upper triangle is mirrored to lower triangle to enforce symmetry.
+     * * Math details can be found at docs/learning/geometry/Matrix.md
+     * @param i row index of zeroed member.
+     * @param j column index of zeroed member.
+     * @param k other row/column index (different from i and j).
+     * @param leftEigenVectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     */
+    applyFastSymmetricJacobi(i, j, k, leftEigenVectors) {
+        const indexII = 4 * i;
+        const indexJJ = 4 * j;
+        const indexIJ = 3 * i + j;
+        const indexJI = 3 * j + i;
+        const indexIK = 3 * i + k;
+        const indexKI = 3 * k + i;
+        const indexJK = 3 * j + k;
+        const indexKJ = 3 * k + j;
+        const sii = this.coffs[indexII];
+        const sjj = this.coffs[indexJJ];
+        const sij = this.coffs[indexIJ];
+        if (Math.abs(sij) < 1.0e-15 * (sii + sjj))
+            return 0.0;
+        const jacobi = Angle.trigValuesToHalfAngleTrigValues(sii - sjj, 2.0 * sij);
+        const c = jacobi.c;
+        const s = jacobi.s;
+        const cc = c * c;
+        const ss = s * s;
+        const sc2 = 2.0 * c * s;
+        this.coffs[indexII] = cc * sii + sc2 * sij + ss * sjj;
+        this.coffs[indexJJ] = ss * sii - sc2 * sij + cc * sjj;
+        this.coffs[indexIJ] = 0.0;
+        this.coffs[indexJI] = 0.0;
+        const a = this.coffs[indexIK];
+        const b = this.coffs[indexJK];
+        this.coffs[indexIK] = c * a + s * b;
+        this.coffs[indexJK] = -s * a + c * b;
+        this.coffs[indexKI] = this.coffs[indexIK];
+        this.coffs[indexKJ] = this.coffs[indexJK];
+        leftEigenVectors.applyGivensColumnOp(i, j, c, s);
+        return Math.abs(sij);
+    }
+    /**
+     * Factor `this` matrix as a product `U * lambda * UT` where `U` is an orthogonal matrix and `lambda`
+     * is a diagonal matrix.
+     *
+     * * **Note:** You must apply this function to a `symmetric` matrix. Otherwise, the lower triangle is ignored
+     * and the upper triangle is mirrored to the lower triangle to enforce symmetry.
+     * * Math details can be found at docs/learning/geometry/Matrix.md
+     * @param leftEigenvectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     * @param lambda a vector that its entries will be filled by eigenvalues of `this` Matrix3d (allocated by
+     * caller, computed and filled by this function).
+     */
+    fastSymmetricEigenvalues(leftEigenvectors, lambda) {
+        const matrix = this.clone();
+        leftEigenvectors.setIdentity();
+        const tolerance = 1.0e-12 * this.sumSquares();
+        const numberOfIterations = 7;
+        for (let iteration = 0; iteration < numberOfIterations; iteration++) {
+            const sum = matrix.applyFastSymmetricJacobi(0, 1, 2, leftEigenvectors)
+                + matrix.applyFastSymmetricJacobi(0, 2, 1, leftEigenvectors)
+                + matrix.applyFastSymmetricJacobi(1, 2, 0, leftEigenvectors);
+            if (sum < tolerance) {
+                lambda.set(matrix.at(0, 0), matrix.at(1, 1), matrix.at(2, 2));
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Compute the (unit vector) axis and angle for the rotation generated by `this` Matrix3d.
+     * * Math details can be found at docs/learning/geometry/Angle.md
      * @returns Returns axis and angle of rotation with result.ok === true when the conversion succeeded.
      */
     getAxisAndAngleOfRotation() {
         const trace = this.coffs[0] + this.coffs[4] + this.coffs[8];
-        // trace = (xx + yy * zz) * (1-c) + 3 * c = 1 + 2c ==> c = (trace-1) / 2
-        const skewXY = this.coffs[3] - this.coffs[1]; // == 2sz
-        const skewYZ = this.coffs[7] - this.coffs[5]; // == 2sx
-        const skewZX = this.coffs[2] - this.coffs[6]; // == 2sy
-        const c = (trace - 1.0) / 2.0;
-        const s = Geometry.hypotenuseXYZ(skewXY, skewYZ, skewZX) / 2.0;
-        const e = c * c + s * s - 1.0;
+        const skewXY = this.coffs[3] - this.coffs[1]; // 2*z*sin
+        const skewYZ = this.coffs[7] - this.coffs[5]; // 2*y*sin
+        const skewZX = this.coffs[2] - this.coffs[6]; // 2*x*sin
+        // trace = (m00^2 + m11^2 + m22^2) * (1-cos) + 3cos = (1-cos) + 3cos = 1 + 2cos ==> cos = (trace-1) / 2
+        const c = (trace - 1.0) / 2.0; // cosine
+        const s = Geometry.hypotenuseXYZ(skewXY, skewYZ, skewZX) / 2.0; // sine
+        const e = c * c + s * s - 1.0; // s^2 + c^2 = 1
+        // if s^2 + c^2 != 1 then we have a bad matrix so return false
         if (Math.abs(e) > Geometry.smallAngleRadians) {
-            // the sine and cosine are not a unit circle point.   bad matrix . ..
             return { axis: Vector3d.create(0, 0, 1), angle: Angle.createRadians(0), ok: false };
         }
+        // sin is close to 0 then we got to special cases (angle 0 or 180) which needs to be handled differently
         if (Math.abs(s) < Geometry.smallAngleRadians) {
-            // There is no significant skew.
-            // The matrix is symmetric
-            // So it has simple eigenvalues -- either (1,1,1) or (1,-1,-1).
-            if (c > 0) // no rotation
+            if (c > 0) // sin = 0 and cos = 1 so angle = 0 (i.e., no rotation)
                 return { axis: Vector3d.create(0, 0, 1), angle: Angle.createRadians(0), ok: true };
-            // 180 degree flip around some axis ?
-            // Look for the simple case of a principal rotation ...
-            // look for a pair of (-1) entries on the diagonal ...
+            /**
+             * If sin = 0 and cos = -1 then angle = 180 (i.e., 180 degree rotation around some axis)
+             * then the rotation matrix becomes
+             *                                 2x^2-1  2xy      2xz
+             *                                 2xy     2y^2-1   2yz
+             *                                 2xz     2yz      2z^2-1
+             * Note that the matrix is "symmetric".
+             * If rotation is around one the standard basis then non-diagonal entries become 0 and we
+             * have one 1 and two -1s on the diagonal.
+             * If rotation is around an axis other than standard basis, then the axis is the eigenvector
+             * of the rotation matrix with eigenvalue = 1.
+             */
             const axx = this.coffs[0];
             const ayy = this.coffs[4];
             const azz = this.coffs[8];
-            const theta180 = Angle.createDegrees(180);
-            // Look for principal axis flips as a special case . ..
+            // Look for a pair of "-1" entries on the diagonal (for rotation around the basis X,Y,Z axis)
             if (Geometry.isAlmostEqualNumber(-1.0, ayy) && Geometry.isAlmostEqualNumber(-1, azz)) {
-                // rotate around
-                return { axis: Vector3d.create(1, 0, 0), angle: theta180, ok: true };
+                return { axis: Vector3d.create(1, 0, 0), angle: Angle.createDegrees(180), ok: true };
             }
             else if (Geometry.isAlmostEqualNumber(-1.0, axx) && Geometry.isAlmostEqualNumber(-1, azz)) {
-                return { axis: Vector3d.create(0, 1, 0), angle: theta180, ok: true };
+                return { axis: Vector3d.create(0, 1, 0), angle: Angle.createDegrees(180), ok: true };
             }
             else if (Geometry.isAlmostEqualNumber(-1.0, axx) && Geometry.isAlmostEqualNumber(-1, ayy)) {
-                return { axis: Vector3d.create(0, 0, 1), angle: theta180, ok: true };
+                return { axis: Vector3d.create(0, 0, 1), angle: Angle.createDegrees(180), ok: true };
             }
-            // 180 degree flip around some other axis ...
-            // eigenvalues will have 1.0 once, -1.0 twice.
-            // These cases look for each place (x,y,z) that the 1.0 might appear.
-            // But fastSymmetricEigenvalues reliably always seems to put the 1.0 as the x eigenvalue.
-            // so only the getColumn(0) return seems reachable in unit tests.
+            // Look for eigenvector with eigenvalue = 1
             const eigenvectors = Matrix3d.createIdentity();
             const eigenvalues = Vector3d.create(0, 0, 0);
-            if (this.fastSymmetricEigenvalues(eigenvectors, eigenvalues)) {
+            if (this.fastSymmetricEigenvalues(eigenvectors, eigenvalues)) { // note: this matrix is "symmetric"
                 for (let axisIndex = 0; axisIndex < 2; axisIndex++) {
                     const lambda = eigenvalues.at(axisIndex);
                     if (Geometry.isAlmostEqualNumber(1, lambda))
-                        return { axis: eigenvectors.getColumn(axisIndex), angle: theta180, ok: true };
+                        return { axis: eigenvectors.getColumn(axisIndex), angle: Angle.createDegrees(180), ok: true };
                 }
-                // Don't know if this can be reached ....
+                // if no eigenvalue = 1 was found return false
                 return { axis: Vector3d.create(0, 0, 1), angle: Angle.createRadians(0), ok: false };
             }
+            // if no axis was found return false
             return { axis: Vector3d.create(0, 0, 1), angle: Angle.createRadians(0), ok: false };
         }
+        // good matrix and non-zero sine
         const a = 1.0 / (2.0 * s);
-        const result = { axis: Vector3d.create(skewYZ * a, skewZX * a, skewXY * a), angle: Angle.createAtan2(s, c), ok: true };
+        const result = {
+            axis: Vector3d.create(skewYZ * a, skewZX * a, skewXY * a),
+            angle: Angle.createAtan2(s, c),
+            ok: true,
+        };
         return result;
     }
     /**
-     * Returns a matrix that rotates from vectorA to vectorB.
+     * Rotate columns i and j of `this` matrix to make them perpendicular using the angle that zero-out
+     * `thisTranspose * this`.
+     * @param i row index of zeroed member.
+     * @param j column index of zeroed member.
+     * @param matrixU a matrix that its columns will be filled by the right eigenvectors of `thisTranspose * this`
+     * (allocated by caller, computed and filled by this function). Note that columns of matrixU will be mutually
+     *  perpendicular because `thisTranspose * this` matrix is symmetric.
      */
-    static createRotationVectorToVector(vectorA, vectorB, result) {
-        return this.createPartialRotationVectorToVector(vectorA, 1.0, vectorB, result);
+    applyJacobiColumnRotation(i, j, matrixU) {
+        const uDotU = this.coffs[i] * this.coffs[i]
+            + this.coffs[i + 3] * this.coffs[i + 3]
+            + this.coffs[i + 6] * this.coffs[i + 6];
+        const vDotV = this.coffs[j] * this.coffs[j]
+            + this.coffs[j + 3] * this.coffs[j + 3]
+            + this.coffs[j + 6] * this.coffs[j + 6];
+        const uDotV = this.coffs[i] * this.coffs[j]
+            + this.coffs[i + 3] * this.coffs[j + 3]
+            + this.coffs[i + 6] * this.coffs[j + 6];
+        const jacobi = Angle.trigValuesToHalfAngleTrigValues(uDotU - vDotV, 2.0 * uDotV);
+        const c = jacobi.c;
+        const s = jacobi.s;
+        if (Math.abs(s) < 2.0e-15)
+            return 0.0;
+        this.applyGivensColumnOp(i, j, c, s); // make columns i and j of `this` matrix perpendicular
+        matrixU.applyGivensRowOp(i, j, c, s); // right eigenvalues of `thisTranspose * this`
+        return Math.abs(uDotV);
+    }
+    /**
+     * Factor `this` matrix as a product `VD * U` where `VD` has mutually perpendicular columns and `U` is orthogonal.
+     * @param matrixVD a matrix that its columns will be filled by rotating columns of `this` to make them mutually
+     * perpendicular (allocated by caller, computed and filled by this function).
+     * @param matrixU a matrix that its columns will be filled by the right eigenvectors of `thisTranspose * this`
+     * (allocated by caller, computed and filled by this function). Note that columns of matrixU will be mutually
+     *  perpendicular because `thisTranspose * this` matrix is symmetric.
+     */
+    factorPerpendicularColumns(matrixVD, matrixU) {
+        matrixVD.setFrom(this);
+        matrixU.setIdentity();
+        const tolerance = 1.0e-12 * this.sumSquares();
+        const numberOfIterations = 7;
+        for (let iteration = 0; iteration < numberOfIterations; iteration++) {
+            const sum = matrixVD.applyJacobiColumnRotation(0, 1, matrixU)
+                + matrixVD.applyJacobiColumnRotation(0, 2, matrixU)
+                + matrixVD.applyJacobiColumnRotation(1, 2, matrixU);
+            if (sum < tolerance) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Factor `this` matrix as a product `V * D * U` where `V` and `U` are orthogonal and `D` is diagonal with
+     * positive entries.
+     * * This is formally known as the `Singular Value Decomposition` or `SVD`.
+     * @param matrixV an orthogonal matrix that its columns will be filled by the left eigenvectors of
+     * `thisTranspose * this` (allocated by caller, computed and filled by this function).
+     * @param scale singular values of `this` (allocated by caller, computed and filled by this function).
+     * The singular values in the `scale` are non-negative and decreasing.
+     * @param matrixU an orthogonal matrix that its columns will be filled by the right eigenvectors of
+     * `thisTranspose * this` (allocated by caller, computed and filled by this function).
+     */
+    factorOrthogonalScaleOrthogonal(matrixV, scale, matrixU) {
+        const matrixVD = Matrix3d.createZero();
+        if (!this.factorPerpendicularColumns(matrixVD, matrixU))
+            return false;
+        const column = [];
+        column.push(matrixVD.getColumn(0));
+        column.push(matrixVD.getColumn(1));
+        column.push(matrixVD.getColumn(2));
+        scale.set(column[0].magnitude(), column[1].magnitude(), column[2].magnitude()); // singular values of `this`
+        const det = matrixVD.determinant();
+        if (det < 0)
+            scale.z = -scale.z;
+        const almostZero = 1.0e-15;
+        const scaleXIsZero = Math.abs(scale.x) < almostZero;
+        const scaleYIsZero = Math.abs(scale.y) < almostZero;
+        const scaleZIsZero = Math.abs(scale.z) < almostZero;
+        // NOTE: We assume any zero-magnitude column(s) of matrixVD are last
+        if (!scaleXIsZero && !scaleYIsZero && !scaleZIsZero) { // full rank
+            matrixV = matrixVD.scaleColumns(1 / scale.x, 1 / scale.y, 1 / scale.z, matrixV);
+        }
+        else if (!scaleXIsZero && !scaleYIsZero) { // rank 2
+            column[0].scaleInPlace(1 / scale.x);
+            column[1].scaleInPlace(1 / scale.y);
+            column[2] = column[0].unitCrossProduct(column[1], column[2]);
+            matrixV.setColumns(column[0], column[1], column[2]);
+        }
+        else if (!scaleXIsZero) { // rank 1
+            matrixV = Matrix3d.createRigidHeadsUp(column[0], AxisOrder.XYZ, matrixV); // preserve column0
+        }
+        else { // rank 0
+            matrixV.setIdentity();
+        }
+        return true;
     }
     /**
      * Return a matrix that rotates a fraction of the angular sweep from vectorA to vectorB.
      * @param vectorA initial vector position
-     * @param fraction fractional rotation.  1.0 is "all the way"
+     * @param fraction fractional rotation (1 means rotate all the way)
      * @param vectorB final vector position
      * @param result optional result matrix.
      */
     static createPartialRotationVectorToVector(vectorA, fraction, vectorB, result) {
         let upVector = vectorA.unitCrossProduct(vectorB);
-        if (upVector) { // the usual case --
+        // the usual case (both vectors and also their cross product is non-zero)
+        if (upVector) {
             return Matrix3d.createRotationAroundVector(upVector, Angle.createRadians(fraction * vectorA.planarAngleTo(vectorB, upVector).radians));
         }
-        // fail if either vector is zero ...
+        // if either vector is zero
         if (Geometry.isSmallMetricDistance(vectorA.magnitude())
             || Geometry.isSmallMetricDistance(vectorB.magnitude()))
             return undefined;
-        // nonzero but aligned vectors ...
+        // aligned vectors (cross product = 0, dot product > 0)
         if (vectorA.dotProduct(vectorB) > 0.0)
             return Matrix3d.createIdentity(result);
-        // nonzero opposing vectors ..
+        // opposing vectors (cross product = 0, dot product < 0)
         upVector = Matrix3d.createPerpendicularVectorFavorPlaneContainingZ(vectorA, upVector);
         return Matrix3d.createRotationAroundVector(upVector, Angle.createRadians(fraction * Math.PI));
     }
+    /** Returns a matrix that rotates from vectorA to vectorB. */
+    static createRotationVectorToVector(vectorA, vectorB, result) {
+        return this.createPartialRotationVectorToVector(vectorA, 1.0, vectorB, result);
+    }
     /** Create a 90 degree rotation around a principal axis */
     static create90DegreeRotationAroundAxis(axisIndex) {
         axisIndex = Geometry.cyclic3dAxis(axisIndex);
@@ -1009,43 +1246,78 @@ export class Matrix3d {
         }
     }
     /** Return (a copy of) the X column */
-    columnX(result) { return Vector3d.create(this.coffs[0], this.coffs[3], this.coffs[6], result); }
-    /** Return (a copy of)the Y column */
-    columnY(result) { return Vector3d.create(this.coffs[1], this.coffs[4], this.coffs[7], result); }
-    /** Return (a copy of)the Z column */
-    columnZ(result) { return Vector3d.create(this.coffs[2], this.coffs[5], this.coffs[8], result); }
+    columnX(result) {
+        return Vector3d.create(this.coffs[0], this.coffs[3], this.coffs[6], result);
+    }
+    /** Return (a copy of) the Y column */
+    columnY(result) {
+        return Vector3d.create(this.coffs[1], this.coffs[4], this.coffs[7], result);
+    }
+    /** Return (a copy of) the Z column */
+    columnZ(result) {
+        return Vector3d.create(this.coffs[2], this.coffs[5], this.coffs[8], result);
+    }
     /** Return the X column magnitude squared */
-    columnXMagnitudeSquared() { return Geometry.hypotenuseSquaredXYZ(this.coffs[0], this.coffs[3], this.coffs[6]); }
+    columnXMagnitudeSquared() {
+        return Geometry.hypotenuseSquaredXYZ(this.coffs[0], this.coffs[3], this.coffs[6]);
+    }
     /** Return the Y column magnitude squared */
-    columnYMagnitudeSquared() { return Geometry.hypotenuseSquaredXYZ(this.coffs[1], this.coffs[4], this.coffs[7]); }
+    columnYMagnitudeSquared() {
+        return Geometry.hypotenuseSquaredXYZ(this.coffs[1], this.coffs[4], this.coffs[7]);
+    }
     /** Return the Z column magnitude squared */
-    columnZMagnitudeSquared() { return Geometry.hypotenuseSquaredXYZ(this.coffs[2], this.coffs[5], this.coffs[8]); }
+    columnZMagnitudeSquared() {
+        return Geometry.hypotenuseSquaredXYZ(this.coffs[2], this.coffs[5], this.coffs[8]);
+    }
     /** Return the X column magnitude */
-    columnXMagnitude() { return Geometry.hypotenuseXYZ(this.coffs[0], this.coffs[3], this.coffs[6]); }
+    columnXMagnitude() {
+        return Geometry.hypotenuseXYZ(this.coffs[0], this.coffs[3], this.coffs[6]);
+    }
     /** Return the Y column magnitude */
-    columnYMagnitude() { return Geometry.hypotenuseXYZ(this.coffs[1], this.coffs[4], this.coffs[7]); }
+    columnYMagnitude() {
+        return Geometry.hypotenuseXYZ(this.coffs[1], this.coffs[4], this.coffs[7]);
+    }
     /** Return the Z column magnitude */
-    columnZMagnitude() { return Geometry.hypotenuseXYZ(this.coffs[2], this.coffs[5], this.coffs[8]); }
+    columnZMagnitude() {
+        return Geometry.hypotenuseXYZ(this.coffs[2], this.coffs[5], this.coffs[8]);
+    }
     /** Return magnitude of columnX cross columnY. */
     columnXYCrossProductMagnitude() {
         return Geometry.crossProductMagnitude(this.coffs[0], this.coffs[3], this.coffs[6], this.coffs[1], this.coffs[4], this.coffs[7]);
     }
-    /** Return the X row magnitude d */
-    rowXMagnitude() { return Geometry.hypotenuseXYZ(this.coffs[0], this.coffs[1], this.coffs[2]); }
+    /** Return the X row magnitude */
+    rowXMagnitude() {
+        return Geometry.hypotenuseXYZ(this.coffs[0], this.coffs[1], this.coffs[2]);
+    }
     /** Return the Y row magnitude  */
-    rowYMagnitude() { return Geometry.hypotenuseXYZ(this.coffs[3], this.coffs[4], this.coffs[5]); }
+    rowYMagnitude() {
+        return Geometry.hypotenuseXYZ(this.coffs[3], this.coffs[4], this.coffs[5]);
+    }
     /** Return the Z row magnitude  */
-    rowZMagnitude() { return Geometry.hypotenuseXYZ(this.coffs[6], this.coffs[7], this.coffs[8]); }
-    /** Return the dot product of column X with column Y */
+    rowZMagnitude() {
+        return Geometry.hypotenuseXYZ(this.coffs[6], this.coffs[7], this.coffs[8]);
+    }
     /** Return the dot product of column X with column Y */
     columnXDotColumnY() {
         return this.coffs[0] * this.coffs[1]
             + 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
+     * @param columnIndex index of column. Must be 0,1,2.
      * @param x x component of vector
      * @param y y component of vector
      * @param z z component of vector
@@ -1054,285 +1326,58 @@ export class Matrix3d {
         return this.coffs[columnIndex] * x + this.coffs[columnIndex + 3] * y + this.coffs[columnIndex + 6] * z;
     }
     /** Return (a copy of) the X row */
-    rowX(result) { return Vector3d.create(this.coffs[0], this.coffs[1], this.coffs[2], result); }
+    rowX(result) {
+        return Vector3d.create(this.coffs[0], this.coffs[1], this.coffs[2], result);
+    }
     /** Return (a copy of) the Y row */
-    rowY(result) { return Vector3d.create(this.coffs[3], this.coffs[4], this.coffs[5], result); }
+    rowY(result) {
+        return Vector3d.create(this.coffs[3], this.coffs[4], this.coffs[5], result);
+    }
     /** Return (a copy of) the Z row */
-    rowZ(result) { return Vector3d.create(this.coffs[6], this.coffs[7], this.coffs[8], result); }
+    rowZ(result) {
+        return Vector3d.create(this.coffs[6], this.coffs[7], this.coffs[8], result);
+    }
     /** Return the dot product of the vector parameter with the X column. */
-    dotColumnX(vector) { return vector.x * this.coffs[0] + vector.y * this.coffs[3] + vector.z * this.coffs[6]; }
-    /** Return the dot product of the vector parameter with the Y column. */
-    dotColumnY(vector) { return vector.x * this.coffs[1] + vector.y * this.coffs[4] + vector.z * this.coffs[7]; }
-    /** Return the dot product of the vector parameter with the Z column. */
-    dotColumnZ(vector) { return vector.x * this.coffs[2] + vector.y * this.coffs[5] + vector.z * this.coffs[8]; }
-    /** Return the dot product of the vector parameter with the X row. */
-    dotRowX(vector) { return vector.x * this.coffs[0] + vector.y * this.coffs[1] + vector.z * this.coffs[2]; }
-    /** Return the dot product of the vector parameter with the Y row. */
-    dotRowY(vector) { return vector.x * this.coffs[3] + vector.y * this.coffs[4] + vector.z * this.coffs[5]; }
-    /** Return the dot product of the vector parameter with the Z row. */
-    dotRowZ(vector) { return vector.x * this.coffs[6] + vector.y * this.coffs[7] + vector.z * this.coffs[8]; }
-    // cSpell:words XXYZ YXYZ ZXYZ XYZAs Eigen
-    /** Return the dot product of the x,y,z with the X row. */
-    dotRowXXYZ(x, y, z) { return x * this.coffs[0] + y * this.coffs[1] + z * this.coffs[2]; }
-    /** Return the dot product of the x,y,z with the Y row. */
-    dotRowYXYZ(x, y, z) { return x * this.coffs[3] + y * this.coffs[4] + z * this.coffs[5]; }
-    /** Return the dot product of the x,y,z with the Z row. */
-    dotRowZXYZ(x, y, z) { return x * this.coffs[6] + y * this.coffs[7] + z * this.coffs[8]; }
-    /** Return the (vector) cross product of the Z column with the vector parameter. */
-    columnZCrossVector(vector, result) {
-        return Geometry.crossProductXYZXYZ(this.coffs[2], this.coffs[5], this.coffs[8], vector.x, vector.y, vector.z, result);
+    dotColumnX(vector) {
+        return vector.x * this.coffs[0] + vector.y * this.coffs[3] + vector.z * this.coffs[6];
     }
-    /*
-     * Replace current rows Ui Uj with (c*Ui - s*Uj) and (c*Uj + s*Ui).
-     * @param i first row index.  must be 0,1,2 (unchecked)
-     * @param j second row index. must be 0,1,2 (unchecked)
-     * @param c fist coefficient
-     * @param s second coefficient
-     */
-    applyGivensRowOp(i, j, c, s) {
-        let ii = 3 * i;
-        let jj = 3 * j;
-        const limit = ii + 3;
-        for (; ii < limit; ii++, jj++) {
-            const a = this.coffs[ii];
-            const b = this.coffs[jj];
-            this.coffs[ii] = a * c + b * s;
-            this.coffs[jj] = -a * s + b * c;
-        }
+    /** Return the dot product of the vector parameter with the Y column. */
+    dotColumnY(vector) {
+        return vector.x * this.coffs[1] + vector.y * this.coffs[4] + vector.z * this.coffs[7];
     }
-    /**
-     * create a rigid coordinate frame column z parallel to (_x_,_y_,_z_) and column x in the xy plane.
-     * * column z points from origin to x,y,z
-     * * column x is perpendicular and in the xy plane
-     * * column y is perpendicular to both.  It is the "up" vector on the view plane.
-     * * Multiplying a world vector times the transpose of this matrix transforms into the view xy
-     * * Multiplying the matrix times the an in-view vector transforms the vector to world.
-     * @param x eye x coordinate
-     * @param y eye y coordinate
-     * @param z eye z coordinate
-     * @param result
-     */
-    static createRigidViewAxesZTowardsEye(x, y, z, result) {
-        result = Matrix3d.createIdentity(result);
-        const rxy = Geometry.hypotenuseXY(x, y);
-        if (Geometry.isSmallMetricDistance(rxy)) {
-            // special case for top or bottom view.
-            if (z < 0.0)
-                result.scaleColumnsInPlace(1.0, -1, -1.0);
-        }
-        else {
-            //      const d = Geometry.hypotenuseSquaredXYZ(x, y, z);
-            const c = x / rxy;
-            const s = y / rxy;
-            result.setRowValues(-s, 0, c, c, 0, s, 0, 1, 0);
-            if (z !== 0.0) {
-                const r = Geometry.hypotenuseXYZ(x, y, z);
-                const s1 = z / r;
-                const c1 = rxy / r;
-                result.applyGivensColumnOp(1, 2, c1, -s1);
-            }
-        }
-        return result;
+    /** Return the dot product of the vector parameter with the Z column. */
+    dotColumnZ(vector) {
+        return vector.x * this.coffs[2] + vector.y * this.coffs[5] + vector.z * this.coffs[8];
     }
-    /** Rotate so columns i and j become perpendicular */
-    applyJacobiColumnRotation(i, j, matrixU) {
-        const uDotU = this.coffs[i] * this.coffs[i] + this.coffs[i + 3] * this.coffs[i + 3] + this.coffs[i + 6] * this.coffs[i + 6];
-        const vDotV = this.coffs[j] * this.coffs[j] + this.coffs[j + 3] * this.coffs[j + 3] + this.coffs[j + 6] * this.coffs[j + 6];
-        const uDotV = this.coffs[i] * this.coffs[j] + this.coffs[i + 3] * this.coffs[j + 3] + this.coffs[i + 6] * this.coffs[j + 6];
-        // const c2 = uDotU - vDotV;
-        // const s2 = 2.0 * uDotV;
-        const jacobi = Angle.trigValuesToHalfAngleTrigValues(uDotU - vDotV, 2.0 * uDotV);
-        // const h = Math.hypot(c2, s2);
-        // console.log(" c2 s2", c2 / h, s2 / h);
-        // console.log(" C S ", Math.cos(2 * jacobi.radians), Math.sin(2 * jacobi.radians));
-        // console.log("i j uDotV", i, j, uDotV);
-        if (Math.abs(jacobi.s) < 2.0e-15)
-            return 0.0;
-        this.applyGivensColumnOp(i, j, jacobi.c, jacobi.s);
-        matrixU.applyGivensRowOp(i, j, jacobi.c, jacobi.s);
-        // const BTB = this.multiplyMatrixTransposeMatrix(this);
-        // console.log("BTB", BTB.at(0, 0), BTB.at(1, 1), BTB.at(2, 2), "       off", BTB.at(0, 1), BTB.at(0, 2), BTB.at(1, 2), "  at(i,j)", BTB.at(i, j));
-        return Math.abs(uDotV);
+    /** Return the dot product of the vector parameter with the X row. */
+    dotRowX(vector) {
+        return vector.x * this.coffs[0] + vector.y * this.coffs[1] + vector.z * this.coffs[2];
     }
-    /**
-     * Factor this as a product C * U where C has mutually perpendicular columns and
-     * U is orthogonal.
-     * @param matrixC (allocate by caller, computed here)
-     * @param matrixU (allocate by caller, computed here)
-     */
-    factorPerpendicularColumns(matrixC, matrixU) {
-        matrixC.setFrom(this);
-        matrixU.setIdentity();
-        const ss = this.sumSquares();
-        const tolerance = 1.0e-12 * ss;
-        for (let iteration = 0; iteration < 7; iteration++) {
-            const sum = matrixC.applyJacobiColumnRotation(0, 1, matrixU)
-                + matrixC.applyJacobiColumnRotation(0, 2, matrixU)
-                + matrixC.applyJacobiColumnRotation(1, 2, matrixU);
-            // console.log ("   sum", sum);
-            if (sum < tolerance) {
-                // console.log("jacobi iterations", iteration);
-                return true;
-            }
-        }
-        return false;
+    /** Return the dot product of the vector parameter with the Y row. */
+    dotRowY(vector) {
+        return vector.x * this.coffs[3] + vector.y * this.coffs[4] + vector.z * this.coffs[5];
     }
-    /**
-     * Factor this matrix M as a product M = V * D * U where V and U are orthogonal, and D is diagonal (scale matrix).
-     * @param matrixV left orthogonal factor (allocate by caller, computed here)
-     * @param scale diagonal entries of D (allocate by caller, computed here)
-     * @param matrixU right orthogonal factor (allocate by caller, computed here)
-     */
-    factorOrthogonalScaleOrthogonal(matrixV, scale, matrixU) {
-        const matrixVD = Matrix3d.createZero();
-        if (!this.factorPerpendicularColumns(matrixVD, matrixU))
-            return false;
-        const column = [];
-        column.push(matrixVD.getColumn(0));
-        column.push(matrixVD.getColumn(1));
-        column.push(matrixVD.getColumn(2));
-        scale.set(column[0].magnitude(), column[1].magnitude(), column[2].magnitude());
-        const det = matrixVD.determinant();
-        if (det < 0)
-            scale.z = -scale.z;
-        const almostZero = 1.0e-15;
-        const scaleXIsZero = Math.abs(scale.x) < almostZero;
-        const scaleYIsZero = Math.abs(scale.y) < almostZero;
-        const scaleZIsZero = Math.abs(scale.z) < almostZero;
-        // ASSUME: any zero-magnitude column(s) of matrixVD are last
-        if (!scaleXIsZero && !scaleYIsZero && !scaleZIsZero) { // full rank
-            matrixV = matrixVD.scaleColumns(1 / scale.x, 1 / scale.y, 1 / scale.z, matrixV);
-        }
-        else if (!scaleXIsZero && !scaleYIsZero) { // rank 2
-            column[0].scaleInPlace(1 / scale.x);
-            column[1].scaleInPlace(1 / scale.y);
-            column[2] = column[0].unitCrossProduct(column[1], column[2]);
-            matrixV.setColumns(column[0], column[1], column[2]);
-        }
-        else if (!scaleXIsZero) { // rank 1
-            matrixV = Matrix3d.createRigidHeadsUp(column[0], AxisOrder.XYZ, matrixV); // preserve column0
-        }
-        else { // rank 0
-            matrixV.setIdentity();
-        }
-        return true;
+    /** Return the dot product of the vector parameter with the Z row. */
+    dotRowZ(vector) {
+        return vector.x * this.coffs[6] + vector.y * this.coffs[7] + vector.z * this.coffs[8];
     }
-    /** Apply a jacobi step to lambda which evolves towards diagonal. */
-    applySymmetricJacobi(i, j, lambda) {
-        const uDotU = lambda.at(i, i);
-        const vDotV = lambda.at(j, j);
-        const uDotV = lambda.at(i, j);
-        if (Math.abs(uDotV) < 1.0e-15 * (uDotU + vDotV))
-            return 0.0;
-        // const c2 = uDotU - vDotV;
-        // const s2 = 2.0 * uDotV;
-        const jacobi = Angle.trigValuesToHalfAngleTrigValues(uDotU - vDotV, 2.0 * uDotV);
-        // const h = Math.hypot(c2, s2);
-        // console.log(" c2 s2", c2 / h, s2 / h);
-        // console.log(" C S ", Math.cos(2 * jacobi.radians), Math.sin(2 * jacobi.radians));
-        // console.log("i j uDotV", i, j, uDotV);
-        if (Math.abs(jacobi.s) < 2.0e-15)
-            return 0.0;
-        // Factored form is this *lambda * thisTranspose
-        // Let Q be the rotation matrix.  Q*QT is inserted, viz
-        //          this*Q * QT * lambda * Q*thisTranspose
-        this.applyGivensColumnOp(i, j, jacobi.c, jacobi.s);
-        lambda.applyGivensRowOp(i, j, jacobi.c, jacobi.s);
-        lambda.applyGivensColumnOp(i, j, jacobi.c, jacobi.s);
-        // const BTB = this.multiplyMatrixTransposeMatrix(this);
-        // console.log("BTB", BTB.at(0, 0), BTB.at(1, 1), BTB.at(2, 2), "       off", BTB.at(0, 1), BTB.at(0, 2), BTB.at(1, 2), "  at(i,j)", BTB.at(i, j));
-        return Math.abs(uDotV);
+    /** Return the dot product of the x,y,z with the X row. */
+    dotRowXXYZ(x, y, z) {
+        return x * this.coffs[0] + y * this.coffs[1] + z * this.coffs[2];
     }
-    /**
-     * Factor this (symmetrized) as a product U * lambda * UT where U is orthogonal, lambda is diagonal.
-     * The upper triangle is mirrored to lower triangle to enforce symmetry.
-     * @param matrixC (allocate by caller, computed here)
-     * @param factor  (allocate by caller, computed here)
-     */
-    symmetricEigenvalues(leftEigenvectors, lambda) {
-        const matrix = this.clone();
-        leftEigenvectors.setIdentity();
-        matrix.coffs[3] = matrix.coffs[1];
-        matrix.coffs[6] = matrix.coffs[2];
-        matrix.coffs[7] = matrix.coffs[5];
-        const ss = this.sumSquares();
-        const tolerance = 1.0e-12 * ss;
-        for (let iteration = 0; iteration < 7; iteration++) {
-            const sum = leftEigenvectors.applySymmetricJacobi(0, 1, matrix)
-                + leftEigenvectors.applySymmetricJacobi(0, 2, matrix)
-                + leftEigenvectors.applySymmetricJacobi(1, 2, matrix);
-            // console.log("symmetric sum", sum);
-            // console.log ("   sum", sum);
-            if (sum < tolerance) {
-                // console.log("symmetric iterations", iteration);
-                lambda.set(matrix.at(0, 0), matrix.at(1, 1), matrix.at(2, 2));
-                return true;
-            }
-        }
-        return false;
+    /** Return the dot product of the x,y,z with the Y row. */
+    dotRowYXYZ(x, y, z) {
+        return x * this.coffs[3] + y * this.coffs[4] + z * this.coffs[5];
     }
-    /** Apply (in place a jacobi update that zeros out this.at(i,j).
-     *
-     */
-    applyFastSymmetricJacobiUpdate(i, // row index of zeroed member
-    j, // column index of zeroed member
-    k, // other row/column index (different from i and j)
-    leftEigenVectors) {
-        const indexII = 4 * i;
-        const indexJJ = 4 * j;
-        const indexIJ = 3 * i + j;
-        const indexIK = 3 * i + k;
-        const indexJK = 3 * j + k;
-        const dotUU = this.coffs[indexII];
-        const dotVV = this.coffs[indexJJ];
-        const dotUV = this.coffs[indexIJ];
-        const jacobi = Angle.trigValuesToHalfAngleTrigValues(dotUU - dotVV, 2.0 * dotUV);
-        if (Math.abs(dotUV) < 1.0e-15 * (dotUU + dotVV))
-            return 0.0;
-        const c = jacobi.c;
-        const s = jacobi.s;
-        const cc = c * c;
-        const ss = s * s;
-        const sc2 = 2.0 * c * s;
-        this.coffs[indexII] = cc * dotUU + sc2 * dotUV + ss * dotVV;
-        this.coffs[indexJJ] = ss * dotUU - sc2 * dotUV + cc * dotVV;
-        this.coffs[indexIJ] = 0.0;
-        const a = this.coffs[indexIK];
-        const b = this.coffs[indexJK];
-        this.coffs[indexIK] = a * c + b * s;
-        this.coffs[indexJK] = -s * a + c * b;
-        this.coffs[3 * j + i] = 0.0;
-        this.coffs[3 * k + i] = this.coffs[indexIK];
-        this.coffs[3 * k + j] = this.coffs[indexJK];
-        leftEigenVectors.applyGivensColumnOp(i, j, c, s);
-        return Math.abs(dotUV);
+    /** Return the dot product of the x,y,z with the Z row. */
+    dotRowZXYZ(x, y, z) {
+        return x * this.coffs[6] + y * this.coffs[7] + z * this.coffs[8];
     }
-    /**
-     * Factor this (symmetrized) as a product U * lambda * UT where U is orthogonal, lambda is diagonal.
-     * The upper triangle is mirrored to lower triangle to enforce symmetry.
-     * @param matrixC (allocate by caller, computed here)
-     * @param factor  (allocate by caller, computed here)
-     */
-    fastSymmetricEigenvalues(leftEigenvectors, lambda) {
-        const matrix = this.clone();
-        leftEigenvectors.setIdentity();
-        const ss = this.sumSquares();
-        const tolerance = 1.0e-12 * ss;
-        for (let iteration = 0; iteration < 7; iteration++) {
-            const sum = matrix.applyFastSymmetricJacobiUpdate(0, 1, 2, leftEigenvectors)
-                + matrix.applyFastSymmetricJacobiUpdate(0, 2, 1, leftEigenvectors)
-                + matrix.applyFastSymmetricJacobiUpdate(1, 2, 0, leftEigenvectors);
-            // console.log("symmetric sum", sum);
-            // console.log ("   sum", sum);
-            if (sum < tolerance) {
-                // console.log("symmetric iterations", iteration);
-                lambda.set(matrix.at(0, 0), matrix.at(1, 1), matrix.at(2, 2));
-                return true;
-            }
-        }
-        return false;
+    /** Return the cross product of the Z column with the vector parameter. */
+    columnZCrossVector(vector, result) {
+        return Geometry.crossProductXYZXYZ(this.coffs[2], this.coffs[5], this.coffs[8], vector.x, vector.y, vector.z, result);
     }
-    /** Install data from xyz parts of Point4d  (w part of Point4d ignored) */
+    /** Set data from xyz parts of Point4d  (w part of Point4d ignored) */
     setColumnsPoint4dXYZ(vectorU, vectorV, vectorW) {
         this.inverseState = InverseMatrixState.unknown;
         this.setRowValues(vectorU.x, vectorV.x, vectorW.x, vectorU.y, vectorV.y, vectorW.y, vectorU.z, vectorV.z, vectorW.z);
@@ -1356,16 +1401,22 @@ export class Matrix3d {
             this.coffs[index + 6] = 0.0;
         }
     }
-    /** Set all columns of the matrix. Any undefined vector is zeros. */
+    /**
+     * Set all columns of the matrix. Any undefined vector is zeros.
+     * @param vectorX values for column 0
+     * @param vectorY values for column 1
+     * @param vectorZ optional values for column 2 (it's optional in case column 2 is 000, which is a
+     * projection onto the xy-plane)
+     */
     setColumns(vectorX, vectorY, vectorZ) {
         this.setColumn(0, vectorX);
         this.setColumn(1, vectorY);
         this.setColumn(2, vectorZ);
     }
     /**
-     * set entries in one row of the matrix.
-     * @param rowIndex row index. this is interpreted cyclically.
-     * @param value x,yz, values for row.  If undefined, zeros are installed.
+     * Set entries in one row of the matrix.
+     * @param rowIndex row index. This is interpreted cyclically (using Geometry.cyclic3dAxis).
+     * @param value x,y,z values for row.
      */
     setRow(rowIndex, value) {
         const index = 3 * Geometry.cyclic3dAxis(rowIndex);
@@ -1374,21 +1425,26 @@ export class Matrix3d {
         this.coffs[index + 2] = value.z;
         this.inverseState = InverseMatrixState.unknown;
     }
-    /** Return a (copy of) a column of the matrix.
-     * @param i column index.  This is corrected to 012 by Geometry.cyclic3dAxis.
+    /**
+     * Return (a copy of) a column of the matrix.
+     * @param i column index. This is interpreted cyclically (using Geometry.cyclic3dAxis).
+     * @param result optional preallocated result.
      */
     getColumn(columnIndex, result) {
         const index = Geometry.cyclic3dAxis(columnIndex);
         return Vector3d.create(this.coffs[index], this.coffs[index + 3], this.coffs[index + 6], result);
     }
-    /** Return a (copy of) a row of the matrix.
-     * @param i row index.  This is corrected to 012 by Geometry.cyclic3dAxis.
+    /**
+     * Return a (copy of) a row of the matrix.
+     * @param i row index. This is interpreted cyclically (using Geometry.cyclic3dAxis).
+     * @param result optional preallocated result.
      */
     getRow(columnIndex, result) {
         const index = 3 * Geometry.cyclic3dAxis(columnIndex);
         return Vector3d.create(this.coffs[index], this.coffs[index + 1], this.coffs[index + 2], result);
     }
-    /** Create a matrix from row vectors.
+    /**
+     * Create a matrix from row vectors.
      * ```
      * equation
      * \begin{bmatrix}U_x & U_y & U_z \\ V_x & V_y & V_z \\ W_x & W_y & W_z \end{bmatrix}
@@ -1397,14 +1453,20 @@ export class Matrix3d {
     static createRows(vectorU, vectorV, vectorW, result) {
         return Matrix3d.createRowValues(vectorU.x, vectorU.y, vectorU.z, vectorV.x, vectorV.y, vectorV.z, vectorW.x, vectorW.y, vectorW.z, result);
     }
-    /** Create a matrix that scales along a specified direction.
-     * * The scale factor can be negative.
-     *  * A scale of -1.0 (negative one) is a mirror across the plane perpendicular to the vector.
+    /**
+     * Create a matrix that scales along a specified `direction`. This means if you multiply the returned matrix
+     * by a `vector`, you get `directional scale` of that `vector`. Suppose `plane` is the plane perpendicular
+     * to the `direction`. When scale = 0, `directional scale` is projection of the `vector` to the `plane`.
+     * When scale = 1, `directional scale` is the `vector` itself. When scale = -1, `directional scale` is
+     * mirror of the `vector` across the `plane`. In general, When scale != 0, the result is computed by first
+     * projecting the `vector` to the `plane`, then translating that projection along the `direction` (if scale > 0)
+     * or in opposite direction (if scale < 0).
      * ```
      * equation
-     * \text{The matrix is } I - (s-1) U U^T
-     * \\ \text{with }U\text{ being the unit vector in the direction of the input vector.}
+     * \text{The matrix is } I + (s-1) D D^T
+     * \\ \text{with }D\text{ being the normalized direction vector and }s\text{ being the scale.}
      * ```
+     * * Visualization can be found at itwinjs.org/sandbox/SaeedTorabi/DirectionalScale
      */
     static createDirectionalScale(direction, scale, result) {
         const unit = direction.normalize();
@@ -1412,19 +1474,13 @@ export class Matrix3d {
             const x = unit.x;
             const y = unit.y;
             const z = unit.z;
-            const a = (scale - 1);
+            const a = scale - 1;
             return Matrix3d.createRowValues(1 + a * x * x, a * x * y, a * x * z, a * y * x, 1 + a * y * y, a * y * z, a * z * x, a * z * y, 1 + a * z * z, result);
         }
         return Matrix3d.createUniformScale(scale);
     }
-    /* Create a matrix with the indicated column in the (normalized) direction, and the other two columns perpendicular. All columns are normalized.
-     * * The direction vector is normalized and appears in column axisIndex
-     * * If the direction vector is not close to Z, the "next" column ((axisIndex + 1) mod 3) will be in the XY plane in the direction of (direction cross Z)
-     * * If the direction vector is close to Z, the "next" column ((axisIndex + 1) mode 3) will be in the direction of (direction cross Y)
-    */
-    // static create1Vector(direction: Vector3d, axisIndex: number): Matrix3d;
-    // static createFromXYVectors(vectorX: Vector3d, vectorY: Vector3d, axisIndex: number): Matrix3d;
-    /** Multiply the matrix * vector, treating the vector is a column vector on the right.
+    /**
+     * Multiply `matrix * vector`, treating the vector is a column vector on the right.
      * ```
      * equation
      * \matrixXY{A}\columnSubXYZ{U}
@@ -1435,36 +1491,38 @@ export class Matrix3d {
         const x = vectorU.x;
         const y = vectorU.y;
         const z = vectorU.z;
-        return Vector3d.create((this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z), (this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z), (this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z), result);
+        return Vector3d.create(this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z, this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z, this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z, result);
     }
-    /** Multiply matrix * vector for each array member, i.e. the vector is a column vector on the right.
-     * @return the vector result
+    /**
+     * Multiply `matrix * vector` in place for vector in the array, i.e. treating the vector is a column
+     * vector on the right.
+     * * Each `vector` is updated to be `matrix * vector`
      */
     multiplyVectorArrayInPlace(data) {
         for (const v of data)
-            v.set((this.coffs[0] * v.x + this.coffs[1] * v.y + this.coffs[2] * v.z), (this.coffs[3] * v.x + this.coffs[4] * v.y + this.coffs[5] * v.z), (this.coffs[6] * v.x + this.coffs[7] * v.y + this.coffs[8] * v.z));
+            v.set(this.coffs[0] * v.x + this.coffs[1] * v.y + this.coffs[2] * v.z, this.coffs[3] * v.x + this.coffs[4] * v.y + this.coffs[5] * v.z, this.coffs[6] * v.x + this.coffs[7] * v.y + this.coffs[8] * v.z);
     }
-    /** compute `origin - matrix * vector` */
+    /** Compute `origin - matrix * vector` */
     static xyzMinusMatrixTimesXYZ(origin, matrix, vector, result) {
         const x = vector.x;
         const y = vector.y;
         const z = vector.z;
         return Point3d.create(origin.x - (matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z), origin.y - (matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z), origin.z - (matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z), result);
     }
-    /** compute  `origin + matrix * vector`  using only the xy parts of the inputs. */
+    /** Compute `origin + matrix * vector`  using only the xy parts of the inputs. */
     static xyPlusMatrixTimesXY(origin, matrix, vector, result) {
         const x = vector.x;
         const y = vector.y;
         return Point2d.create(origin.x + matrix.coffs[0] * x + matrix.coffs[1] * y, origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y, result);
     }
-    /** compute  `origin + matrix * vector`  using all xyz parts of the inputs. */
+    /** Compute `origin + matrix * vector`  using all xyz parts of the inputs. */
     static xyzPlusMatrixTimesXYZ(origin, matrix, vector, result) {
         const x = vector.x;
         const y = vector.y;
         const z = vector.z;
         return Point3d.create(origin.x + matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z, origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z, origin.z + matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z, result);
     }
-    /** compute  `origin + matrix * vector`  using all xyz parts of the inputs. */
+    /** Updates vector to be `origin + matrix * vector` using all xyz parts of the inputs. */
     static xyzPlusMatrixTimesXYZInPlace(origin, matrix, vector) {
         const x = vector.x;
         const y = vector.y;
@@ -1473,65 +1531,76 @@ export class Matrix3d {
         vector.y = origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z;
         vector.z = origin.z + matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z;
     }
-    /** compute `origin + matrix * vector` where the final vector is given as direct x,y,z coordinates */
+    /** Compute `origin + matrix * vector` where the final vector is given as direct x,y,z coordinates */
     static xyzPlusMatrixTimesCoordinates(origin, matrix, x, y, z, result) {
         return Point3d.create(origin.x + matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z, origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z, origin.z + matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z, result);
     }
     /**
      * Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row.
-     * Multiply times point with coordinates `[x,y,z,w]`
+     * Multiply the 4x4 matrix by `[x,y,z,w]`
+     * ```
+     * equation
+     * \begin{bmatrix}M_0 & M_1 & M_2 & Ox \\ M_3 & M_4 & M_5 & Oy \\ M_6 & M_7 & M_8 & Oz \\ 0 & 0 & 0 & 1\end{bmatrix} * \begin{bmatrix}x \\ y \\ z \\ w\end{bmatrix}
+     * ```
      * @param origin translation part (xyz in column 3)
      * @param matrix matrix part (leading 3x3)
      * @param x x part of multiplied point
      * @param y y part of multiplied point
      * @param z z part of multiplied point
      * @param w w part of multiplied point
-     * @param result optional result.
+     * @param result optional preallocated result.
      */
     static xyzPlusMatrixTimesWeightedCoordinates(origin, matrix, x, y, z, w, result) {
-        return Point4d.create(w * origin.x + matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z, w * origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z, w * origin.z + matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z, w, result);
+        return Point4d.create(matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z + origin.x * w, matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z + origin.y * w, matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z + origin.z * w, w, result);
     }
     /**
      * Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row.
-     * Multiply times point with coordinates `[x,y,z,w]`
+     * Multiply the 4x4 matrix by `[x,y,z,w]`
+     * ```
+     * equation
+     * \begin{bmatrix}M_0 & M_1 & M_2 & Ox \\ M_3 & M_4 & M_5 & Oy \\ M_6 & M_7 & M_8 & Oz \\ 0 & 0 & 0 & 1\end{bmatrix} * \begin{bmatrix}x \\ y \\ z \\ w\end{bmatrix}
+     * ```
      * @param origin translation part (xyz in column 3)
      * @param matrix matrix part (leading 3x3)
      * @param x x part of multiplied point
      * @param y y part of multiplied point
      * @param z z part of multiplied point
      * @param w w part of multiplied point
-     * @param result optional result.
+     * @param result optional preallocated result.
      */
     static xyzPlusMatrixTimesWeightedCoordinatesToFloat64Array(origin, matrix, x, y, z, w, result) {
         if (!result)
             result = new Float64Array(4);
-        result[0] = w * origin.x + matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z;
-        result[1] = w * origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z;
-        result[2] = w * origin.z + matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z;
+        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;
+        result[2] = matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z + origin.z * w;
         result[3] = w;
         return result;
     }
     /**
-     * Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row.
-     * Multiply times point with coordinates `[x,y,z,w]`
+     * Treat the 3x3 matrix and origin as a 3x4 matrix.
+     * * Multiply the 3x4 matrix by `[x,y,z,1]`
+     * ```
+     * equation
+     * \begin{bmatrix}M_0 & M_1 & M_2 & Ox \\ M_3 & M_4 & M_5 & Oy \\ M_6 & M_7 & M_8 & Oz\end{bmatrix} * \begin{bmatrix}x \\ y \\ z \\ 1\end{bmatrix}
+     * ```
      * @param origin translation part (xyz in column 3)
      * @param matrix matrix part (leading 3x3)
      * @param x x part of multiplied point
      * @param y y part of multiplied point
      * @param z z part of multiplied point
-     * @param w w part of multiplied point
-     * @param result optional result.
+     * @param result optional preallocated result.
      */
     static xyzPlusMatrixTimesCoordinatesToFloat64Array(origin, matrix, x, y, z, result) {
         if (!result)
             result = new Float64Array(3);
-        result[0] = origin.x + matrix.coffs[0] * x + matrix.coffs[1] * y + matrix.coffs[2] * z;
-        result[1] = origin.y + matrix.coffs[3] * x + matrix.coffs[4] * y + matrix.coffs[5] * z;
-        result[2] = origin.z + matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z;
+        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;
+        result[2] = matrix.coffs[6] * x + matrix.coffs[7] * y + matrix.coffs[8] * z + origin.z;
         return result;
     }
     /**
-     * Multiply transpose of this matrix times a vector.
+     * Multiply the transpose matrix times a vector.
      * * This produces the same x,y,z as treating the vector as a row on the left of the (un-transposed) matrix.
      * ```
      * equation
@@ -1540,99 +1609,112 @@ 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
+     * @param result the vector result (optional)
      */
     multiplyTransposeVector(vector, result) {
         result = result ? result : new Vector3d();
         const x = vector.x;
         const y = vector.y;
         const z = vector.z;
-        result.x = (this.coffs[0] * x + this.coffs[3] * y + this.coffs[6] * z);
-        result.y = (this.coffs[1] * x + this.coffs[4] * y + this.coffs[7] * z);
-        result.z = (this.coffs[2] * x + this.coffs[5] * y + this.coffs[8] * z);
+        result.x = this.coffs[0] * x + this.coffs[3] * y + this.coffs[6] * z;
+        result.y = this.coffs[1] * x + this.coffs[4] * y + this.coffs[7] * z;
+        result.z = this.coffs[2] * x + this.coffs[5] * y + this.coffs[8] * z;
         return result;
     }
-    /** Multiply the matrix * (x,y,z), i.e. the vector (x,y,z) is a column vector on the right.
-     * @return the vector result
+    /**
+     * Multiply the matrix * [x,y,z], i.e. the vector [x,y,z] is a column vector on the right.
+     * @param result the vector result (optional)
      */
     multiplyXYZ(x, y, z, result) {
         result = result ? result : new Vector3d();
-        result.x = (this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z);
-        result.y = (this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z);
-        result.z = (this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z);
+        result.x = this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z;
+        result.y = this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z;
+        result.z = this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z;
         return result;
     }
-    /** Multiply the matrix * xyz, place result in (required) return value.
-     *   @param xyz right side
-     *   @param result result.
+    /**
+     * Multiply the matrix * xyz, place result in (required) return value.
+     * @param xyz right side
+     * @param result the result.
      */
     multiplyXYZtoXYZ(xyz, result) {
         const x = xyz.x;
         const y = xyz.y;
         const z = xyz.z;
-        result.x = (this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z);
-        result.y = (this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z);
-        result.z = (this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z);
+        result.x = this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z;
+        result.y = this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z;
+        result.z = this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z;
         return result;
     }
-    /** Multiply the matrix * (x,y,0), i.e. the vector (x,y,z) is a column vector on the right.
-     *   @return the vector result
+    /**
+     * Multiply the matrix * [x,y,0], i.e. the vector [x,y,0] is a column vector on the right.
+     * @param result the vector result (optional)
      */
     multiplyXY(x, y, result) {
         result = result ? result : new Vector3d();
-        result.x = (this.coffs[0] * x + this.coffs[1] * y);
-        result.y = (this.coffs[3] * x + this.coffs[4] * y);
-        result.z = (this.coffs[6] * x + this.coffs[7] * y);
+        result.x = this.coffs[0] * x + this.coffs[1] * y;
+        result.y = this.coffs[3] * x + this.coffs[4] * y;
+        result.z = this.coffs[6] * x + this.coffs[7] * y;
         return result;
     }
-    /** compute `origin + this*[x,y,0]`  */
+    /**
+     * Compute origin + the matrix * [x,y,0].
+     * @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);
     }
-    /** Multiply matrix * (x, y, z) using any 3d object given containing those members */
+    /**
+     * 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.
+     */
     multiplyVectorInPlace(xyzData) {
         const x = xyzData.x;
         const y = xyzData.y;
         const z = xyzData.z;
-        const coffs = this.coffs;
-        xyzData.x = (coffs[0] * x + coffs[1] * y + coffs[2] * z);
-        xyzData.y = (coffs[3] * x + coffs[4] * y + coffs[5] * z);
-        xyzData.z = (coffs[6] * x + coffs[7] * y + coffs[8] * z);
+        xyzData.x = this.coffs[0] * x + this.coffs[1] * y + this.coffs[2] * z;
+        xyzData.y = this.coffs[3] * x + this.coffs[4] * y + this.coffs[5] * z;
+        xyzData.z = this.coffs[6] * x + this.coffs[7] * y + this.coffs[8] * z;
     }
-    /** Multiply the transpose matrix times column using any 3d object with x,y,z members.
-     * This is equivalent to `multiplyTransposeVector` but always returns the result directly in the input.
+    /**
+     * 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 vectorU the vector data
      */
     multiplyTransposeVectorInPlace(vectorU) {
         const x = vectorU.x;
         const y = vectorU.y;
         const z = vectorU.z;
-        const coffs = this.coffs;
-        vectorU.x = (coffs[0] * x + coffs[3] * y + coffs[6] * z);
-        vectorU.y = (coffs[1] * x + coffs[4] * y + coffs[7] * z);
-        vectorU.z = (coffs[2] * x + coffs[5] * y + coffs[8] * z);
+        vectorU.x = this.coffs[0] * x + this.coffs[3] * y + this.coffs[6] * z;
+        vectorU.y = this.coffs[1] * x + this.coffs[4] * y + this.coffs[7] * z;
+        vectorU.z = this.coffs[2] * x + this.coffs[5] * y + this.coffs[8] * z;
     }
-    /** Multiply the transpose matrix times column using individual numeric inputs.
-     * * This is equivalent to multiplying with the vector as a row to the left of the plain matrix.
+    /**
+     * Multiply the transpose matrix times column using individual numeric inputs.
+     * * This produces the same x,y,z as treating the vector as a row on the left of the (un-transposed) matrix.
      * ```
      * equation
      * \begin{matrix}
-     * \text{treating the input as a column } \columnXYZ{x}{y}{z}\text{ compute  }&\columnSubXYZ{V} &= &A^T \columnXYZ{x}{y}{z} \\
-     * \text{or row vector } \rowXYZ{x}{y}{z} \text{ compute }&\rowSubXYZ{V} &= &\rowXYZ{x}{y}{z} A \\
+     * \text{treating the input as a column vector } \columnXYZ{x}{y}{z}\text{ compute  }&\columnSubXYZ{V} &= &A^T \columnXYZ{x}{y}{z} \\
+     * \text{or as a row vector } \rowXYZ{x}{y}{z} \text{ compute }&\rowSubXYZ{V} &= &\rowXYZ{x}{y}{z} A \\
      * \phantom{8888}\text{and return V as a Vector3d} & & &
      * \end{matrix}
      * ````
-     * @return the vector result
+     * @param result the vector result (optional)
      */
     multiplyTransposeXYZ(x, y, z, result) {
         result = result ? result : new Vector3d();
-        result.x = (this.coffs[0] * x + this.coffs[3] * y + this.coffs[6] * z);
-        result.y = (this.coffs[1] * x + this.coffs[4] * y + this.coffs[7] * z);
-        result.z = (this.coffs[2] * x + this.coffs[5] * y + this.coffs[8] * z);
+        result.x = this.coffs[0] * x + this.coffs[3] * y + this.coffs[6] * z;
+        result.y = this.coffs[1] * x + this.coffs[4] * y + this.coffs[7] * z;
+        result.z = this.coffs[2] * x + this.coffs[5] * y + this.coffs[8] * z;
         return result;
     }
-    /** Solve `matrix * result = vector`.
+    /**
+     * Solve `matrix * result = vector` for an unknown `result`.
      * * This is equivalent to multiplication `result = matrixInverse * vector`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel or zero length columns)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      */
     multiplyInverse(vector, result) {
         this.computeCachedInverse(true);
@@ -1640,13 +1722,14 @@ export class Matrix3d {
             const x = vector.x;
             const y = vector.y;
             const z = vector.z;
-            return Vector3d.create((this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z), (this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z), (this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z), result);
+            return Vector3d.create(this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z, this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z, this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z, result);
         }
         return undefined;
     }
-    /** Solve `matrixTranspose * result = vector`.
+    /**
+     * 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 or zero length columns)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      */
     multiplyInverseTranspose(vector, result) {
         this.computeCachedInverse(true);
@@ -1654,87 +1737,91 @@ export class Matrix3d {
             const x = vector.x;
             const y = vector.y;
             const z = vector.z;
-            return Vector3d.create((this.inverseCoffs[0] * x + this.inverseCoffs[3] * y + this.inverseCoffs[6] * z), (this.inverseCoffs[1] * x + this.inverseCoffs[4] * y + this.inverseCoffs[7] * z), (this.inverseCoffs[2] * x + this.inverseCoffs[5] * y + this.inverseCoffs[8] * z), result);
+            return Vector3d.create(this.inverseCoffs[0] * x + this.inverseCoffs[3] * y + this.inverseCoffs[6] * z, this.inverseCoffs[1] * x + this.inverseCoffs[4] * y + this.inverseCoffs[7] * z, this.inverseCoffs[2] * x + this.inverseCoffs[5] * y + this.inverseCoffs[8] * z, result);
         }
         return undefined;
     }
     /**
-     * multiply `matrixInverse * [x,y,z]`.
-     * *  This is equivalent to solving `matrix * result = [x,y,z]`
-     * *  return as a Vector3d, or undefined if the matrix is singular.
+     * 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)
+     * @return result as a Vector3d or undefined (if the matrix is singular).
      */
     multiplyInverseXYZAsVector3d(x, y, z, result) {
         this.computeCachedInverse(true);
         if (this.inverseCoffs) {
-            return Vector3d.create((this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z), (this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z), (this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z), result);
+            return Vector3d.create(this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z, this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z, this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z, result);
         }
         return undefined;
     }
     /**
-     * multiply `matrixInverse * [x,y,z]` and return packaged as `Point4d` with given weight.
-     * *  Equivalent to solving matrix * result = [x,y,z]
-     * *  return as a Point4d with the same weight.
-     * *  Called by Transform with x,y,z adjusted by subtraction ((xw) - w * origin.x, etc) where xw is the pre-weighted space point.
+     * 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)
+     * @return result as a Point4d with the same weight.
      */
     multiplyInverseXYZW(x, y, z, w, result) {
         this.computeCachedInverse(true);
         if (this.inverseCoffs) {
-            return Point4d.create((this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z), (this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z), (this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z), w, result);
+            return Point4d.create(this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z, this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z, this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z, w, result);
         }
         return undefined;
     }
     /**
-     * multiply `matrixInverse * [x,y,z]` and return packaged as `Point3d`.
-     * *  multiply matrixInverse * [x,y,z]
-     * *  Equivalent to solving matrix * result = [x,y,z]
-     * *  return as a Point3d.
+     * 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).
      */
     multiplyInverseXYZAsPoint3d(x, y, z, result) {
         this.computeCachedInverse(true);
         if (this.inverseCoffs) {
-            return Point3d.create((this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z), (this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z), (this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z), result);
+            return Point3d.create(this.inverseCoffs[0] * x + this.inverseCoffs[1] * y + this.inverseCoffs[2] * z, this.inverseCoffs[3] * x + this.inverseCoffs[4] * y + this.inverseCoffs[5] * z, this.inverseCoffs[6] * x + this.inverseCoffs[7] * y + this.inverseCoffs[8] * z, result);
         }
         return undefined;
     }
     /**
-     * * invoke a given matrix-matrix operation (product function) to compute this.inverseCOffs
-     * * set this.inverseCoffs
-     * * if either input cffA or coffB is undefined, set state to `InverseMatrixState.unknown` (but leave the inverseCoffs untouched)
+     * 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
+     * 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.
      */
     finishInverseCoffs(f, coffA, coffB) {
         if (coffA && coffB) {
             this.createInverseCoffsWithZeros();
             this.inverseState = InverseMatrixState.inverseStored;
-            f(coffA, coffB, this.inverseCoffs);
+            f(coffA, coffB, this.inverseCoffs); // call function f (which is provided by user) to compute the inverse.
         }
         else {
             this.inverseState = InverseMatrixState.unknown;
         }
     }
-    /*
-     Notes on inverses of products
-     * 1) M = A * B       MInverse = BInverse * AInverse
-     * 2) M = A * BInverse       MInverse = B * AInverse
-     * 3) M = AInverse * B       MInverse = BInverse * A
-     * 4) M = ATranspose * B       MInverse = BInverse * AInverseTranspose
-     * 5) M = A * BTranspose       MInverse = BInverseTranspose * AInverse
-    */
-    /** Multiply the instance matrix A by the input matrix B.
-     *   @return the matrix product A * B
+    // Notes on inverse of matrix products:
+    //      1) M = A * B           ===>  MInverse = BInverse * AInverse
+    //      2) M = A * BInverse    ===>  MInverse = B * AInverse
+    //      3) M = AInverse * B    ===>  MInverse = BInverse * A
+    //      4) M = A * BTranspose  ===>  MInverse = BInverseTranspose * AInverse
+    //      5) M = ATranspose * B  ===>  MInverse = BInverse * AInverseTranspose
+    /**
+     * Multiply `this` matrix times `other` matrix
+     * @return the matrix result: this*other
      */
     multiplyMatrixMatrix(other, result) {
         result = result ? result : new Matrix3d();
         PackedMatrix3dOps.multiplyMatrixMatrix(this.coffs, other.coffs, result.coffs);
-        if (this.inverseState === InverseMatrixState.inverseStored && other.inverseState === InverseMatrixState.inverseStored)
+        if (this.inverseState === InverseMatrixState.inverseStored
+            && other.inverseState === InverseMatrixState.inverseStored)
             result.finishInverseCoffs(PackedMatrix3dOps.multiplyMatrixMatrix, other.inverseCoffs, this.inverseCoffs);
-        else if (this.inverseState === InverseMatrixState.singular || other.inverseState === InverseMatrixState.singular)
+        else if (this.inverseState === InverseMatrixState.singular
+            || other.inverseState === InverseMatrixState.singular)
             result.inverseState = InverseMatrixState.singular;
         else
             result.inverseState = InverseMatrixState.unknown;
         return result;
     }
-    /** Multiply this matrix times inverse of other
-     *   @return the matrix result
+    /**
+     * Multiply `this` matrix times `inverse of other` matrix
+     * @return the matrix result: this*otherInverse
      */
     multiplyMatrixMatrixInverse(other, result) {
         if (!other.computeCachedInverse(true))
@@ -1748,8 +1835,9 @@ export class Matrix3d {
         PackedMatrix3dOps.copy(Matrix3d._productBuffer, result.coffs);
         return result;
     }
-    /** Multiply this matrix times inverse of other
-     *   @return the matrix result
+    /**
+     * Multiply `inverse of this` matrix times `other` matrix
+     * @return the matrix result: thisInverse*other
      */
     multiplyMatrixInverseMatrix(other, result) {
         if (!this.computeCachedInverse(true))
@@ -1763,30 +1851,32 @@ export class Matrix3d {
         PackedMatrix3dOps.copy(Matrix3d._productBuffer, result.coffs);
         return result;
     }
-    /** Multiply `this` matrix times the transpose of `matrixB`.
+    /**
+     * Multiply `this` matrix times the transpose of `other` matrix
      * ```
      * equation
-     * \text{for instance matrix }A\text{ and other matrix }B\text{ return matrix }C{\text where }\\\matrixXY{C}=\matrixXY{A}\matrixTransposeSubXY{B}
+     * \text{for instance matrix }A\text{ and matrix }B\text{ return matrix }C{\text where }\\\matrixXY{C}=\matrixXY{A}\matrixTransposeSubXY{B}
      * ```
-     * @return the matrix result
+     * @return the matrix result: this*otherTranspose
      */
-    multiplyMatrixMatrixTranspose(matrixB, result) {
+    multiplyMatrixMatrixTranspose(other, result) {
         result = result ? result : new Matrix3d();
-        PackedMatrix3dOps.multiplyMatrixMatrixTranspose(this.coffs, matrixB.coffs, result.coffs);
-        if (this.inverseState === InverseMatrixState.inverseStored && matrixB.inverseState === InverseMatrixState.inverseStored)
-            result.finishInverseCoffs(PackedMatrix3dOps.multiplyMatrixTransposeMatrix, matrixB.inverseCoffs, this.inverseCoffs);
-        else if (this.inverseState === InverseMatrixState.singular || matrixB.inverseState === InverseMatrixState.singular)
+        PackedMatrix3dOps.multiplyMatrixMatrixTranspose(this.coffs, other.coffs, result.coffs);
+        if (this.inverseState === InverseMatrixState.inverseStored && other.inverseState === InverseMatrixState.inverseStored)
+            result.finishInverseCoffs(PackedMatrix3dOps.multiplyMatrixTransposeMatrix, other.inverseCoffs, this.inverseCoffs);
+        else if (this.inverseState === InverseMatrixState.singular || other.inverseState === InverseMatrixState.singular)
             result.inverseState = InverseMatrixState.singular;
         else
             result.inverseState = InverseMatrixState.unknown;
         return result;
     }
-    /** Matrix multiplication `thisTranspose * other`.
+    /**
+     * Multiply the transpose of `this` matrix times `other` matrix
      * ```
      * equation
      * \matrixXY{result}=\matrixXY{\text{this}}\matrixTransposeSubXY{\text{other}}
      * ```
-     *   @return the matrix result
+     * @return the matrix result: thisTranspose*other
      */
     multiplyMatrixTransposeMatrix(other, result) {
         result = result ? result : new Matrix3d();
@@ -1799,30 +1889,31 @@ export class Matrix3d {
             result.inverseState = InverseMatrixState.unknown;
         return result;
     }
-    /** multiply this Matrix3d (considered as a transform with 0 translation) times other Transform.
+    /**
+     * Multiply `this` Matrix3d (considered as a Transform with 0 translation) times `other` Transform.
      * ```
      * equation
      * \begin{matrix}
-     *    \text{This matrix }\bold{A}\text{ promoted to block transform} & \blockTransform{A}{0} \\
-     *    \text{other transform with matrix part }\bold{B}\text{ and translation }\bold{b} & \blockTransform{B}{b}\\
+     * \text{This matrix }\bold{A}\text{ promoted to block transform} & \blockTransform{A}{0} \\
+     * \text{other transform with matrix part }\bold{B}\text{ and translation }\bold{b} & \blockTransform{B}{b}\\
      * \text{product}& \blockTransform{A}{0}\blockTransform{B}{b}=\blockTransform{AB}{Ab}
      * \end{matrix}
      * ```
-     * @param other right hand Matrix3d for multiplication.
-     * @param result optional preallocated result to reuse.
+     * @param other Right hand Matrix3d for multiplication.
+     * @param result the Transform result (optional)
      */
     multiplyMatrixTransform(other, result) {
         if (!result)
             return Transform.createRefs(this.multiplyXYZ(other.origin.x, other.origin.y, other.origin.z), this.multiplyMatrixMatrix(other.matrix));
-        // be sure to do the point multiplication first before aliasing changes the matrix ..
+        // be sure to do the point multiplication first before aliasing changes the matrix
         this.multiplyXYZtoXYZ(other.origin, result.origin);
         this.multiplyMatrixMatrix(other.matrix, result.matrix);
         return result;
     }
     /**
      * Return the transpose of `this` matrix.
-     * If `result` is passed as argument, then the function copies the transpose of `this` into `result`
-     * `this` is not changed unless also passed as the result, i.e., this.transpose(this) transposes `this` in place
+     * * If `result` is passed as argument, then the function copies the transpose of `this` into `result`.
+     * * `this` is not changed unless also passed as the result, i.e., `this.transpose(this)` transposes `this` in place.
      */
     transpose(result) {
         if (!result)
@@ -1844,18 +1935,22 @@ export class Matrix3d {
     transposeInPlace() {
         PackedMatrix3dOps.transposeInPlace(this.coffs);
         if (this.inverseCoffs)
-            PackedMatrix3dOps.transposeInPlace(this.inverseCoffs);
+            PackedMatrix3dOps.transposeInPlace(this.inverseCoffs); // inverse of transpose is equal to transpose of inverse
     }
-    /** return the inverse matrix.
-     * The return is undefined if the matrix is singular (has columns that are coplanar or colinear)
-     * * Note that each Matrix3d object caches its own inverse, and has methods to multiply the inverse times matrices and vectors.
-     * * Hence explicitly constructing this new inverse object is rarely necessary.
+    /**
+     * Return the inverse matrix.
+     * The return is undefined if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * * If `result == this`, then content of inverse of `this` matrix is copied into `this`. Otherwise, inverse
+     * of `this` is stored in `result`.
+     * * **Note:** Each Matrix3d object caches its own inverse (`this.inverseCoffs`) and has methods to multiply
+     * the inverse times matrices and vectors (e.g., `multiplyMatrixInverseMatrix`, `multiplyMatrixMatrixInverse`,
+     * `multiplyInverse`). Hence explicitly constructing this new inverse object is rarely necessary.
      */
     inverse(result) {
         if (!this.computeCachedInverse(true))
             return undefined;
         if (result === this) {
-            // swap the contents (preserve pointers .. caller better know what they are doing)
+            // swap the contents of this.coffs and this.inverseCoffs
             PackedMatrix3dOps.copy(this.coffs, Matrix3d._productBuffer);
             PackedMatrix3dOps.copy(this.inverseCoffs, this.coffs);
             PackedMatrix3dOps.copy(Matrix3d._productBuffer, this.inverseCoffs);
@@ -1870,33 +1965,50 @@ export class Matrix3d {
         result.inverseState = this.inverseState;
         return result;
     }
-    /* Alternate implementation of computedCachedInverse - more direct addressing of arrays.
-       This is indeed 10% faster than using static work areas. */
-    // take the cross product of two rows of source.
-    // store as a column of dest.
+    /**
+     * Take the dot product of a row (specified by `rowStartA`) of `coffA` and `columnStartB` of `coffB`.
+     * * **Note:** We don't validate row/column numbers. Pass 0/3/6 for row 0/1/2 and pass 0/1/2 for column 0/1/2.
+     */
+    static rowColumnDot(coffA, rowStartA, coffB, columnStartB) {
+        return coffA[rowStartA] * coffB[columnStartB] +
+            coffA[rowStartA + 1] * coffB[columnStartB + 3] +
+            coffA[rowStartA + 2] * coffB[columnStartB + 6];
+    }
+    /**
+     * Take the cross product of 2 rows (specified by `rowStart0` and `rowStart1`) of `source` and store the result
+     * in `columnStart` of `dest`.
+     * * **Note:** We don't validate row/column numbers. Pass 0/3/6 for row 0/1/2 and pass 0/1/2 for column 0/1/2.
+     */
     static indexedRowCrossProduct(source, rowStart0, rowStart1, dest, columnStart) {
         dest[columnStart] = source[rowStart0 + 1] * source[rowStart1 + 2] - source[rowStart0 + 2] * source[rowStart1 + 1];
         dest[columnStart + 3] = source[rowStart0 + 2] * source[rowStart1] - source[rowStart0] * source[rowStart1 + 2];
         dest[columnStart + 6] = source[rowStart0] * source[rowStart1 + 1] - source[rowStart0 + 1] * source[rowStart1];
     }
-    // take the cross product of two columns of source.
-    // store as third column in same Matrix3d.
-    // This is private because the columnStart values are unchecked raw indices into the coffs
+    /**
+     * Take the cross product of 2 columns (i.e., `colStart0` and `colStart1`) of `this` matrix and store the
+     * result in `colStart2` of the same matrix.
+     * * **Note:** We don't validate column numbers. Pass 0/1/2 for column 0/1/2.
+     */
     indexedColumnCrossProductInPlace(colStart0, colStart1, colStart2) {
         const coffs = this.coffs;
         coffs[colStart2] = coffs[colStart0 + 3] * coffs[colStart1 + 6] - coffs[colStart0 + 6] * coffs[colStart1 + 3];
         coffs[colStart2 + 3] = coffs[colStart0 + 6] * coffs[colStart1] - coffs[colStart0] * coffs[colStart1 + 6];
         coffs[colStart2 + 6] = coffs[colStart0] * coffs[colStart1 + 3] - coffs[colStart0 + 3] * coffs[colStart1];
     }
-    /** Form cross products among columns in axisOrder.
-     * For axis order ABC,
-     * * form cross product of column A and B, store in C
+    /**
+     * Form cross products among columns in axisOrder.
+     * For axis order ABC:
+     * * form cross product of column A and B, store in C.
      * * form cross product of column C and A, store in B.
+     * * [A   B   C] ===> [A   B   AxB] ===> [A   (AxB)xA   AxB]
+     *
      * This means that in the final matrix:
-     * * column A is strictly parallel to original column A
-     * * column B is linear combination of only original A and B
-     * * column C is perpendicular to A and B of both the original and final.
-     * * original column C does not participate in the result.
+     * * 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) {
@@ -1932,41 +2044,44 @@ export class Matrix3d {
             }
         }
     }
-    /** Normalize each column in place.
-     * * For false return the magnitudes are stored in the originalMagnitudes vector but no columns are altered.
-     * @returns Return true if all columns had nonzero lengths.
-     * @param originalMagnitudes optional vector to receive original column magnitudes.
+    /**
+     * Normalize each column in place.
+     * @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(originalMagnitudes) {
+    normalizeColumnsInPlace(originalColumnMagnitudes) {
         const ax = this.columnXMagnitude();
         const ay = this.columnYMagnitude();
         const az = this.columnZMagnitude();
-        if (originalMagnitudes)
-            originalMagnitudes.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 */
-    normalizeRowsInPlace(originalMagnitudes) {
+    /**
+     * 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 (originalMagnitudes)
-            originalMagnitudes.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);
         return true;
     }
-    // take the cross product of two rows of source.
-    // store as a column of dest.
-    static rowColumnDot(coffA, rowStartA, coffB, columnStartB) {
-        return coffA[rowStartA] * coffB[columnStartB] + coffA[rowStartA + 1] * coffB[columnStartB + 3] + coffA[rowStartA + 2] * coffB[columnStartB + 6];
-    }
     /**
-     * Returns true if the matrix is singular (i.e. collapses data to a plane, line, or point)
+     * Returns true if the matrix is singular.
      */
     isSingular() {
         return !this.computeCachedInverse(true);
@@ -1978,18 +2093,10 @@ export class Matrix3d {
         this.inverseState = InverseMatrixState.singular;
     }
     /**
-     * Create the inverseCoffs member (filled with zeros)
-     * This is for use by matrix * matrix multiplications which need to be sure the member is there to be
-     * filled with method-specific content.
-     */
-    createInverseCoffsWithZeros() {
-        if (!this.inverseCoffs) {
-            this.inverseState = InverseMatrixState.unknown;
-            this.inverseCoffs = new Float64Array(9);
-        }
-    }
-    /** compute the inverse of this Matrix3d. The inverse is stored for later use.
-     * @returns Return true if the inverse computed.  (False if the columns collapse to a point, line or plane.)
+     * 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.
      */
     computeCachedInverse(useCacheIfAvailable) {
         if (useCacheIfAvailable && Matrix3d.useCachedInverse && this.inverseState !== InverseMatrixState.unknown) {
@@ -2000,71 +2107,46 @@ export class Matrix3d {
         this.createInverseCoffsWithZeros();
         const coffs = this.coffs;
         const inverseCoffs = this.inverseCoffs;
-        Matrix3d.indexedRowCrossProduct(coffs, 3, 6, inverseCoffs, 0);
-        Matrix3d.indexedRowCrossProduct(coffs, 6, 0, inverseCoffs, 1);
-        Matrix3d.indexedRowCrossProduct(coffs, 0, 3, inverseCoffs, 2);
+        /**
+         * We calculate the inverse using cross products.
+         * 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
+        Matrix3d.indexedRowCrossProduct(coffs, 0, 3, inverseCoffs, 2); // AxB
         Matrix3d.numComputeCache++;
-        const d = Matrix3d.rowColumnDot(coffs, 0, inverseCoffs, 0);
-        if (d === 0.0) { // better test?
+        const det = Matrix3d.rowColumnDot(coffs, 0, inverseCoffs, 0); // A dot BxC
+        if (det === 0.0) {
             this.inverseState = InverseMatrixState.singular;
             this.inverseCoffs = undefined;
             return false;
         }
-        const f = 1.0 / d;
+        const f = 1.0 / det;
         for (let i = 0; i < 9; i++)
             inverseCoffs[i] *= f;
         this.inverseState = InverseMatrixState.inverseStored;
-        // verify inverse
-        // const p = new Float64Array(9);
-        // for (let i = 0; i < 9; i += 3)
-        //   for (let j = 0; j < 3; j++)
-        //    p[i + j] = Matrix3d.rowColumnDot (coffs, i, inverseCoffs, j);
         return true;
     }
-    /* "Classic" inverse implementation with temporary vectors.
-      private static rowX: Vector3d = Vector3d.create();
-      private static rowY: Vector3d = Vector3d.create();
-      private static rowZ: Vector3d = Vector3d.create();
-      private static crossXY: Vector3d = Vector3d.create();
-      private static crossZX: Vector3d = Vector3d.create();
-      private static crossYZ: Vector3d = Vector3d.create();
-    private computeCachedInverse(useCacheIfAvailable: boolean) {
-        if (useCacheIfAvailable && Matrix3d.useCachedInverse && this.inverseState !== InverseMatrixState.unknown) {
-          Matrix3d.numUseCache++;
-          return this.inverseState === InverseMatrixState.inverseStored;
-        }
-        this.inverseState = InverseMatrixState.unknown;
-        Matrix3d.numComputeCache++;
-        const rowX = this.rowX(Matrix3d.rowX);
-        const rowY = this.rowY(Matrix3d.rowY);
-        const rowZ = this.rowZ(Matrix3d.rowZ);
-        const crossXY = rowX.crossProduct(rowY, Matrix3d.crossXY);
-        const crossYZ = rowY.crossProduct(rowZ, Matrix3d.crossYZ);
-        const crossZX = rowZ.crossProduct(rowX, Matrix3d.crossZX);
-        const d = rowX.dotProduct(crossYZ);  // that's the determinant
-        if (d === 0.0) {     // better test?
-          this.inverseState = InverseMatrixState.singular;
-          this.inverseCoffs = undefined;
-          return false;
-        }
-        const f = 1.0 / d;
-        this.inverseState = InverseMatrixState.inverseStored;   // Currently just lists that the inverse has been stored... singular case not handled
-        this.inverseCoffs = Float64Array.from([crossYZ.x * f, crossZX.x * f, crossXY.x * f,
-        crossYZ.y * f, crossZX.y * f, crossXY.y * f,
-        crossYZ.z * f, crossZX.z * f, crossXY.z * f]);
-        return true;
-      }
-    */
-    /** convert a (row,column) index pair to the single index within flattened array of 9 numbers in row-major-order  */
+    /**
+     * Convert a (row,column) index pair to the single index within flattened array of 9 numbers in row-major-order
+     * * **Note:** Out of range row/column is interpreted cyclically.
+     */
     static flatIndexOf(row, column) {
         return 3 * Geometry.cyclic3dAxis(row) + Geometry.cyclic3dAxis(column);
     }
-    /** Get a column by index (0,1,2), packaged as a Point4d with given weight.   Out of range index is interpreted cyclically.  */
+    /**
+     * Get elements of column `index` packaged as a Point4d with given `weight`.
+     * * **Note:** Out of range index is interpreted cyclically.
+     */
     indexedColumnWithWeight(index, weight, result) {
         index = Geometry.cyclic3dAxis(index);
         return Point4d.create(this.coffs[index], this.coffs[index + 3], this.coffs[index + 6], weight, result);
     }
-    /** return the entry at specific row and column */
+    /** Return the entry at specific row and column */
     at(row, column) {
         return this.coffs[Matrix3d.flatIndexOf(row, column)];
     }
@@ -2073,19 +2155,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
+    /**
+     * 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;
@@ -2098,7 +2191,7 @@ export class Matrix3d {
         this.coffs[7] *= scaleY;
         this.coffs[8] *= scaleZ;
         if (this.inverseState === InverseMatrixState.inverseStored && this.inverseCoffs !== undefined) {
-            // apply reciprocal scales to the ROWS of the inverse .  . .
+            // apply reciprocal scales to the ROWS of the inverse
             const divX = Geometry.conditionalDivideFraction(1.0, scaleX);
             const divY = Geometry.conditionalDivideFraction(1.0, scaleY);
             const divZ = Geometry.conditionalDivideFraction(1.0, scaleZ);
@@ -2117,18 +2210,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 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) {
@@ -2137,18 +2267,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) {
@@ -2163,65 +2294,107 @@ 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 result.
-     * @returns Return the new or repopulated matrix
+    /**
+     * Create a rigid matrix (columns and rows are unit length and pairwise perpendicular) for the given eye coordinate.
+     * * column 2 is parallel to (x,y,z).
+     * * column 0 is perpendicular to column 2 and is in the xy plane.
+     * * column 1 is perpendicular to both. It is the "up" vector on the view plane.
+     * * Multiplying the returned matrix times a local (view) vector gives the world vector.
+     * * Multiplying transpose of the returned matrix times a world vector gives the local (view) vector.
+     * @param x eye x coordinate
+     * @param y eye y coordinate
+     * @param z eye z coordinate
+     * @param result optional preallocated result
      */
-    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);
+    static createRigidViewAxesZTowardsEye(x, y, z, result) {
+        result = Matrix3d.createIdentity(result);
+        const rxy = Geometry.hypotenuseXY(x, y);
+        // if coordinate is (0,0,z), i.e., Top or Bottom view
+        if (Geometry.isSmallMetricDistance(rxy)) {
+            if (z < 0.0)
+                result.scaleColumnsInPlace(1.0, -1.0, -1.0);
+        }
+        else {
+            /**
+             * The matrix that the "else" statement creates is
+             *        [-s   -s1*c    c1*c]
+             *        [c    -s1*s    c1*s]
+             *        [0      c1      s1 ]
+             * where
+             *        c = x / sqrt(x*x + y*y)
+             *        s = y / sqrt(x*x + y*y)
+             *        c1 = sqrt(x*x + y*y) / sqrt(x*x + y*y + z*z)
+             *        s1 = z / sqrt(x*x + y*y + z*z)
+             *
+             * This is an orthogonal matrix meaning it rotates the standard XYZ axis to ABC axis system
+             * (if matrix is [A B C]). The matrix rotates (0,0,1), i.e., the default Top view or Z axis,
+             * to the eye point (x/r,y/r,z/r) where r = sqrt(x*x + y*y + z*z). The matrix also rotates
+             * (1,0,0) to a point on XY plane.
+             */
+            const c = x / rxy;
+            const s = y / rxy;
+            // if coordinate is (x,y,0), e.g., Front or Back or Left or Right view (for those 4 views x or y is 0 not both)
+            result.setRowValues(-s, 0, c, c, 0, s, 0, 1, 0);
+            // if coordinate is (x,y,z) and z is not 0, i.e., other views such as Iso or RightIso
+            if (z !== 0.0) {
+                const r = Geometry.hypotenuseXYZ(x, y, z);
+                const s1 = z / r;
+                const c1 = rxy / r;
+                result.applyGivensColumnOp(1, 2, c1, -s1);
+            }
+        }
+        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;
     }
@@ -2236,90 +2409,111 @@ export class Matrix3d {
         const sumOff = Math.abs(sumAll - sumDiagonal);
         return Math.sqrt(sumOff) <= Geometry.smallAngleRadians * (1.0 + Math.sqrt(sumAll));
     }
+    /** Sum of squared differences between symmetric pairs (symmetric pairs have indices (1,3), (2,6), and (5,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 (very near to) symmetric */
+    isSymmetric() {
+        const offDiagonal = this.sumSkewSquares();
+        return Math.sqrt(offDiagonal) <= Geometry.smallAngleRadians * (1.0 + Math.sqrt(this.sumSquares()));
+    }
     /** Test if the stored inverse is present and marked valid */
     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[5]);
+        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 */
-    sumSkewSquares() {
-        return Geometry.hypotenuseSquaredXYZ(this.coffs[1] - this.coffs[3], this.coffs[2] - this.coffs[6], this.coffs[5] - this.coffs[7]);
+    /**
+     * 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 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 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();
@@ -2340,22 +2534,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;
@@ -2368,31 +2553,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;
         }
@@ -2433,5 +2644,6 @@ Matrix3d.useCachedInverse = true; // cached inverse can be suppressed for testin
 Matrix3d.numUseCache = 0;
 /** Total number of times a cached inverse was computed. */
 Matrix3d.numComputeCache = 0;
+/** temporary buffer to store a matrix as a Float64Array (array of 9 floats) */
 Matrix3d._productBuffer = new Float64Array(9);
 //# sourceMappingURL=Matrix3d.js.map