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

package/lib/cjs/geometry3d/Matrix3d.d.ts

@@ -33,54 +33,60 @@ export declare class PackedMatrix3dOps {
      */
     static loadMatrix(dest: Float64Array, a00: number, a01: number, a02: number, a10: number, a11: number, a12: number, a20: number, a21: number, a22: number): void;
     /**
-     * * 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.
      */
     static multiplyMatrixMatrix(a: Float64Array, b: Float64Array, result?: Float64Array): Float64Array;
     /**
-     * * 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.
      */
     static multiplyMatrixMatrixTranspose(a: Float64Array, b: Float64Array, result?: Float64Array): Float64Array;
     /**
-     * * 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.
      */
     static multiplyMatrixTransposeMatrix(a: Float64Array, b: Float64Array, result?: Float64Array): Float64Array;
-    /** transpose 3x3 coefficients in place */
+    /** Transpose 3x3 matrix `a` in place */
     static transposeInPlace(a: Float64Array): void;
-    /** 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: Float64Array, dest?: Float64Array): Float64Array;
-    /** transpose 3x3 coefficients in place */
+    /** Copy matrix `a` entries into `dest` */
     static copy(a: Float64Array, dest: Float64Array): Float64Array;
 }
 /** 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 declare enum 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.
      */
     unknown = 0,
-    /** An inverse was computed and stored as the `inverseCoffs` */
+    /**
+     * An inverse was computed and stored as the `inverseCoffs`
+     */
     inverseStored = 1,
     /**
-     * * 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.
      */
     singular = 2
 }
 /** 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}
@@ -92,42 +98,43 @@ export declare enum 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 declare class Matrix3d implements BeJSONFunctions {
     /** Control flag for whether this class uses cached inverse of matrices. */
     static useCachedInverse: boolean;
-    /** total number of times a cached inverse was used to avoid recompute */
+    /** Total number of times a cached inverse was used to avoid recompute */
     static numUseCache: number;
-    /** total number of times a cached inverse was computed. */
+    /** Total number of times a cached inverse was computed. */
     static numComputeCache: number;
-    /** Matrix contents as a flat array of numbers in row-major order.
+    /**
+     * Matrix contents as a flat array of numbers in row-major order.
      * ```
      * equation
      * \mxy{B}
      * \mij{B}
      * ```
-     * * DO NOT directly modify this array.  It will destroy safety of the cached inverse state.
+     * * DO NOT directly modify this array. It will destroy safety of the cached inverse state.
      */
     coffs: Float64Array;
-    /** matrix inverse contents.
-     * * DO NOT directly modify this array.  It will destroy integrity of the cached inverse state.
+    /**
+     * Matrix inverse contents.
      * ```
      * equation
      * \mxy{A}
      * ```
-     *
-     *
+     * * DO NOT directly modify this array. It will destroy integrity of the cached inverse state.
      */
     inverseCoffs: Float64Array | undefined;
-    /** indicates if inverse is unknown, available, or known singular */
+    /** Indicates if inverse is unknown, available, or known singular */
     inverseState: InverseMatrixState;
     private static _identity;
     /** The identity Matrix3d. Value is frozen and cannot be modified. */
