@itwin/core-geometry 3.6.0-dev.8 → 4.0.0-dev.10

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
 /**
  * PackedMatrix3dOps contains static methods for matrix operations where the matrix is a Float64Array.
  * * The Float64Array contains the matrix entries in row-major order
@@ -47,7 +48,7 @@ export class PackedMatrix3dOps {
         dest[8] = a22;
     }
     /**
-     * * multiply 3x3 matrix `a*b`, store in c.
+     * Multiply 3x3 matrix `a*b`, store in `result`.
      * * All params assumed length 9, allocated by caller.
      * * c may alias either input.
      */
@@ -58,7 +59,7 @@ export class PackedMatrix3dOps {
         return result;
     }
     /**
-     * * multiply 3x3 matrix `a*bTranspose`, store in c.
+     * Multiply 3x3 matrix `a*bTranspose`, store in `result`.
      * * All params assumed length 9, allocated by caller.
      * * c may alias either input.
      */
@@ -69,7 +70,7 @@ export class PackedMatrix3dOps {
         return result;
     }
     /**
-     * * multiply 3x3 matrix `a*bTranspose`, store in c.
+     * Multiply 3x3 matrix `aTranspose*b`, store in `result`.
      * * All params assumed length 9, allocated by caller.
      * * c may alias either input.
      */
@@ -79,7 +80,7 @@ export class PackedMatrix3dOps {
         PackedMatrix3dOps.loadMatrix(result, (a[0] * b[0] + a[3] * b[3] + a[6] * b[6]), (a[0] * b[1] + a[3] * b[4] + a[6] * b[7]), (a[0] * b[2] + a[3] * b[5] + a[6] * b[8]), (a[1] * b[0] + a[4] * b[3] + a[7] * b[6]), (a[1] * b[1] + a[4] * b[4] + a[7] * b[7]), (a[1] * b[2] + a[4] * b[5] + a[7] * b[8]), (a[2] * b[0] + a[5] * b[3] + a[8] * b[6]), (a[2] * b[1] + a[5] * b[4] + a[8] * b[7]), (a[2] * b[2] + a[5] * b[5] + a[8] * b[8]));
         return result;
     }