@@ -135,40 +142,61 @@ export declare class Matrix3d implements BeJSONFunctions {
     /** Freeze this Matrix3d. */
     freeze(): Readonly<this>;
     /**
-     *
-     * @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?: Float64Array);
-    /** 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(): Matrix3dProps;
-    /** 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?: Matrix3dProps | Matrix3d): void;
-    /** Return a new Matrix3d constructed from contents of the json value. Se `setFromJSON` for layout rules */
+    /** Return a new Matrix3d constructed from contents of the json value. See `setFromJSON` for layout rules */
     static fromJSON(json?: Matrix3dProps): Matrix3d;
-    /** 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: Matrix3d, tol?: number): boolean;
-    /** 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
      */
-    isAlmostEqualAllowZRotation(other: Matrix3d, tol?: number): boolean;
     isAlmostEqualColumn(columnIndex: AxisIndex, other: Matrix3d, tol?: number): boolean;
+    /**
+     * 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: AxisIndex, ax: number, ay: number, az: number, tol?: number): boolean;
+    /**
+     * 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: Matrix3d, tol?: number): boolean;
     /** Test for exact (bitwise) equality with other. */
     isExactEqual(other: Matrix3d): boolean;
     /** test if all entries in the z row and column are exact 001, i.e. the matrix only acts in 2d */
     get isXY(): boolean;
+    /**
+     * 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.
+     */
     private static _create;
-    /** 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.
+    /**
+     * 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}
@@ -186,7 +214,7 @@ export declare class Matrix3d implements BeJSONFunctions {
     static createRowValues(axx: number, axy: number, axz: number, ayx: number, ayy: number, ayz: number, azx: number, azy: number, azz: number, result?: Matrix3d): 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.
@@ -194,16 +222,24 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     static createCapture(coffs: Float64Array, inverseCoffs?: Float64Array): Matrix3d;
     /**
-     * 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
-     */
-    static createColumnsInAxisOrder(axisOrder: AxisOrder, columnA: Vector3d, columnB: Vector3d, columnC: Vector3d | undefined, result?: Matrix3d): Matrix3d;
+     * @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: AxisOrder, columnA: Vector3d | undefined, columnB: Vector3d | undefined, columnC: Vector3d | undefined, result?: Matrix3d): Matrix3d;
+    /**
+   * Copy the transpose of the coffs to the inverseCoffs.
+   * * Mark the matrix as inverseStored.
+   */
+    private setupInverseTranspose;
     /**
-     *  set all entries in the matrix from call parameters appearing in row-major order.
+     * 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
@@ -219,38 +255,47 @@ export declare class Matrix3d implements BeJSONFunctions {
     setIdentity(): void;
     /** Set the matrix to all zeros. */
     setZero(): void;
-    /** copy contents from another matrix. */
+    /** Copy contents from another matrix. */
     setFrom(other: Matrix3d | undefined): void;
-    /** 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?: Matrix3d): Matrix3d;
-    /** 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(): Matrix3d;
-    /** 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}
      * ```
      *
      */
     static createIdentity(result?: Matrix3d): Matrix3d;
     /**
-     * Create a matrix with uniform scale factors.
-     * For scale factor _s_,
+     * 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}
+     * ```
+     */
+    static createScale(scaleFactorX: number, scaleFactorY: number, scaleFactorZ: number, result?: Matrix3d): Matrix3d;
+    /**
+     * 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}
@@ -258,96 +303,208 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     static createUniformScale(scaleFactor: number): Matrix3d;
     /**
-     * Construct a rigid matrix using createPerpendicularVectorFavorXYPlane to generate a vector perpendicular to vectorA.
-     * *
+     * 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 createRigidHeadsUp(vectorA: Vector3d, axisOrder?: AxisOrder, result?: Matrix3d): Matrix3d;
+    static createPerpendicularVectorFavorXYPlane(vectorA: Vector3d, result?: Vector3d): Vector3d;
     /**
-     * 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.
+     * 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 createPerpendicularVectorFavorXYPlane(vector: Vector3d, result?: Vector3d): Vector3d;
+    static createPerpendicularVectorFavorPlaneContainingZ(vectorA: Vector3d, result?: Vector3d): Vector3d;
     /**
-     * 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.
+     * 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 createPerpendicularVectorFavorPlaneContainingZ(vector: Vector3d, result?: Vector3d): Vector3d;
-    /** 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}
-     * ```
+    static createShuffledColumns(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d;
+    /**
+     * 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 createScale(scaleFactorX: number, scaleFactorY: number, scaleFactorZ: number, result?: Matrix3d): Matrix3d;
-    /** return a rotation of specified angle around an axis */
+    static createRigidFromColumns(vectorA: Vector3d, vectorB: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d | 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: Vector3d, axisOrder?: AxisOrder, result?: Matrix3d): Matrix3d;
+    /** Return the matrix for rotation of `angle` around desired `axis` */
     static createRotationAroundVector(axis: Vector3d, angle: Angle, result?: Matrix3d): Matrix3d | 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: AxisIndex, angle: Angle, result?: Matrix3d): Matrix3d;
+    /**
+     * 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
+     */
+    private applyGivensRowOp;
+    /**
+     * 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: number, j: number, c: number, s: number): void;
+    /**
+     * 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: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Matrix3d;
+    /** 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: XAndY, u: number, vectorV: XAndY, v: number, vectorW: XAndY, w: number, result?: Matrix3d): Matrix3d;
     /** 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: Vector3d, upVector: Vector3d, leftNoneRight?: number, topNoneBottom?: number): Matrix3d | 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: StandardViewIndex, invert?: boolean, result?: Matrix3d): Matrix3d;
+    /**
+     * 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)
+     */
+    private applyFastSymmetricJacobiUpdate;
+    /**
+     * 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: Matrix3d, lambda: Vector3d): boolean;
     /**
      * 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(): {
         axis: Vector3d;
         angle: Angle;
         ok: boolean;
     };
+    /** Rotate so columns i and j become perpendicular */
+    private applyJacobiColumnRotation;
     /**
-     * Returns a matrix that rotates from vectorA to vectorB.
+     * Factor this as a product C * U where C has mutually perpendicular columns and
+     * U is orthogonal.
+     * @param matrixC (allocate by caller, computed here)
+     * @param matrixU (allocate by caller, computed here)
      */
-    static createRotationVectorToVector(vectorA: Vector3d, vectorB: Vector3d, result?: Matrix3d): Matrix3d | undefined;
+    factorPerpendicularColumns(matrixC: Matrix3d, matrixU: Matrix3d): boolean;
+    /**
+     * Factor this matrix M as a product M = V * D * U where V and U are orthogonal, and D is diagonal (scale matrix).
+     * @param matrixV left orthogonal factor (allocate by caller, computed here)
+     * @param scale diagonal entries of D (allocate by caller, computed here)
+     * @param matrixU right orthogonal factor (allocate by caller, computed here)
+     */
+    factorOrthogonalScaleOrthogonal(matrixV: Matrix3d, scale: Point3d, matrixU: Matrix3d): boolean;
+    /** Apply a jacobi step to lambda which evolves towards diagonal. */
+    private applySymmetricJacobi;
+    /**
+     * 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: Matrix3d, lambda: Vector3d): boolean;
     /**
      * Return a matrix that rotates a fraction of the angular sweep from vectorA to vectorB.
      * @param vectorA initial vector position
-     * @param fraction fractional rotation.  1.0 is "all the way"
+     * @param fraction fractional rotation (1 means rotate all the way)
      * @param vectorB final vector position
      * @param result optional result matrix.
      */
     static createPartialRotationVectorToVector(vectorA: Vector3d, fraction: number, vectorB: Vector3d, result?: Matrix3d): Matrix3d | undefined;
+    /** Returns a matrix that rotates from vectorA to vectorB. */
+    static createRotationVectorToVector(vectorA: Vector3d, vectorB: Vector3d, result?: Matrix3d): Matrix3d | undefined;
     /** Create a 90 degree rotation around a principal axis */
     static create90DegreeRotationAroundAxis(axisIndex: number): Matrix3d;
     /** Return (a copy of) the X column */
     columnX(result?: Vector3d): Vector3d;
-    /** Return (a copy of)the Y column */
+    /** Return (a copy of) the Y column */
     columnY(result?: Vector3d): Vector3d;
-    /** Return (a copy of)the Z column */
+    /** Return (a copy of) the Z column */
     columnZ(result?: Vector3d): Vector3d;
     /** Return the X column magnitude squared */
     columnXMagnitudeSquared(): number;