-    /** transpose 3x3 coefficients in place */
+    /** Transpose 3x3 matrix `a` in place */
     static transposeInPlace(a) {
         let q = a[1];
         a[1] = a[3];
@@ -91,10 +92,14 @@ export class PackedMatrix3dOps {
         a[5] = a[7];
         a[7] = q;
     }
-    /** transpose 3x3 coefficients in place */
+    /**
+     * Returns the transpose of 3x3 matrix `a`
+     * * If `dest` is passed as argument, then the function copies the transpose of 3x3 matrix `a` into `dest`
+     * * `a` is not changed unless also passed as the dest, i.e., copyTransposed(a,a) transposes `a` in place
+     */
     static copyTransposed(a, dest) {
         if (dest === a) {
-            PackedMatrix3dOps.transposeInPlace(a);
+            PackedMatrix3dOps.transposeInPlace(dest);
         }
         else {
             if (!dest)
@@ -111,7 +116,7 @@ export class PackedMatrix3dOps {
         }
         return dest;
     }
-    /** transpose 3x3 coefficients in place */
+    /** Copy matrix `a` entries into `dest` */
     static copy(a, dest) {
         if (dest !== a) {
             dest[0] = a[0];
@@ -129,29 +134,31 @@ export class PackedMatrix3dOps {
 }
 /** A Matrix3d is tagged indicating one of the following states:
  * * unknown: it is not know if the matrix is invertible.
- * * inverseStored: the matrix has its inverse stored
+ * * inverseStored: the matrix has its inverse stored.
  * * singular: the matrix is known to be singular.
  * @public
  */
 export var InverseMatrixState;
 (function (InverseMatrixState) {
     /**
-     * * The invertibility of the  `coffs` array has not been determined.
-     * * Any `inverseCoffs` contents are random.
+     * The invertibility of the `coffs` array has not been determined.
+     * Any `inverseCoffs` contents are random.
      */
     InverseMatrixState[InverseMatrixState["unknown"] = 0] = "unknown";
-    /** An inverse was computed and stored as the `inverseCoffs` */
+    /**
+     * An inverse was computed and stored as the `inverseCoffs`
+     */
     InverseMatrixState[InverseMatrixState["inverseStored"] = 1] = "inverseStored";
     /**
-     * * The `coffs` array is known to be singular.
-     * * Any `inverseCoffs` contents are random.
+     * The `coffs` array is known to be singular.
+     * Any `inverseCoffs` contents are random.
      */
     InverseMatrixState[InverseMatrixState["singular"] = 2] = "singular";
 })(InverseMatrixState || (InverseMatrixState = {}));
 /** A Matrix3d is a 3x3 matrix.
  * * A very common use is to hold a rigid body rotation (which has no scaling or skew), but the 3x3 contents can
  * also hold scaling and skewing.
- * * The matrix with 2-dimensional layout
+ * * The matrix with 2-dimensional layout (note: a 2d array can be shown by a matrix)
  * ```
  * equation
  *      \matrixXY{A}
@@ -163,19 +170,21 @@ export var InverseMatrixState;
  * ```
  * * If the matrix inverse is known it is stored in the inverseCoffs array.
  * * The inverse status (`unknown`, `inverseStored`, `singular`) status is indicated by the `inverseState` property.
- * * construction methods that are able to trivially construct the inverse store it immediately and note that in the inverseState.
- * * constructions (e.g. createRowValues) for which the inverse is not immediately known mark the
- *     inverseState as unknown.
- * * Later queries for the inverse trigger full computation if needed at that time.
+ * * Construction methods that are able to trivially construct the inverse, store it immediately and note that in
+ * the inverseState.
+ * * Constructions (e.g. createRowValues) for which the inverse is not immediately known mark the inverseState as
+ * unknown.
+ * * Later queries for the inverse, trigger full computation if needed at that time.
  * * Most matrix queries are present with both "column" and "row" variants.
- * * Usage elsewhere in the library is typically "column" based.  For example, in a Transform
- *     that carries a coordinate frame the matrix columns are the unit vectors for the axes.
+ * * Usage elsewhere in the library is typically "column" based.  For example, in a Transform that carries a
+ * coordinate frame, the matrix columns are the unit vectors for the axes.
  * @public
  */
 export class Matrix3d {
     /**
-     *
-     * @param coffs optional coefficient array. This is captured.
+     * Constructor
+     * @param coffs optional coefficient array.
+     * * **WARNING:** coffs is captured (i.e., is now owned by the Matrix3d object and can be modified by it).
      */
     constructor(coffs) {
         this.coffs = coffs ? coffs : new Float64Array(9);
@@ -193,14 +202,16 @@ export class Matrix3d {
     /** Freeze this Matrix3d. */
     freeze() {
         this.computeCachedInverse(true);
-        /* hm.. can't freeze the Float64Arrays . . .
+        /*
+        hm.. can't freeze the Float64Arrays..
         Object.freeze(this.coffs);
         if (this.inverseCoffs)
           Object.freeze(this.inverseCoffs);
         */
         return Object.freeze(this);
     }
-    /** Return a json object containing the 9 numeric entries as a single array in row major order,
+    /**
+     * Return a json object containing the 9 numeric entries as a single array in row major order,
      * `[ [1, 2, 3],[ 4, 5, 6], [7, 8, 9] ]`
      */
     toJSON() {
@@ -208,46 +219,81 @@ export class Matrix3d {
             [this.coffs[3], this.coffs[4], this.coffs[5]],
             [this.coffs[6], this.coffs[7], this.coffs[8]]];
     }
-    /** copy data from various input forms to this matrix.
+    /**
+     * Copy data from various input forms to this matrix.
      * The source can be:
      * * Another `Matrix3d`
      * * An array of 3 arrays, each of which has the 3 numbers for a row of the matrix.
-     * * An array of 9 numbers in row major order.
+     * * An array of 4 or 9 numbers in row major order.
+     * * **WARNING:** if json is an array of numbers but size is not 4 or 9, the matrix is set to zeros.
      */
     setFromJSON(json) {
         this.inverseCoffs = undefined;
+        // if no json is passed
         if (!json) {
             this.setRowValues(0, 0, 0, 0, 0, 0, 0, 0, 0);
             return;
         }
+        // if json is Matrix3d
         if (!Array.isArray(json)) {
             if (json instanceof Matrix3d)
                 this.setFrom(json);
             return;
         }
+        // if json is Matrix3dProps and is an array of arrays
         if (Geometry.isArrayOfNumberArray(json, 3, 3)) {
             const data = json;
             this.setRowValues(data[0][0], data[0][1], data[0][2], data[1][0], data[1][1], data[1][2], data[2][0], data[2][1], data[2][2]);
             return;
         }
+        // if json is Matrix3dProps and is an array of numbers
         if (json.length === 9) {
             const data = json;
             this.setRowValues(data[0], data[1], data[2], data[3], data[4], data[5], data[6], data[7], data[8]);
+            return;
         }
         else if (json.length === 4) {
             const data = json;
             this.setRowValues(data[0], data[1], 0, data[2], data[3], 0, 0, 0, 1);
+            return;
         }
+        // if json is Matrix3dProps but is not the right size
+        this.setRowValues(0, 0, 0, 0, 0, 0, 0, 0, 0);
+        return;
+    }
+    /** Return a new Matrix3d constructed from contents of the json value. See `setFromJSON` for layout rules */
+    static fromJSON(json) {
+        const result = Matrix3d.createIdentity();
+        result.setFromJSON(json);
+        return result;
     }
-    /** Return a new Matrix3d constructed from contents of the json value. Se `setFromJSON` for layout rules */
-    static fromJSON(json) { const result = Matrix3d.createIdentity(); result.setFromJSON(json); return result; }
-    /** Test if this Matrix3d and other are within tolerance in all numeric entries.
+    /**
+     * Test if `this` and `other` are within tolerance in all numeric entries.
      * @param tol optional tolerance for comparisons by Geometry.isDistanceWithinTol
      */
     isAlmostEqual(other, tol) {
         return Geometry.isDistanceWithinTol(this.maxDiff(other), tol);
     }
-    /** Test if `this` and `other` have almost equal Z column and have X and Y columns differing only by a rotation around that Z.
+    /**
+     * Test if `this` and `other` are within tolerance in the column entries specified by `columnIndex`.
+     * @param tol optional tolerance for comparisons by Geometry.isDistanceWithinTol
+     */
+    isAlmostEqualColumn(columnIndex, other, tol) {
+        const max = Geometry.maxAbsXYZ(this.coffs[columnIndex] - other.coffs[columnIndex], this.coffs[columnIndex + 3] - other.coffs[columnIndex + 3], this.coffs[columnIndex + 6] - other.coffs[columnIndex + 6]);
+        return Geometry.isDistanceWithinTol(max, tol);
+    }
+    /**
+     * Test if column (specified by `columnIndex`) entries of `this` and [ax,ay,az] are within tolerance.
+     * @param tol optional tolerance for comparisons by Geometry.isDistanceWithinTol
+     */
+    isAlmostEqualColumnXYZ(columnIndex, ax, ay, az, tol) {
+        const max = Geometry.maxAbsXYZ(this.coffs[columnIndex] - ax, this.coffs[columnIndex + 3] - ay, this.coffs[columnIndex + 6] - az);
+        return Geometry.isDistanceWithinTol(max, tol);
+    }
+    /**
+     * Test if `this` and `other` have almost equal Z column and have X and Y columns differing only by a
+     * rotation of the same angle around that Z.
+     * * **WARNING:** X and Y columns have to be perpendicular to Z column in both `this` and `other`.
      * @param tol optional tolerance for comparisons by Geometry.isDistanceWithinTol
      */
     isAlmostEqualAllowZRotation(other, tol) {
@@ -255,10 +301,15 @@ export class Matrix3d {
             return true;
         if (this.isAlmostEqualColumn(AxisIndex.Z, other, tol)) {
             const radians = Angle.radiansBetweenVectorsXYZ(this.coffs[0], this.coffs[3], this.coffs[6], other.coffs[0], other.coffs[3], other.coffs[6]);
-            const angle = Angle.createRadians(radians);
+            const angle = Angle.createRadians(radians); // angle between X columns in `this` and `other`
             const columnX = this.columnX();
             const columnY = this.columnY();
             const columnZ = this.columnZ();
+            /**
+             * 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.
+             */
             let column = Vector3d.createRotateVectorAroundVector(columnX, columnZ, angle);
             if (other.isAlmostEqualColumnXYZ(0, column.x, column.y, column.z, tol)) {
                 column = Vector3d.createRotateVectorAroundVector(columnY, columnZ, angle);
@@ -267,16 +318,10 @@ export class Matrix3d {
         }
         return false;
     }
-    isAlmostEqualColumn(columnIndex, other, tol) {
-        const a = Geometry.maxAbsXYZ(this.coffs[columnIndex] - other.coffs[columnIndex], this.coffs[columnIndex + 3] - other.coffs[columnIndex + 3], this.coffs[columnIndex + 6] - other.coffs[columnIndex + 6]);
-        return Geometry.isDistanceWithinTol(a, tol);
-    }
-    isAlmostEqualColumnXYZ(columnIndex, ax, ay, az, tol) {
-        const a = Geometry.maxAbsXYZ(this.coffs[columnIndex] - ax, this.coffs[columnIndex + 3] - ay, this.coffs[columnIndex + 6] - az);
-        return Geometry.isDistanceWithinTol(a, tol);
-    }
     /** Test for exact (bitwise) equality with other. */
-    isExactEqual(other) { return this.maxDiff(other) === 0.0; }
+    isExactEqual(other) {
+        return this.maxDiff(other) === 0.0;
+    }
     /** test if all entries in the z row and column are exact 001, i.e. the matrix only acts in 2d */
     get isXY() {
         return this.coffs[2] === 0.0
@@ -285,10 +330,16 @@ export class Matrix3d {
             && this.coffs[7] === 0.0
             && this.coffs[8] === 1.0;
     }
-    // !! does not clear supplied result !!
-    static _create(result) { return result ? result : new Matrix3d(); }
-    /** Returns a Matrix3d populated by numeric values given in row-major order.
-     *  set all entries in the matrix from call parameters appearing in row - major order, i.e.
+    /**
+     * If result is not provided, then the method returns a new (zeroed) matrix; otherwise the result is
+     * not zeroed first and is just returned as-is.
+     */
+    static _create(result) {
+        return result ? result : new Matrix3d();
+    }
+    /**
+     * Returns a Matrix3d populated by numeric values given in row-major order.
+     * Sets all entries in the matrix from call parameters appearing in row-major order, i.e.
      * ```
      * equation
      * \begin{bmatrix}a_{xx}\ a_{xy}\ a_{xz}\\ a_{yx}\ a_{yy}\ a_{yz}\\ a_{zx}\ a_{zy}\ a_{zz}\end{bmatrix}
@@ -319,7 +370,7 @@ export class Matrix3d {
     }
     /**
      * Create a Matrix3d with caller-supplied coefficients and optional inverse coefficients.
-     * * The inputs are captured into the new Matrix3d.
+     * * The inputs are captured into (i.e., owned by) the new Matrix3d.
      * * The caller is responsible for validity of the inverse coefficients.
      * @param coffs (required) array of 9 coefficients.
      * @param inverseCoffs (optional) array of 9 coefficients.
@@ -337,12 +388,15 @@ export class Matrix3d {
         return result;
     }
     /**
-     * create a matrix by distributing vectors to columns in one of 6 orders.
+     * Create a matrix by distributing vectors to columns in one of 6 orders.
      * @param axisOrder identifies where the columns are placed.
-     * @param columnA vector to place in the first column named by the axis order.
-     * @param columnB vector to place in the second column named by the axis order.
-     * @param columnC vector to place in the third column named by the axis order.
-     * @param result
+     * @param columnA vector to place in the column specified by first letter in the AxisOrder name.
+     * @param columnB vector to place in the column specified by second letter in the AxisOrder name.
+     * @param columnC vector to place in the column specified by third letter in the AxisOrder name.
+     * @param result optional result matrix3d
+     * * Example: If you pass AxisOrder.YZX, then result will be [columnC, columnA, columnB] because
+     * first letter Y means columnA should go to the second column, second letter Z means columnB should
+     * go to the third column, and third letter X means columnC should go to the first column.
      */
     static createColumnsInAxisOrder(axisOrder, columnA, columnB, columnC, result) {
         if (!result)
@@ -362,13 +416,26 @@ export class Matrix3d {
         else if (axisOrder === AxisOrder.ZYX) {
             result.setColumns(columnC, columnB, columnA);
         }
-        else { // fallthrough should only happen for AxisOrder.XYZ
+        else { // AxisOrder.XYZ
             result.setColumns(columnA, columnB, columnC);
         }
         return result;
     }
     /**
-     *  set all entries in the matrix from call parameters appearing in row-major order.
+   * Copy the transpose of the coffs to the inverseCoffs.
+   * * Mark the matrix as inverseStored.
+   */
+    setupInverseTranspose() {
+        const coffs = this.coffs;
+        this.inverseState = InverseMatrixState.inverseStored;
+        this.inverseCoffs = Float64Array.from([
+            coffs[0], coffs[3], coffs[6],
+            coffs[1], coffs[4], coffs[7],
+            coffs[2], coffs[5], coffs[8],
+        ]);
+    }
+    /**
+     * Set all entries in the matrix from call parameters appearing in row-major order.
      * @param axx Row x, column x (0,0) entry
      * @param axy Row x, column y (0,1) entry
      * @param axz Row x, column z (0,2) entry
@@ -392,15 +459,22 @@ export class Matrix3d {
         this.inverseState = InverseMatrixState.unknown;
     }
     /** Set the matrix to an identity. */
-    setIdentity() { this.setRowValues(1, 0, 0, 0, 1, 0, 0, 0, 1); this.setupInverseTranspose(); }
+    setIdentity() {
+        this.setRowValues(1, 0, 0, 0, 1, 0, 0, 0, 1);
+        this.setupInverseTranspose();
+    }
     /** Set the matrix to all zeros. */
-    setZero() { this.setRowValues(0, 0, 0, 0, 0, 0, 0, 0, 0); this.inverseState = InverseMatrixState.singular; }
-    /** copy contents from another matrix. */
+    setZero() {
+        this.setRowValues(0, 0, 0, 0, 0, 0, 0, 0, 0);
+        this.inverseState = InverseMatrixState.singular;
+    }
+    /** Copy contents from another matrix. */
     setFrom(other) {
         if (other === undefined) {
             this.setIdentity();
+            return;
         }
-        else if (other !== this) {
+        if (other !== this) {
             for (let i = 0; i < 9; i++)
                 this.coffs[i] = other.coffs[i];
             if (other.inverseState === InverseMatrixState.inverseStored && other.inverseCoffs !== undefined) {
@@ -412,28 +486,29 @@ export class Matrix3d {
             else if (other.inverseState !== InverseMatrixState.inverseStored) {
                 this.inverseState = other.inverseState;
             }
-            else { // This is reached of other says stored but does not have coffs.  This should not happen.
+            else { // This is reached when other says stored but does not have coffs. This should not happen.
                 this.inverseState = InverseMatrixState.unknown;
             }
         }
     }
-    /** return a clone of this matrix.
-     * * coefficients are copied.
-     * * inverse coefficients are NOT copied.
-     * * inverse status is set to unknown
+    /**
+     * Return a clone of this matrix.
+     * * Coefficients are copied.
+     * * Inverse coefficients and inverse status are copied if stored by `this`.
      */
     clone(result) {
         result = result ? result : new Matrix3d();
         result.setFrom(this);
         return result;
     }
-    /** create a matrix with all zeros.
+    /**
+     * Create a matrix with all zeros.
      * * Note that for geometry transformations "all zeros" is not a useful default state.
-     * * Hence almost always use `createIdentity` for graphics transformations.
-     * * "all zeros" is appropriate for summing moment data.
+     * * Hence, almost always use `createIdentity` for graphics transformations.
+     * * "All zeros" is appropriate for summing moment data.
      * ```
      * equation
-     * \begin{bmatrix}0 0 0 \\ 0 0 0 \\ 0 0 0\end{bmatrix}
+     * \begin{bmatrix}0 & 0 & 0 \\ 0 & 0 & 0 \\ 0 & 0 & 0\end{bmatrix}
      * ```
      */
     static createZero() {
@@ -441,13 +516,14 @@ export class Matrix3d {
         retVal.inverseState = InverseMatrixState.singular;
         return retVal;
     }
-    /** create an identity matrix.
-     * * all diagonal entries (xx,yy,zz) are one
-     * * all others are zero.
-     * * This (rather than all zeros) is the useful state for most graphics transformations.
+    /**
+     * Create an identity matrix.
+     * * All diagonal entries (xx,yy,zz) are one
+     * * All others are zero.
+     * * This (rather than "all zeros") is the useful state for most graphics transformations.
      * ```
      * equation
-     * \begin{bmatrix}1 0 0 \\ 0 1 0 \\ 0 0 1\end{bmatrix}
+     * \begin{bmatrix}1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1\end{bmatrix}
      * ```
      *
      */
@@ -457,55 +533,7 @@ export class Matrix3d {
         return result;
     }
     /**
-     * Create a matrix with uniform scale factors.
-     * For scale factor _s_,
-     * ```
-     * equation
-     * \begin{bmatrix}s & 0 & 0 \\ 0 & s & 0\\ 0 & 0 & s\end{bmatrix}
-     * ```
-     */
-    static createUniformScale(scaleFactor) {
-        return Matrix3d.createScale(scaleFactor, scaleFactor, scaleFactor);
-    }
-    /**
-     * Construct a rigid matrix using createPerpendicularVectorFavorXYPlane to generate a vector perpendicular to vectorA.
-     * *
-     */
-    static createRigidHeadsUp(vectorA, axisOrder = AxisOrder.ZXY, result) {
-        const vectorB = Matrix3d.createPerpendicularVectorFavorXYPlane(vectorA);
-        const matrix = Matrix3d.createRigidFromColumns(vectorA, vectorB, axisOrder, result);
-        if (matrix) {
-            matrix.setupInverseTranspose();
-            return matrix;
-        }
-        return Matrix3d.createIdentity(result);
-    }
-    /**
-     * return a vector that is perpendicular to the input direction.
-     * * Among the infinite number of perpendiculars possible, this method
-     * favors having one in the xy plane.
-     * * Hence, when vectorA is NOT close to the Z axis, the returned vector is Z cross vectorA.
-     * * But vectorA is close to the Z axis, the returned vector is unitY cross vectorA.
-     */
-    static createPerpendicularVectorFavorXYPlane(vector, result) {
-        const a = vector.magnitude();
-        const b = a / 64.0; // A constant from the dawn of time in the CAD industry.
-        if (Math.abs(vector.x) < b && Math.abs(vector.y) < b) {
-            return Vector3d.createCrossProduct(vector.x, vector.y, vector.z, 0, -1, 0, result);
-        }
-        return Vector3d.createCrossProduct(0, 0, 1, vector.x, vector.y, vector.z, result);
-    }
-    /**
-     * return a vector that is perpendicular to the input direction.
-     * * Among the infinite number of perpendiculars possible, this method
-     * favors having one near the Z.
-     * That is achieved by crossing "this" vector with the result of createPerpendicularVectorFavorXYPlane.
-     */
-    static createPerpendicularVectorFavorPlaneContainingZ(vector, result) {
-        result = Matrix3d.createPerpendicularVectorFavorXYPlane(vector, result);
-        return vector.crossProduct(result, result);
-    }
-    /** Create a matrix with distinct x,y,z diagonal (scale) entries.
+     * Create a matrix with distinct x,y,z diagonal (scale) entries.
      * ```
      * equation
      * \begin{bmatrix}s_x & 0 & 0 \\ 0 & s_y & 0\\ 0 & 0 & s_z\end{bmatrix}
@@ -530,8 +558,104 @@ export class Matrix3d {
         }
         return result;
     }
-    /** return a rotation of specified angle around an axis */
+    /**
+     * Create a matrix with uniform scale factors for scale factor "s"
+     * ```
+     * equation
+     * \begin{bmatrix}s & 0 & 0 \\ 0 & s & 0\\ 0 & 0 & s\end{bmatrix}
+     * ```
+     */
+    static createUniformScale(scaleFactor) {
+        return Matrix3d.createScale(scaleFactor, scaleFactor, scaleFactor);
+    }
+    /**
+     * Return a vector that is perpendicular to the input `vectorA`.
+     * * Among the infinite number of perpendiculars possible, this method favors having one in the xy plane.
+     * * Hence, when `vectorA` is close to the Z axis, the returned vector is `vectorA cross -unitY`
+     * but when `vectorA` is NOT close to the Z axis, the returned vector is `unitZ cross vectorA`.
+     */
+    static createPerpendicularVectorFavorXYPlane(vectorA, result) {
+        const a = vectorA.magnitude();
+        const scale = 64.0; // A constant from the dawn of time in the CAD industry
+        const b = a / scale;
+        // if vectorA is close to the Z axis
+        if (Math.abs(vectorA.x) < b && Math.abs(vectorA.y) < b) {
+            return Vector3d.createCrossProduct(vectorA.x, vectorA.y, vectorA.z, 0, -1, 0, result);
+        }
+        // if vectorA is NOT close to the Z axis
+        return Vector3d.createCrossProduct(0, 0, 1, vectorA.x, vectorA.y, vectorA.z, result);
+    }
+    /**
+     * Return a vector that is perpendicular to the input `vectorA`.
+     * * Among the infinite number of perpendiculars possible, this method favors having one near the plane
+     * containing Z.
+     * That is achieved by cross product of `this` vector with the result of createPerpendicularVectorFavorXYPlane.
+     */
+    static createPerpendicularVectorFavorPlaneContainingZ(vectorA, result) {
+        /**
+         * vectorA, result (below), and "vectorA cross result" form a coordinate system where "result" is located on
+         * the XY-plane. Once you've got a coordinate system with an axis in the XY-plane, your other two axes form
+         * a plane that includes the z-axis.
+         */
+        result = Matrix3d.createPerpendicularVectorFavorXYPlane(vectorA, result);
+        return vectorA.crossProduct(result, result);
+    }
+    /**
+     * Create a matrix from column vectors, shuffled into place per axisOrder
+     * For example, if axisOrder = XYZ then it returns [vectorU, vectorV, vectorW]
+     * Another example, if axisOrder = YZX then it returns [vectorW, vectorU, vectorV] because
+     * Y is at index 0 so vectorU goes to the column Y (column 2), Z is at index 1 so vectorV goes
+     * to the column Z (column 3), and X is at index 2 so vectorW goes to the column X (column 1)
+     */
+    static createShuffledColumns(vectorU, vectorV, vectorW, axisOrder, result) {
+        const target = Matrix3d._create(result);
+        target.setColumn(Geometry.axisOrderToAxis(axisOrder, 0), vectorU);
+        target.setColumn(Geometry.axisOrderToAxis(axisOrder, 1), vectorV);
+        target.setColumn(Geometry.axisOrderToAxis(axisOrder, 2), vectorW);
+        return target;
+    }
+    /**
+     * Create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).
+     * * `vectorA1 = Normalized vectorA` is placed in the column specified by **first** letter in
+     * the AxisOrder name.
+     * * Normalized `vectorC1 = vectorA1 cross vectorB` is placed in the column specified by **third**
+     * letter in the AxisOrder name.
+     * * Normalized  `vectorC1 cross vectorA` is placed in the column specified by **second**
+     * letter in the AxisOrder name.
+     * * This function internally uses createShuffledColumns.
+     */
+    static createRigidFromColumns(vectorA, vectorB, axisOrder, result) {
+        const vectorA1 = vectorA.normalize();
+        if (vectorA1) {
+            const vectorC1 = vectorA1.unitCrossProduct(vectorB);
+            if (vectorC1) {
+                const vectorB1 = vectorC1.unitCrossProduct(vectorA);
+                if (vectorB1) {
+                    const retVal = Matrix3d.createShuffledColumns(vectorA1, vectorB1, vectorC1, axisOrder, result);
+                    retVal.setupInverseTranspose();
+                    return retVal;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 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.
+     */
+    static createRigidHeadsUp(vectorA, axisOrder = AxisOrder.ZXY, result) {
+        const vectorB = Matrix3d.createPerpendicularVectorFavorXYPlane(vectorA);
+        const matrix = Matrix3d.createRigidFromColumns(vectorA, vectorB, axisOrder, result);
+        if (matrix) {
+            matrix.setupInverseTranspose();
+            return matrix;
+        }
+        return Matrix3d.createIdentity(result);
+    }
+    /** Return the matrix for rotation of `angle` around desired `axis` */
     static createRotationAroundVector(axis, angle, result) {
+        // Rodriguez formula (matrix form), https://mathworld.wolfram.com/RodriguesRotationFormula.html
         const c = angle.cos();
         const s = angle.sin();
         const v = 1.0 - c;
@@ -543,10 +667,11 @@ 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.
+     * * Math details of 3d rotation matrices derivation can be found at docs/learning/geometry/Angle.md
      */
     static createRotationAroundAxisIndex(axisIndex, angle, result) {
         const c = angle.cos();
@@ -564,27 +689,101 @@ export class Matrix3d {
         myResult.setupInverseTranspose();
         return myResult;
     }
+    /**
+     * 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) {
+            const a = this.coffs[i];
+            const b = this.coffs[j];
+            this.coffs[i] = a * c + b * s;
+            this.coffs[j] = -a * s + b * c;
+        }
+    }
+    /**
+     * 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);
+    }
+    /** Create a matrix with each column's _x,y_ parts given `XAndY` and separate numeric z values.
+     * ```
+     * equation
+     * \begin{bmatrix}U_x & V_x & W_x \\ U_y & V_y & W_y \\ u & v & w \end{bmatrix}
+     * ```
+     */
+    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 in the upVectorDirection
-     * * ColumnZ is a unit cross product.
-     * Optionally rotate the standard cube by 45 to bring its left or right vertical edge to center
-     * * leftNoneRight = [-1,0,1] respectively for left edge, no rotation, or right edge
-     * * bottomNoneTop = [-1,0,1] respectively for isometric rotation to view the bottom, no isometric rotation, and isometric rotation to view the top
-     * This is expected to be used with various principal unit vectors that are perpendicular to each other.
-     *  * STANDARD TOP VIEW: (Vector3d.UnitX (), Vector3d.UnitY (), 0, 0)
-     *  * STANDARD FRONT VIEW: (Vector3d.UnitX (), Vector3d.UnitZ (), 0, 0)
-     *  * STANDARD BACK VIEW: (Vector3d.UnitX (-1), Vector3d.UnitZ (), 0, 0)
-     *  * STANDARD RIGHT VIEW: (Vector3d.UnitY (1), Vector3d.UnitZ (), 0, 0)
-     *  * STANDARD LEFT VIEW: (Vector3d.UnitY (-1), Vector3d.UnitZ (), 0, 0)
-     *  * STANDARD BOTTOM VIEW: (Vector3d.UnitX (1), Vector3d.UnitY (-1), 0, 0)
-     * @param leftNoneRight Normally one of {-1,0,1}, where (-1) indicates the left vertical is rotated to center and (1) for right.  Other numbers are used as multiplier for this 45 degree rotation
-     * @returns undefined if columnX, columnY are coplanar.
+     * * ColumnY points in the upVector direction
+     * * ColumnZ is a unit cross product of ColumnX and ColumnY.
+     * * Optionally rotate by 45 degrees around `upVector` to bring its left or right vertical edge to center.
+     * * Optionally rotate by arctan(1/sqrt(2)) ~ 35.264 degrees around `rightVector` to bring the top or bottom
+     * horizontal edge of the view to the center (for isometric views).
+     * * This is expected to be used with various principal unit vectors that are perpendicular to each other.
+     * * 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 `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 `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
+     * by leftNoneRight and topNoneBottom. Returns undefined if rightVector and upVector are parallel.
      */
     static createViewedAxes(rightVector, upVector, leftNoneRight = 0, topNoneBottom = 0) {
         const columnZ = rightVector.crossProduct(upVector);
         if (columnZ.normalizeInPlace()) {
-            const geometry = Matrix3d.createColumns(rightVector, upVector, columnZ);
+            // matrix = [rightVector, upVector, rightVector cross upVector]
+            const matrix = Matrix3d.createColumns(rightVector, upVector, columnZ);
+            // "45 degrees * leftNoneRight" rotation around Y
             if (leftNoneRight !== 0.0) {
                 let c = Math.sqrt(0.5);
                 let s = leftNoneRight < 0.0 ? -c : c;
@@ -593,377 +792,213 @@ export class Matrix3d {
                     c = Math.cos(radians);
                     s = Math.sin(radians);
                 }
-                geometry.applyGivensColumnOp(2, 0, c, s); // rotate around Y
+                matrix.applyGivensColumnOp(2, 0, c, s); // rotate around Y (equivalent to matrix*rotationY)
             }
+            // "35.264 degrees * topNoneBottom" rotation around X
             if (topNoneBottom !== 0.0) {
                 const theta = topNoneBottom * Math.atan(Math.sqrt(0.5));
                 const c = Math.cos(theta);
                 const s = Math.sin(theta);
-                geometry.applyGivensColumnOp(1, 2, c, -s); // rotate around X
+                matrix.applyGivensColumnOp(1, 2, c, -s); // rotate around X (equivalent to matrix*rotationX)
             }
-            return geometry;
+            return matrix;
         }
         return undefined;
     }
     /**
      * Create a rotation matrix for one of the 8 standard views.
-     * * With `invert === false` the return is such that `matrix.multiply(worldVector)` returns the vector as seen in the xy (projected) coordinates of the view.
-     * * With invert === true the matrix is transposed so that `matrix.multiply(viewVector` maps the "in view" vector to a world vector.
+     * * 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 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, LeftIso`
-     * @param invert if false (default), the returned Matrix3d "projects" world vectors into XY view vectors.  If true, it is inverted to map view vectors to world.
+     * @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
+     * matrix is local (view) to world.
      * @param result optional result.
      */
     static createStandardWorldToView(index, invert = false, result) {
         switch (index) {
+            // 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
             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
             case StandardViewIndex.Right:
                 result = Matrix3d.createRowValues(0, 1, 0, 0, 0, 1, 1, 0, 0);
                 break;
-            case StandardViewIndex.Front: // 0-based 4
+            // 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;
-            case StandardViewIndex.Back: // 0-based 5
+            // 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:
                 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;
+            // 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
-    }
-  */
+    /**
+     * Apply (in place) a jacobi update that zeros out this.at(i,j).
+     * @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 eigenvectors of this Matrix3d
+     * (allocated by caller, computed and filled by this function)
+     */
+    applyFastSymmetricJacobiUpdate(i, j, k, 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);
+    }
+    /**
+     * 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 leftEigenvectors a matrix that its columns will be filled by eigenvectors of this Matrix3d
+     * (allocated by caller, computed and filled by this function)
+     * @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();
+        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;
+    }
     /**
      * Compute the (unit vector) axis and angle of rotation.
-     * @returns Returns with result.ok === true when the conversion succeeded.
+     * * 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)) {
                 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 };
-        return result;
-    }
-    /**
-     * Returns a matrix that rotates from vectorA to vectorB.
-     */
-    static createRotationVectorToVector(vectorA, vectorB, result) {
-        return this.createPartialRotationVectorToVector(vectorA, 1.0, vectorB, result);
-    }
-    /**
-     * 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 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 --
-            return Matrix3d.createRotationAroundVector(upVector, Angle.createRadians(fraction * vectorA.planarAngleTo(vectorB, upVector).radians));
-        }
-        // fail if either vector is zero ...
-        if (Geometry.isSmallMetricDistance(vectorA.magnitude())
-            || Geometry.isSmallMetricDistance(vectorB.magnitude()))
-            return undefined;
-        // nonzero but aligned vectors ...
-        if (vectorA.dotProduct(vectorB) > 0.0)
-            return Matrix3d.createIdentity(result);
-        // nonzero opposing vectors ..
-        upVector = Matrix3d.createPerpendicularVectorFavorPlaneContainingZ(vectorA, upVector);
-        return Matrix3d.createRotationAroundVector(upVector, Angle.createRadians(fraction * Math.PI));
-    }
-    /** Create a 90 degree rotation around a principal axis */
-    static create90DegreeRotationAroundAxis(axisIndex) {
-        axisIndex = Geometry.cyclic3dAxis(axisIndex);
-        if (axisIndex === 0) {
-            const retVal = Matrix3d.createRowValues(1, 0, 0, 0, 0, -1, 0, 1, 0);
-            retVal.setupInverseTranspose();
-            return retVal;
-        }
-        else if (axisIndex === 1) {
-            const retVal = Matrix3d.createRowValues(0, 0, 1, 0, 1, 0, -1, 0, 0);
-            retVal.setupInverseTranspose();
-            return retVal;
-        }
-        else {
-            const retVal = Matrix3d.createRowValues(0, -1, 0, 1, 0, 0, 0, 0, 1);
-            retVal.setupInverseTranspose();
-            return retVal;
-        }
-    }
-    /** 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); }
-    /** Return the X column magnitude squared */
-    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]); }
-    /** Return the Z column magnitude squared */
-    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]); }
-    /** Return the Y column magnitude */
-    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]); }
-    /** 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 Y row magnitude  */
-    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 */
-    /** 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];
-    }
-    /**
-     * 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 x x component of vector
-     * @param y y component of vector
-     * @param z z component of vector
-     */
-    columnDotXYZ(columnIndex, x, y, z) {
-        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); }
-    /** Return (a copy of) the Y row */
-    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); }
-    /** 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);
-    }
-    /**
-     * 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;
-        }
-    }
-    /**
-     * Replace current columns Ui Uj with (c*Ui - s*Uj) and (c*Uj + s*Ui).
-     * * This is used in compute intensive inner loops -- 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
-     */
-    applyGivensColumnOp(i, j, c, s) {
-        const limit = i + 9;
-        for (; i < limit; i += 3, j += 3) {
-            const a = this.coffs[i];
-            const b = this.coffs[j];
-            this.coffs[i] = a * c + b * s;
-            this.coffs[j] = -a * s + b * c;
-        }
-    }
-    /**
-     * 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);
-            }
-        }
+        const result = {
+            axis: Vector3d.create(skewYZ * a, skewZX * a, skewXY * a),
+            angle: Angle.createAtan2(s, c),
+            ok: true,
+        };
         return result;
     }
     /** Rotate so columns i and j become perpendicular */
@@ -995,8 +1030,7 @@ export class Matrix3d {
     factorPerpendicularColumns(matrixC, matrixU) {
         matrixC.setFrom(this);
         matrixU.setIdentity();
-        const ss = this.sumSquares();
-        const tolerance = 1.0e-12 * ss;
+        const tolerance = 1.0e-12 * this.sumSquares();
         for (let iteration = 0; iteration < 7; iteration++) {
             const sum = matrixC.applyJacobiColumnRotation(0, 1, matrixU)
                 + matrixC.applyJacobiColumnRotation(0, 2, matrixU)
@@ -1054,90 +1088,26 @@ export class Matrix3d {
         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);
-    }
-    /**
-     * 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;
-    }
-    /** 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))
+        if (Math.abs(uDotV) < 1.0e-15 * (uDotU + vDotV))
             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);
+        // 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);
     }
     /**
      * Factor this (symmetrized) as a product U * lambda * UT where U is orthogonal, lambda is diagonal.
@@ -1145,15 +1115,17 @@ export class Matrix3d {
      * @param matrixC (allocate by caller, computed here)
      * @param factor  (allocate by caller, computed here)
      */
-    fastSymmetricEigenvalues(leftEigenvectors, lambda) {
+    symmetricEigenvalues(leftEigenvectors, lambda) {
         const matrix = this.clone();
         leftEigenvectors.setIdentity();
-        const ss = this.sumSquares();
-        const tolerance = 1.0e-12 * ss;
+        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();
         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);
+            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) {
@@ -1165,32 +1137,180 @@ export class Matrix3d {
         return false;
     }
     /**
-     * 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}
-     * ```
+     * 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 means rotate all the way)
+     * @param vectorB final vector position
+     * @param result optional result matrix.
      */
-    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);
+    static createPartialRotationVectorToVector(vectorA, fraction, vectorB, result) {
+        let upVector = vectorA.unitCrossProduct(vectorB);
+        // 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));
+        }
+        // if either vector is zero
+        if (Geometry.isSmallMetricDistance(vectorA.magnitude())
+            || Geometry.isSmallMetricDistance(vectorB.magnitude()))
+            return undefined;
+        // aligned vectors (cross product = 0, dot product > 0)
+        if (vectorA.dotProduct(vectorB) > 0.0)
+            return Matrix3d.createIdentity(result);
+        // opposing vectors (cross product = 0, dot product < 0)
+        upVector = Matrix3d.createPerpendicularVectorFavorPlaneContainingZ(vectorA, upVector);
+        return Matrix3d.createRotationAroundVector(upVector, Angle.createRadians(fraction * Math.PI));
     }
-    /** Create a matrix with each column's _x,y_ parts given `XAndY` and separate numeric z values.
-     * ```
-     * equation
-     * \begin{bmatrix}U_x & V_x & W_x \\ U_y & V_y & W_y \\ u & v & w \end{bmatrix}
-     * ```
+    /** 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);
+        if (axisIndex === 0) {
+            const retVal = Matrix3d.createRowValues(1, 0, 0, 0, 0, -1, 0, 1, 0);
+            retVal.setupInverseTranspose();
+            return retVal;
+        }
+        else if (axisIndex === 1) {
+            const retVal = Matrix3d.createRowValues(0, 0, 1, 0, 1, 0, -1, 0, 0);
+            retVal.setupInverseTranspose();
+            return retVal;
+        }
+        else {
+            const retVal = Matrix3d.createRowValues(0, -1, 0, 1, 0, 0, 0, 0, 1);
+            retVal.setupInverseTranspose();
+            return retVal;
+        }
+    }
+    /** 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);
+    }
+    /** Return the X column magnitude squared */
+    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]);
+    }
+    /** Return the Z column magnitude squared */
+    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]);
+    }
+    /** Return the Y column magnitude */
+    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]);
+    }
+    /** 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 */
+    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]);
+    }
+    /** 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 */
+    columnXDotColumnY() {
+        return this.coffs[0] * this.coffs[1]
+            + this.coffs[3] * this.coffs[4]
+            + this.coffs[6] * this.coffs[7];
+    }
+    /**
+     * 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 x x component of vector
+     * @param y y component of vector
+     * @param z z component of vector
      */
-    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);
+    columnDotXYZ(columnIndex, x, y, z) {
+        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);
+    }
+    /** Return (a copy of) the Y row */
+    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);
+    }
+    /** 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];
+    }
+    /** 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];
     }
-    /** Install data from xyz parts of Point4d  (w part of Point4d ignored) */
+    /** 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);
+    }
+    /** 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);
     }
     /**
-     * set entries in one column of the matrix.
-     * @param columnIndex column index. this is interpreted cyclically.
+     * Set entries in one column of the matrix.
+     * @param columnIndex column index (this is interpreted cyclically. See Geometry.cyclic3dAxis for more info).
      * @param value x,yz, values for column.  If undefined, zeros are installed.
      */
     setColumn(columnIndex, value) {
@@ -1207,16 +1327,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);
@@ -1225,29 +1351,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 column vectors, shuffled into place per AxisTriple */
-    static createShuffledColumns(vectorU, vectorV, vectorW, axisOrder, result) {
-        const target = Matrix3d._create(result);
-        target.setColumn(Geometry.axisOrderToAxis(axisOrder, 0), vectorU);
-        target.setColumn(Geometry.axisOrderToAxis(axisOrder, 1), vectorV);
-        target.setColumn(Geometry.axisOrderToAxis(axisOrder, 2), vectorW);
-        return target;
-    }
-    /** 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}
@@ -1256,13 +1379,18 @@ 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.}
      * ```
      */
     static createDirectionalScale(direction, scale, result) {
@@ -1271,19 +1399,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}
@@ -1294,36 +1416,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;
@@ -1332,61 +1456,72 @@ 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;
     }
     /**
@@ -1406,9 +1541,9 @@ export class Matrix3d {
         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.
@@ -1678,7 +1813,11 @@ export class Matrix3d {
         this.multiplyMatrixMatrix(other.matrix, result.matrix);
         return result;
     }
-    /** return a transposed matrix. `this` is not changed unless also passed as the 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
+     */
     transpose(result) {
         if (!result)
             result = new Matrix3d();
@@ -1693,8 +1832,8 @@ export class Matrix3d {
         }
         return result;
     }