@@ -363,18 +520,17 @@ export declare class Matrix3d implements BeJSONFunctions {
     columnZMagnitude(): number;
     /** Return magnitude of columnX cross columnY. */
     columnXYCrossProductMagnitude(): number;
-    /** Return the X row magnitude d */
+    /** Return the X row magnitude */
     rowXMagnitude(): number;
     /** Return the Y row magnitude  */
     rowYMagnitude(): number;
     /** Return the Z row magnitude  */
     rowZMagnitude(): number;
     /** Return the dot product of column X with column Y */
-    /** Return the dot product of column X with column Y */
     columnXDotColumnY(): number;
     /**
      * Dot product of an indexed column with a vector given as x,y,z
-     * @param columnIndex index of column.  Must be 0,1,2
+     * @param columnIndex index of column. Must be 0,1,2.
      * @param x x component of vector
      * @param y y component of vector
      * @param z z component of vector
@@ -404,133 +560,67 @@ export declare class Matrix3d implements BeJSONFunctions {
     dotRowYXYZ(x: number, y: number, z: number): number;
     /** Return the dot product of the x,y,z with the Z row. */
     dotRowZXYZ(x: number, y: number, z: number): number;
-    /** Return the (vector) cross product of the Z column with the vector parameter. */
+    /** Return the cross product of the Z column with the vector parameter. */
     columnZCrossVector(vector: XYZ, result?: Vector3d): Vector3d;
-    /**
-     * 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
-     */
-    private applyGivensRowOp;
-    /**
-     * 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: number, j: number, c: number, s: number): void;
-    /**
-     * 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: number, y: number, z: number, result?: Matrix3d): Matrix3d;
-    /** Rotate so columns i and j become perpendicular */
-    private applyJacobiColumnRotation;
-    /**
-     * Factor this as a product C * U where C has mutually perpendicular columns and
-     * U is orthogonal.
-     * @param matrixC (allocate by caller, computed here)
-     * @param matrixU (allocate by caller, computed here)
-     */
-    factorPerpendicularColumns(matrixC: Matrix3d, matrixU: Matrix3d): boolean;
-    /**
-     * Factor this matrix M as a product M = V * D * U where V and U are orthogonal, and D is diagonal (scale matrix).
-     * @param matrixV left orthogonal factor (allocate by caller, computed here)
-     * @param scale diagonal entries of D (allocate by caller, computed here)
-     * @param matrixU right orthogonal factor (allocate by caller, computed here)
-     */
-    factorOrthogonalScaleOrthogonal(matrixV: Matrix3d, scale: Point3d, matrixU: Matrix3d): boolean;
-    /** Apply a jacobi step to lambda which evolves towards diagonal. */
-    private applySymmetricJacobi;
-    /**
-     * 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: Matrix3d, lambda: Vector3d): boolean;
-    /** Apply (in place a jacobi update that zeros out this.at(i,j).
-     *
-     */
-    private applyFastSymmetricJacobiUpdate;
-    /**
-     * Factor this (symmetrized) as a product U * lambda * UT where U is orthogonal, lambda is diagonal.
-     * The upper triangle is mirrored to lower triangle to enforce symmetry.
-     * @param matrixC (allocate by caller, computed here)
-     * @param factor  (allocate by caller, computed here)
-     */
-    fastSymmetricEigenvalues(leftEigenvectors: Matrix3d, lambda: Vector3d): boolean;
-    /**
-     * 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: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Matrix3d;
-    /** 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: XAndY, u: number, vectorV: XAndY, v: number, vectorW: XAndY, w: number, result?: Matrix3d): Matrix3d;
-    /** Install data from xyz parts of Point4d  (w part of Point4d ignored) */
+    /** Set data from xyz parts of Point4d  (w part of Point4d ignored) */
     setColumnsPoint4dXYZ(vectorU: Point4d, vectorV: Point4d, vectorW: Point4d): void;
     /**
-     * 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: number, value: Vector3d | undefined): void;
-    /** Set all columns of the matrix. Any undefined vector is zeros. */
-    setColumns(vectorX: Vector3d | undefined, vectorY: Vector3d | undefined, vectorZ?: Vector3d | undefined): void;
     /**
-     * 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 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: Vector3d | undefined, vectorY: Vector3d | undefined, vectorZ?: Vector3d): void;
+    /**
+     * 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: number, value: Vector3d): void;
-    /** 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: number, result?: Vector3d): Vector3d;
-    /** 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: number, result?: Vector3d): Vector3d;
-    /** Create a matrix from column vectors, shuffled into place per AxisTriple */
-    static createShuffledColumns(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d;
-    /** 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}
      * ```
      */
     static createRows(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Matrix3d;
-    /** 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: Vector3d, scale: number, result?: Matrix3d): 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}
@@ -538,54 +628,67 @@ export declare class Matrix3d implements BeJSONFunctions {
      * @return the vector result
      */
     multiplyVector(vectorU: XYAndZ, result?: Vector3d): Vector3d;
-    /** 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: XYZ[]): void;
-    /** compute `origin - matrix * vector` */
+    /** Compute `origin - matrix * vector` */
     static xyzMinusMatrixTimesXYZ(origin: XYAndZ, matrix: Matrix3d, vector: XYAndZ, result?: Point3d): Point3d;
-    /** 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: XAndY, matrix: Matrix3d, vector: XAndY, result?: Point2d): Point2d;
-    /** 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: XYZ, matrix: Matrix3d, vector: XYAndZ, result?: Point3d): Point3d;
-    /** 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: XYZ, matrix: Matrix3d, vector: WritableXYAndZ): void;
-    /** 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: XYZ, matrix: Matrix3d, x: number, y: number, z: number, result?: Point3d): Point3d;
     /**
      * 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: XYZ, matrix: Matrix3d, x: number, y: number, z: number, w: number, result?: Point4d): Point4d;
     /**
      * 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: XYZ, matrix: Matrix3d, x: number, y: number, z: number, w: number, result?: Float64Array): Float64Array;
     /**
-     * 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: XYZ, matrix: Matrix3d, x: number, y: number, z: number, result?: Float64Array): Float64Array;
     /**
@@ -713,10 +816,14 @@ export declare class Matrix3d implements BeJSONFunctions {
      * @param result optional preallocated result to reuse.
      */
     multiplyMatrixTransform(other: Transform, result?: Transform): Transform;
-    /** 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?: Matrix3d): Matrix3d;
-    /** transpose this matrix in place.
-     *
+    /**
+     * Transpose this matrix in place.
      */
     transposeInPlace(): void;
     /** return the inverse matrix.
@@ -725,10 +832,6 @@ export declare class Matrix3d implements BeJSONFunctions {
      * * Hence explicitly constructing this new inverse object is rarely necessary.
      */
     inverse(result?: Matrix3d): Matrix3d | undefined;
-    /** copy the transpose of the coffs to the inverseCoffs.
-     * * mark the matrix as inverseStored.
-     */
-    private setupInverseTranspose;
     private static indexedRowCrossProduct;
     private indexedColumnCrossProductInPlace;
     /** Form cross products among columns in axisOrder.
@@ -759,8 +862,10 @@ export declare class Matrix3d implements BeJSONFunctions {
      * Mark this matrix as singular.
      */
     markSingular(): void;
-    /** 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.
      */
     private createInverseCoffsWithZeros;
     /** compute the inverse of this Matrix3d. The inverse is stored for later use.
@@ -779,7 +884,7 @@ export declare class Matrix3d implements BeJSONFunctions {
      * @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: number, scaleY: number, scaleZ: number, result?: Matrix3d): Matrix3d;
     /** Scale the columns of this Matrix3d.
@@ -792,13 +897,13 @@ export declare class Matrix3d implements BeJSONFunctions {
      * @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: number, scaleY: number, scaleZ: number, result?: Matrix3d): 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: Matrix3d, scale: number): void;
     /**
@@ -819,10 +924,25 @@ export declare class Matrix3d implements BeJSONFunctions {
     addScaledOuterProductInPlace(vectorU: Vector3d, vectorV: Vector3d, scale: number): void;
     /** 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: number, result?: Matrix3d): Matrix3d;
+    /**
+     * 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: number, y: number, z: number, result?: Matrix3d): Matrix3d;
     /** Return the determinant of this matrix. */
     determinant(): number;
     /** Return an estimate of how independent the columns are.  Near zero is bad. Near 1 is good
@@ -836,7 +956,7 @@ export declare class Matrix3d implements BeJSONFunctions {
     sumDiagonal(): number;
     /** Return the Maximum absolute value of any single entry */
     maxAbs(): number;
-    /** Return the maximum absolute difference between corresponding entries */
+    /** Return the maximum absolute difference between corresponding entries of `this` and `other` */
     maxDiff(other: Matrix3d): number;
     /** Test if the matrix is (very near to) an identity */
     get isIdentity(): boolean;
@@ -868,11 +988,6 @@ export declare class Matrix3d implements BeJSONFunctions {
     get isSignedPermutation(): boolean;
     /** Test if all rows and columns are length 1 and are perpendicular to each other.  (I.e. the matrix is either a pure rotation with uniform scale factor of 1 or -1) */
     testPerpendicularUnitRowsAndColumns(): boolean;
-    /** 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: Vector3d, vectorB: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d | undefined;
     /** Adjust the matrix in place so that:
      * * columns are perpendicular and have unit length
      * * transpose equals inverse
@@ -888,14 +1003,14 @@ export declare class Matrix3d implements BeJSONFunctions {
     static createRigidFromMatrix3d(source: Matrix3d, axisOrder?: AxisOrder, result?: Matrix3d): Matrix3d | undefined;
     private static computeQuatTerm;
     /** 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: Point4d): 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(): Point4d;
 }