-    /** transpose this matrix in place.
-     *
+    /**
+     * Transpose this matrix in place.
      */
     transposeInPlace() {
         PackedMatrix3dOps.transposeInPlace(this.coffs);
@@ -1725,18 +1864,6 @@ export class Matrix3d {
         result.inverseState = this.inverseState;
         return result;
     }
-    /** copy the transpose of the coffs to the inverseCoffs.
-     * * mark the matrix as inverseStored.
-     */
-    setupInverseTranspose() {
-        const coffs = this.coffs;
-        this.inverseState = InverseMatrixState.inverseStored;
-        this.inverseCoffs = Float64Array.from([
-            coffs[0], coffs[3], coffs[6],
-            coffs[1], coffs[4], coffs[7],
-            coffs[2], coffs[5], coffs[8]
-        ]);
-    }
     /* 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.
@@ -1844,8 +1971,10 @@ export class Matrix3d {
     markSingular() {
         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.
+    /**
+     * 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) {
@@ -1942,7 +2071,7 @@ export class Matrix3d {
      * @param scaleX scale factor for column x
      * @param scaleY scale factor for column y
      * @param scaleZ scale factor for column z
-     * @param result optional result.
+     * @param result optional preallocated 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);
@@ -1963,7 +2092,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 reverse 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);
@@ -1986,7 +2115,7 @@ export class 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.
+     * @param result optional preallocated 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);
@@ -1994,7 +2123,7 @@ export class Matrix3d {
     /**
      * add scaled values from other Matrix3d to this Matrix3d
      * @param other Matrix3d with values to be added
-     * @param scale scale factor to apply to th eadded values.
+     * @param scale scale factor to apply to the added values.
      */
     addScaledInPlace(other, scale) {
         for (let i = 0; i < 9; i++)
@@ -2030,12 +2159,49 @@ export class Matrix3d {
     }
     /** create a Matrix3d whose values are uniformly scaled from this.
      * @param scale scale factor to apply.
-     * @param result optional result.
+     * @param result optional preallocated result.
      * @returns Return the new or repopulated matrix
      */
     scale(scale, result) {
         return Matrix3d.createRowValues(this.coffs[0] * scale, this.coffs[1] * scale, this.coffs[2] * scale, this.coffs[3] * scale, this.coffs[4] * scale, this.coffs[5] * scale, this.coffs[6] * scale, this.coffs[7] * scale, this.coffs[8] * scale, result);
     }
+    /**
+     * Create a rigid matrix (columns and rows are unit length and pairwise perpendicular) for
+     * the given eye coordinate.
+     * * column z is parallel to x,y,z
+     * * column x is perpendicular to column z and is in the xy plane
+     * * column y 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
+     */
+    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 {
+            const c = x / rxy;
+            const s = y / rxy;
+            // if coordinate is (x,y,0), i.e., Front or Back or Left or Right view
+            result.setRowValues(-s, 0, c, c, 0, s, 0, 1, 0);
+            // if coordinate is (x,y,z), 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. */
     determinant() {
         return this.coffs[0] * this.coffs[4] * this.coffs[8]
@@ -2057,18 +2223,18 @@ export class Matrix3d {
     /** Return the sum of squares of all entries */
     sumSquares() {
         let i = 0;
-        let a = 0;
+        let sum = 0;
         for (i = 0; i < 9; i++)
-            a += this.coffs[i] * this.coffs[i];
-        return a;
+            sum += this.coffs[i] * this.coffs[i];
+        return sum;
     }
     /** Return the sum of squares of diagonal entries */
     sumDiagonalSquares() {
         let i = 0;
-        let a = 0;
+        let sum = 0;
         for (i = 0; i < 9; i += 4)
-            a += this.coffs[i] * this.coffs[i];
-        return a;
+            sum += this.coffs[i] * this.coffs[i];
+        return sum;
     }
     /** Return the sum of diagonal entries (also known as the trace) */
     sumDiagonal() {
@@ -2077,18 +2243,18 @@ export class Matrix3d {
     /** Return the Maximum absolute value of any single entry */
     maxAbs() {
         let i = 0;
-        let a = 0;
+        let max = 0;
         for (i = 0; i < 9; i++)
-            a = Math.max(a, Math.abs(this.coffs[i]));
-        return a;
+            max = Math.max(max, Math.abs(this.coffs[i]));
+        return max;
     }
-    /** Return the maximum absolute difference between corresponding entries */
+    /** Return the maximum absolute difference between corresponding entries of `this` and `other` */
     maxDiff(other) {
         let i = 0;
-        let a = 0;
+        let max = 0;
         for (i = 0; i < 9; i++)
-            a = Math.max(a, Math.abs(this.coffs[i] - other.coffs[i]));
-        return a;
+            max = Math.max(max, Math.abs(this.coffs[i] - other.coffs[i]));
+        return max;
     }
     /** Test if the matrix is (very near to) an identity */
     get isIdentity() {
@@ -2179,25 +2345,6 @@ export class Matrix3d {
         const product = this.multiplyMatrixMatrixTranspose(this);
         return product.isIdentity;
     }
-    /** create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).
-     * vectorA is placed in the first column of the axis order.
-     * vectorB is projected perpendicular to vectorA within their plane and placed in the second column.
-     */
-    static createRigidFromColumns(vectorA, vectorB, axisOrder, result) {
-        const vectorA1 = vectorA.normalize();
-        if (vectorA1) {
-            const vectorC1 = vectorA1.unitCrossProduct(vectorB);
-            if (vectorC1) {
-                const vectorB1 = vectorC1.unitCrossProduct(vectorA);
-                if (vectorB1) {
-                    const retVal = Matrix3d.createShuffledColumns(vectorA1, vectorB1, vectorC1, axisOrder, result);
-                    retVal.setupInverseTranspose();
-                    return retVal;
-                }
-            }
-        }
-        return undefined;
-    }
     /** Adjust the matrix in place so that:
      * * columns are perpendicular and have unit length
      * * transpose equals inverse
@@ -2238,8 +2385,8 @@ export class Matrix3d {
         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.
+     * **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.
      */
     static createFromQuaternion(quat) {
         const qqx = quat.x * quat.x;
@@ -2258,8 +2405,8 @@ export class Matrix3d {
     }
     /** 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.
+     * **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.
      */
     toQuaternion() {
         const result = Point4d.createZero();
@@ -2313,9 +2460,9 @@ export class Matrix3d {
 }
 /** Control flag for whether this class uses cached inverse of matrices. */
 Matrix3d.useCachedInverse = true; // cached inverse can be suppressed for testing.
-/** total number of times a cached inverse was used to avoid recompute */
+/** Total number of times a cached inverse was used to avoid recompute */
 Matrix3d.numUseCache = 0;
-/** total number of times a cached inverse was computed. */
+/** Total number of times a cached inverse was computed. */
 Matrix3d.numComputeCache = 0;
 Matrix3d._productBuffer = new Float64Array(9);
 //# sourceMappingURL=Matrix3d.js.map