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

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

@@ -136,7 +136,10 @@ export declare class Matrix3d implements BeJSONFunctions {
     inverseCoffs: Float64Array | undefined;
     /** Indicates if inverse is unknown, available, or known singular */
     inverseState: InverseMatrixState;
+    /** The identity matrix */
     private static _identity;
+    /** temporary buffer to store a matrix as a Float64Array (array of 9 floats) */
+    private static _productBuffer;
     /** The identity Matrix3d. Value is frozen and cannot be modified. */
     static get identity(): Matrix3d;
     /** Freeze this Matrix3d. */
@@ -234,9 +237,15 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     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.
-   */
+     * 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;
+    /**
+     * 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.
@@ -336,13 +345,22 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     static createRigidFromColumns(vectorA: Vector3d, vectorB: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d | undefined;
     /**
-     * Construct a rigid matrix using vectorA and its 2 perpendicular.
+     * Construct a rigid matrix (orthogonal matrix with +1 determinant) using vectorA and its 2 perpendicular.
+     * * If axisOrder is not passed then `AxisOrder = AxisOrder.ZXY` is used as default.
      * * This function internally uses createPerpendicularVectorFavorXYPlane and createRigidFromColumns.
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/2PerpendicularVectorsTo1Vector
      */
     static createRigidHeadsUp(vectorA: Vector3d, axisOrder?: AxisOrder, result?: Matrix3d): Matrix3d;
-    /** Return the matrix for rotation of `angle` around `axis` */
+    /**
+     * Return the matrix for rotation of `angle` around desired `axis`
+     * * Visualization can be found at https://www.itwinjs.org/sandbox/SaeedTorabi/CubeRotationAroundAnAxis
+     * @param axis the axis of rotation
+     * @param angle the angle of rotation
+     * @param result caller-allocated matrix (optional)
+     * @returns the `rotation matrix` or `undefined` (if axis magnitude is near zero).
+     */
     static createRotationAroundVector(axis: 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.
@@ -350,22 +368,31 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     static createRotationAroundAxisIndex(axisIndex: AxisIndex, angle: Angle, result?: Matrix3d): Matrix3d;
     /**
-   * Replace current columns Ui and Uj with (c*Ui - s*Uj) and (c*Uj + s*Ui).
-   * * There is no checking for i,j being 0,1,2.
-   * * This is used in compute intensive inner loops
-   * @param i first row index. **must be 0,1,2** (unchecked)
-   * @param j second row index. **must be 0,1,2** (unchecked)
-   * @param c fist coefficient
-   * @param s second coefficient
-   */
+     * Replace current rows Ui and Uj with (c*Ui + s*Uj) and (c*Uj - s*Ui).
+     * * There is no checking for i,j being 0,1,2.
+     * @param i first row index. **must be 0,1,2** (unchecked)
+     * @param j second row index. **must be 0,1,2** (unchecked)
+     * @param c fist coefficient
+     * @param s second coefficient
+     */
+    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}
-   * ```
-   */
+     * 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.
      * ```
@@ -374,29 +401,36 @@ export declare class Matrix3d implements BeJSONFunctions {
      * ```
      */
     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 the upVector direction
+    /**
+     * Create a matrix from "as viewed" right and up vectors.
+     * * ColumnX points in the rightVector direction.
+     * * ColumnY points in the upVector direction.
      * * ColumnZ is a unit cross product of ColumnX and ColumnY.
-     * * Optionally rotate the standard cube by 45 degrees ccw around Y to bring its left or right vertical edge to center.
-     * * Optionally rotate the standard cube by 35.264 degrees ccw around X (isometric rotation).
-     * * This is expected to be used with various principal unit vectors that are perpendicular to each other.
+     * * Optionally rotate by 45 degrees around `upVector` to bring its left or right vertical edge to center.
+     * * Optionally rotate by arctan(1/sqrt(2)) ~ 35.264 degrees around `rightVector` to bring the top or bottom
+     * horizontal edge of the view to the center (for isometric views).
+     *
+     * This is expected to be used with various principal unit vectors that are perpendicular to each other.
      * * STANDARD TOP VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitY(), 0, 0)
      * * STANDARD FRONT VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitZ(), 0, 0)
      * * STANDARD BACK VIEW: createViewedAxes(Vector3d.unitX(-1), Vector3d.unitZ(), 0, 0)
      * * STANDARD RIGHT VIEW: createViewedAxes(Vector3d.unitY(), Vector3d.unitZ(), 0, 0)
      * * STANDARD LEFT VIEW: createViewedAxes(Vector3d.unitY(-1), Vector3d.unitZ(), 0, 0)
      * * STANDARD BOTTOM VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitY(-1), 0, 0)
+     * * STANDARD ISO VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitZ(), -1, 1)
+     * * STANDARD RIGHT ISO VIEW: createViewedAxes(Vector3d.unitX(), Vector3d.unitZ(), 1, 1)
+     * * Front, right, back, left, top, and bottom standard views are views from faces of the cube
+     * and iso and right iso standard views are views from corners of the cube.
      * * Note: createViewedAxes is column-based so always returns local to world
      *
      * @param rightVector ColumnX of the returned matrix. Expected to be perpendicular to upVector.
      * @param upVector ColumnY of the returned matrix. Expected to be perpendicular to rightVector.
-     * @param leftNoneRight Specifies the ccw rotation around Y axis. Normally one of "-1", "0", and "1", where
-     * "-1" indicates rotation by 45 degrees to bring the left vertical edge to center, "0" means no rotation,
+     * @param leftNoneRight Specifies the ccw rotation around `upVector` axis. Normally one of "-1", "0", and "1",
+     * where "-1" indicates rotation by 45 degrees to bring the left vertical edge to center, "0" means no rotation,
      * and "1" indicates rotation by 45 degrees to bring the right vertical edge to center. Other numbers are
      * used as multiplier for this 45 degree rotation.
-     * @param topNoneBottom Specifies the ccw rotation around X axis. Normally one of "-1", "0", and "1", where
-     * "-1" indicates isometric rotation (35.264 degrees) to bring the bottom upward, "0" means no rotation,
+     * @param topNoneBottom Specifies the ccw rotation around `rightVector` axis. Normally one of "-1", "0", and "1",
+     * where "-1" indicates isometric rotation (35.264 degrees) to bring the bottom upward, "0" means no rotation,
      * and "1" indicates isometric rotation (35.264 degrees) to bring the top downward. Other numbers are
      * used as multiplier for the 35.264 degree rotation.
      * @returns matrix = [rightVector, upVector, rightVector cross upVector] with the applied rotations specified
@@ -408,9 +442,11 @@ export declare class Matrix3d implements BeJSONFunctions {
      * * Default is TOP view (`local X = world X`, `local Y = world Y`, `local Z = world Z`).
      * * To change view from the TOP to one of the other 7 standard views, we need to multiply "world data" to
      * the corresponding matrix1 provided by `createStandardWorldToView(index, false)` and then
-     * `matrix1.multiply(world data)` will returns "local data".
+     * `matrix1.multiply(world data)` will return "local data".
      * * To change view back to the TOP, we need to multiply "local data" to the corresponding matrix2 provided
      * by `createStandardWorldToView(index, true)` and then `matrix2.multiply(local data)` will returns "world data".
+     * * Note: No matter how you rotate the world axis, local X is always pointing right, local Y is always pointing up,
+     * and local Z is always pointing toward you.
      *
      * @param index standard view index `StandardViewIndex.Top, Bottom, Left, Right, Front, Back, Iso, RightIso`
      * @param invert if false (default), the return matrix is world to local (view) and if true, the the return
@@ -419,7 +455,60 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     static createStandardWorldToView(index: StandardViewIndex, invert?: boolean, result?: Matrix3d): Matrix3d;
     /**
-     * Compute the (unit vector) axis and angle of rotation.
+     * Apply (in place) a jacobi eigenvalue algorithm.
+     * @param i row index of zeroed member
+     * @param j column index of zeroed member
+     * @param leftEigenvectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     * @param lambda a matrix that its diagonal entries will be filled by eigenvalues and its non-diagonal elements
+     * converge to 0 (allocated by caller, computed and filled by this function).
+     */
+    private applySymmetricJacobi;
+    /**
+     * Factor `this` matrix as a product `U * lambda * UT` where `U` is an orthogonal matrix and `lambda`
+     * is a diagonal matrix.
+     *
+     * * **Note 1:** You must apply this function to a `symmetric` matrix. Otherwise, the lower triangle is ignored
+     * and the upper triangle is mirrored to the lower triangle to enforce symmetry.
+     * * **Note 2:** This function is replaced by a faster method called `fastSymmetricEigenvalues` so consider
+     * using the fast version instead.
+     * @param leftEigenvectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     * @param lambda a vector that its entries will be filled by eigenvalues of `this` Matrix3d (allocated by
+     * caller, computed and filled by this function).
+     */
+    symmetricEigenvalues(leftEigenvectors: Matrix3d, lambda: Vector3d): boolean;
+    /**
+     * Apply (in place) a jacobi eigenvalue algorithm that diagonalize `this` matrix, i.e., zeros out this.at(i,j).
+     * * During diagonalization, the upper triangle is mirrored to lower triangle to enforce symmetry.
+     * * Math details can be found at docs/learning/geometry/Matrix.md
+     * @param i row index of zeroed member.
+     * @param j column index of zeroed member.
+     * @param k other row/column index (different from i and j).
+     * @param leftEigenVectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     */
+    private applyFastSymmetricJacobi;
+    /**
+     * Factor `this` matrix as a product `U * lambda * UT` where `U` is an orthogonal matrix and `lambda`
+     * is a diagonal matrix.
+     *
+     * * **Note:** You must apply this function to a `symmetric` matrix. Otherwise, the lower triangle is ignored
+     * and the upper triangle is mirrored to the lower triangle to enforce symmetry.
+     * * Math details can be found at docs/learning/geometry/Matrix.md
+     * @param leftEigenvectors a matrix that its columns will be filled by the left eigenvectors of `this` Matrix3d
+     * (allocated by caller, computed and filled by this function). Note that columns of leftEigenVectors will be
+     * mutually perpendicular because `this` matrix is symmetric.
+     * @param lambda a vector that its entries will be filled by eigenvalues of `this` Matrix3d (allocated by
+     * caller, computed and filled by this function).
+     */
+    fastSymmetricEigenvalues(leftEigenvectors: Matrix3d, lambda: Vector3d): boolean;
+    /**
+     * Compute the (unit vector) axis and angle for the rotation generated by `this` Matrix3d.
+     * * Math details can be found at docs/learning/geometry/Angle.md
      * @returns Returns axis and angle of rotation with result.ok === true when the conversion succeeded.
      */
     getAxisAndAngleOfRotation(): {
@@ -428,24 +517,53 @@ export declare class Matrix3d implements BeJSONFunctions {
         ok: boolean;
     };
     /**
-     * Returns a matrix that rotates from vectorA to vectorB.
+     * Rotate columns i and j of `this` matrix to make them perpendicular using the angle that zero-out
+     * `thisTranspose * this`.
+     * @param i row index of zeroed member.
+     * @param j column index of zeroed member.
+     * @param matrixU a matrix that its columns will be filled by the right eigenvectors of `thisTranspose * this`
+     * (allocated by caller, computed and filled by this function). Note that columns of matrixU will be mutually
+     *  perpendicular because `thisTranspose * this` matrix is symmetric.
      */
-    static createRotationVectorToVector(vectorA: Vector3d, vectorB: Vector3d, result?: Matrix3d): Matrix3d | undefined;
+    private applyJacobiColumnRotation;
+    /**
+     * Factor `this` matrix as a product `VD * U` where `VD` has mutually perpendicular columns and `U` is orthogonal.
+     * @param matrixVD a matrix that its columns will be filled by rotating columns of `this` to make them mutually
+     * perpendicular (allocated by caller, computed and filled by this function).
+     * @param matrixU a matrix that its columns will be filled by the right eigenvectors of `thisTranspose * this`
+     * (allocated by caller, computed and filled by this function). Note that columns of matrixU will be mutually
+     *  perpendicular because `thisTranspose * this` matrix is symmetric.
+     */
+    factorPerpendicularColumns(matrixVD: Matrix3d, matrixU: Matrix3d): boolean;
+    /**
+     * Factor `this` matrix as a product `V * D * U` where `V` and `U` are orthogonal and `D` is diagonal with
+     * positive entries.
+     * * This is formally known as the `Singular Value Decomposition` or `SVD`.
+     * @param matrixV an orthogonal matrix that its columns will be filled by the left eigenvectors of
+     * `thisTranspose * this` (allocated by caller, computed and filled by this function).
+     * @param scale singular values of `this` (allocated by caller, computed and filled by this function).
+     * The singular values in the `scale` are non-negative and decreasing.
+     * @param matrixU an orthogonal matrix that its columns will be filled by the right eigenvectors of
+     * `thisTranspose * this` (allocated by caller, computed and filled by this function).
+     */
+    factorOrthogonalScaleOrthogonal(matrixV: Matrix3d, scale: Point3d, matrixU: Matrix3d): 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;
@@ -461,18 +579,21 @@ 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;
+    /** Return the dot product of column X with column Z */
+    columnXDotColumnZ(): number;
+    /** Return the dot product of column Y with column Z */
+    columnYDotColumnZ(): 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
@@ -502,59 +623,9 @@ 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;
-    private applyGivensRowOp;
-    /**
-     * 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;
-    /** 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.
@@ -562,40 +633,58 @@ export declare class Matrix3d implements BeJSONFunctions {
      * @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 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.}
      * ```
+     * * Visualization can be found at itwinjs.org/sandbox/SaeedTorabi/DirectionalScale
      */
     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}
@@ -603,58 +692,71 @@ 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;
     /**
-     * Multiply transpose of this matrix times a vector.
+     * Multiply the transpose matrix times a vector.
      * * This produces the same x,y,z as treating the vector as a row on the left of the (un-transposed) matrix.
      * ```
      * equation
@@ -663,161 +765,215 @@ export declare class Matrix3d implements BeJSONFunctions {
      * \text{Treating U as a row to the left of untransposed matrix\: return row}&\rowSubXYZ{V}&=&\rowSubXYZ{U}\matrixXY{A}
      * \end{matrix}
      * ```
-     * @return the vector result
+     * @param result the vector result (optional)
      */
     multiplyTransposeVector(vector: Vector3d, result?: Vector3d): Vector3d;
-    /** Multiply the matrix * (x,y,z), i.e. the vector (x,y,z) is a column vector on the right.
-     * @return the vector result
+    /**
+     * Multiply the matrix * [x,y,z], i.e. the vector [x,y,z] is a column vector on the right.
+     * @param result the vector result (optional)
      */
     multiplyXYZ(x: number, y: number, z: number, result?: Vector3d): Vector3d;
-    /** Multiply the matrix * xyz, place result in (required) return value.
-     *   @param xyz right side
-     *   @param result result.
+    /**
+     * Multiply the matrix * xyz, place result in (required) return value.
+     * @param xyz right side
+     * @param result the result.
      */
     multiplyXYZtoXYZ(xyz: XYZ, result: XYZ): XYZ;
-    /** Multiply the matrix * (x,y,0), i.e. the vector (x,y,z) is a column vector on the right.
-     *   @return the vector result
+    /**
+     * Multiply the matrix * [x,y,0], i.e. the vector [x,y,0] is a column vector on the right.
+     * @param result the vector result (optional)
      */
     multiplyXY(x: number, y: number, result?: Vector3d): Vector3d;
-    /** compute `origin + this*[x,y,0]`  */
+    /**
+     * Compute origin + the matrix * [x,y,0].
+     * @param result the Point3d result (optional)
+     */
     originPlusMatrixTimesXY(origin: XYZ, x: number, y: number, result?: Point3d): Point3d;
-    /** Multiply matrix * (x, y, z) using any 3d object given containing those members */
+    /**
+     * Multiply the matrix * (x,y,z) in place, i.e. the vector (x,y,z) is a column vector on the right and
+     * the multiplication updates the vector values.
+     * @param xyzData the vector data.
+     */
     multiplyVectorInPlace(xyzData: XYZ): void;
-    /** Multiply the transpose matrix times column using any 3d object with x,y,z members.
-     * This is equivalent to `multiplyTransposeVector` but always returns the result directly in the input.
+    /**
+     * Multiply the transpose matrix times [x,y,z] in place, i.e. the vector [x,y,z] is a column vector on
+     * the right and the multiplication updates the vector values.
+     * * This is equivalent to `multiplyTransposeVector` but always returns the result directly in the input.
+     * @param vectorU the vector data
      */
     multiplyTransposeVectorInPlace(vectorU: XYZ): void;
-    /** Multiply the transpose matrix times column using individual numeric inputs.
-     * * This is equivalent to multiplying with the vector as a row to the left of the plain matrix.
+    /**
+     * Multiply the transpose matrix times column using individual numeric inputs.
+     * * This produces the same x,y,z as treating the vector as a row on the left of the (un-transposed) matrix.
      * ```
      * equation
      * \begin{matrix}
-     * \text{treating the input as a column } \columnXYZ{x}{y}{z}\text{ compute  }&\columnSubXYZ{V} &= &A^T \columnXYZ{x}{y}{z} \\
-     * \text{or row vector } \rowXYZ{x}{y}{z} \text{ compute }&\rowSubXYZ{V} &= &\rowXYZ{x}{y}{z} A \\
+     * \text{treating the input as a column vector } \columnXYZ{x}{y}{z}\text{ compute  }&\columnSubXYZ{V} &= &A^T \columnXYZ{x}{y}{z} \\
+     * \text{or as a row vector } \rowXYZ{x}{y}{z} \text{ compute }&\rowSubXYZ{V} &= &\rowXYZ{x}{y}{z} A \\
      * \phantom{8888}\text{and return V as a Vector3d} & & &
      * \end{matrix}
      * ````
-     * @return the vector result
+     * @param result the vector result (optional)
      */
     multiplyTransposeXYZ(x: number, y: number, z: number, result?: Vector3d): Vector3d;
-    /** Solve `matrix * result = vector`.
+    /**
+     * Solve `matrix * result = vector` for an unknown `result`.
      * * This is equivalent to multiplication `result = matrixInverse * vector`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel or zero length columns)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      */
     multiplyInverse(vector: Vector3d, result?: Vector3d): Vector3d | undefined;
-    /** Solve `matrixTranspose * result = vector`.
+    /**
+     * Solve `matrixTranspose * result = vector` for an unknown `result`.
      * * This is equivalent to multiplication `result = matrixInverseTranspose * vector`.
-     * * Result is undefined if the matrix is singular (e.g. has parallel or zero length columns)
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
      */
     multiplyInverseTranspose(vector: Vector3d, result?: Vector3d): Vector3d | undefined;
     /**
-     * multiply `matrixInverse * [x,y,z]`.
-     * *  This is equivalent to solving `matrix * result = [x,y,z]`
-     * *  return as a Vector3d, or undefined if the matrix is singular.
+     * Multiply `matrixInverse * [x,y,z]`.
+     * * This is equivalent to solving `matrix * result = [x,y,z]` for an unknown `result`.
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * @return result as a Vector3d or undefined (if the matrix is singular).
      */
     multiplyInverseXYZAsVector3d(x: number, y: number, z: number, result?: Vector3d): Vector3d | undefined;
     /**
-     * multiply `matrixInverse * [x,y,z]` and return packaged as `Point4d` with given weight.
-     * *  Equivalent to solving matrix * result = [x,y,z]
-     * *  return as a Point4d with the same weight.
-     * *  Called by Transform with x,y,z adjusted by subtraction ((xw) - w * origin.x, etc) where xw is the pre-weighted space point.
+     * Multiply `matrixInverse * [x,y,z]` and return result as `Point4d` with given weight.
+     * * Equivalent to solving `matrix * result = [x,y,z]` for an unknown `result`.
+     * * Result is `undefined` if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * @return result as a Point4d with the same weight.
      */
     multiplyInverseXYZW(x: number, y: number, z: number, w: number, result?: Point4d): Point4d | undefined;
     /**
-     * multiply `matrixInverse * [x,y,z]` and return packaged as `Point3d`.
-     * *  multiply matrixInverse * [x,y,z]
-     * *  Equivalent to solving matrix * result = [x,y,z]
-     * *  return as a Point3d.
+     * Multiply `matrixInverse * [x,y,z]` and return result as `Point3d`.
+     * * Equivalent to solving `matrix * result = [x,y,z]` for an unknown `result`.
+     * @return result as a Point3d or `undefined` (if the matrix is singular).
      */
     multiplyInverseXYZAsPoint3d(x: number, y: number, z: number, result?: Point3d): Point3d | undefined;
     /**
-     * * invoke a given matrix-matrix operation (product function) to compute this.inverseCOffs
-     * * set this.inverseCoffs
-     * * if either input cffA or coffB is undefined, set state to `InverseMatrixState.unknown` (but leave the inverseCoffs untouched)
+     * Invoke a given matrix*matrix operation to compute the inverse matrix and set this.inverseCoffs
+     * * If either input coffA or coffB is `undefined`, set state to `InverseMatrixState.unknown` but
+     * leave the inverseCoffs untouched.
+     * @param f the given matrix*matrix operation that is called by this function to compute the inverse.
+     * `f` must be a matrix*matrix operation. Otherwise, the function does not generate the inverse properly.
      */
     private finishInverseCoffs;
-    /** Multiply the instance matrix A by the input matrix B.
-     *   @return the matrix product A * B
+    /**
+     * Multiply `this` matrix times `other` matrix
+     * @return the matrix result: this*other
      */
     multiplyMatrixMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d;
-    private static _productBuffer;
-    /** Multiply this matrix times inverse of other
-     *   @return the matrix result
+    /**
+     * Multiply `this` matrix times `inverse of other` matrix
+     * @return the matrix result: this*otherInverse
      */
     multiplyMatrixMatrixInverse(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined;
-    /** Multiply this matrix times inverse of other
-     *   @return the matrix result
+    /**
+     * Multiply `inverse of this` matrix times `other` matrix
+     * @return the matrix result: thisInverse*other
      */
     multiplyMatrixInverseMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined;
-    /** Multiply `this` matrix times the transpose of `matrixB`.
+    /**
+     * Multiply `this` matrix times the transpose of `other` matrix
      * ```
      * equation
-     * \text{for instance matrix }A\text{ and other matrix }B\text{ return matrix }C{\text where }\\\matrixXY{C}=\matrixXY{A}\matrixTransposeSubXY{B}
+     * \text{for instance matrix }A\text{ and matrix }B\text{ return matrix }C{\text where }\\\matrixXY{C}=\matrixXY{A}\matrixTransposeSubXY{B}
      * ```
-     * @return the matrix result
+     * @return the matrix result: this*otherTranspose
      */
-    multiplyMatrixMatrixTranspose(matrixB: Matrix3d, result?: Matrix3d): Matrix3d;
-    /** Matrix multiplication `thisTranspose * other`.
+    multiplyMatrixMatrixTranspose(other: Matrix3d, result?: Matrix3d): Matrix3d;
+    /**
+     * Multiply the transpose of `this` matrix times `other` matrix
      * ```
      * equation
      * \matrixXY{result}=\matrixXY{\text{this}}\matrixTransposeSubXY{\text{other}}
      * ```
-     *   @return the matrix result
+     * @return the matrix result: thisTranspose*other
      */
     multiplyMatrixTransposeMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d;
-    /** multiply this Matrix3d (considered as a transform with 0 translation) times other Transform.
+    /**
+     * Multiply `this` Matrix3d (considered as a Transform with 0 translation) times `other` Transform.
      * ```
      * equation
      * \begin{matrix}
-     *    \text{This matrix }\bold{A}\text{ promoted to block transform} & \blockTransform{A}{0} \\
-     *    \text{other transform with matrix part }\bold{B}\text{ and translation }\bold{b} & \blockTransform{B}{b}\\
+     * \text{This matrix }\bold{A}\text{ promoted to block transform} & \blockTransform{A}{0} \\
+     * \text{other transform with matrix part }\bold{B}\text{ and translation }\bold{b} & \blockTransform{B}{b}\\
      * \text{product}& \blockTransform{A}{0}\blockTransform{B}{b}=\blockTransform{AB}{Ab}
      * \end{matrix}
      * ```
-     * @param other right hand Matrix3d for multiplication.
-     * @param result optional preallocated result to reuse.
+     * @param other Right hand Matrix3d for multiplication.
+     * @param result the Transform result (optional)
      */
     multiplyMatrixTransform(other: Transform, result?: Transform): Transform;
     /**
      * Return the transpose of `this` matrix.
-     * If `result` is passed as argument, then the function copies the transpose of `this` into `result`
-     * `this` is not changed unless also passed as the result, i.e., this.transpose(this) transposes `this` in place
+     * * If `result` is passed as argument, then the function copies the transpose of `this` into `result`.
+     * * `this` is not changed unless also passed as the result, i.e., `this.transpose(this)` transposes `this` in place.
      */
     transpose(result?: Matrix3d): Matrix3d;
     /**
      * Transpose this matrix in place.
      */
     transposeInPlace(): void;
-    /** return the inverse matrix.
-     * The return is undefined if the matrix is singular (has columns that are coplanar or colinear)
-     * * Note that each Matrix3d object caches its own inverse, and has methods to multiply the inverse times matrices and vectors.
-     * * Hence explicitly constructing this new inverse object is rarely necessary.
+    /**
+     * Return the inverse matrix.
+     * The return is undefined if the matrix is singular (e.g. has parallel columns or a zero magnitude column)
+     * * If `result == this`, then content of inverse of `this` matrix is copied into `this`. Otherwise, inverse
+     * of `this` is stored in `result`.
+     * * **Note:** Each Matrix3d object caches its own inverse (`this.inverseCoffs`) and has methods to multiply
+     * the inverse times matrices and vectors (e.g., `multiplyMatrixInverseMatrix`, `multiplyMatrixMatrixInverse`,
+     * `multiplyInverse`). Hence explicitly constructing this new inverse object is rarely necessary.
      */
     inverse(result?: Matrix3d): Matrix3d | undefined;
+    /**
+     * Take the dot product of a row (specified by `rowStartA`) of `coffA` and `columnStartB` of `coffB`.
+     * * **Note:** We don't validate row/column numbers. Pass 0/3/6 for row 0/1/2 and pass 0/1/2 for column 0/1/2.
+     */
+    private static rowColumnDot;
+    /**
+     * Take the cross product of 2 rows (specified by `rowStart0` and `rowStart1`) of `source` and store the result
+     * in `columnStart` of `dest`.
+     * * **Note:** We don't validate row/column numbers. Pass 0/3/6 for row 0/1/2 and pass 0/1/2 for column 0/1/2.
+     */
     private static indexedRowCrossProduct;
+    /**
+     * Take the cross product of 2 columns (i.e., `colStart0` and `colStart1`) of `this` matrix and store the
+     * result in `colStart2` of the same matrix.
+     * * **Note:** We don't validate column numbers. Pass 0/1/2 for column 0/1/2.
+     */
     private indexedColumnCrossProductInPlace;
-    /** Form cross products among columns in axisOrder.
-     * For axis order ABC,
-     * * form cross product of column A and B, store in C
+    /**
+     * Form cross products among columns in axisOrder.
+     * For axis order ABC:
+     * * form cross product of column A and B, store in C.
      * * form cross product of column C and A, store in B.
+     * * [A   B   C] ===> [A   B   AxB] ===> [A   (AxB)xA   AxB]
+     *
      * This means that in the final matrix:
-     * * column A is strictly parallel to original column A
-     * * column B is linear combination of only original A and B
-     * * column C is perpendicular to A and B of both the original and final.
-     * * original column C does not participate in the result.
+     * * first column is same as original column A.
+     * * second column is linear combination of original A and B (i.e., is in the plane of original A and B).
+     * * third column is perpendicular to first and second columns of both the original and final.
+     * * original column C is overwritten and does not participate in the result.
+     *
+     * The final matrix will have 3 orthogonal columns.
      */
     axisOrderCrossProductsInPlace(axisOrder: AxisOrder): void;
-    /** Normalize each column in place.
-     * * For false return the magnitudes are stored in the originalMagnitudes vector but no columns are altered.
-     * @returns Return true if all columns had nonzero lengths.
-     * @param originalMagnitudes optional vector to receive original column magnitudes.
-     */
-    normalizeColumnsInPlace(originalMagnitudes?: Vector3d): boolean;
-    /** Normalize each row in place */
-    normalizeRowsInPlace(originalMagnitudes?: Vector3d): boolean;
-    private static rowColumnDot;
     /**
-     * Returns true if the matrix is singular (i.e. collapses data to a plane, line, or point)
+     * Normalize each column in place.
+     * @param originalColumnMagnitudes optional vector to store original column magnitudes.
+     * @returns return true if all columns have non-zero lengths. Otherwise, return false.
+     * * If false is returned, the magnitudes are stored in the `originalColumnMagnitudes` vector but no columns
+     * are altered.
+     */
+    normalizeColumnsInPlace(originalColumnMagnitudes?: Vector3d): boolean;
+    /**
+     * Normalize each row in place.
+     * @param originalRowMagnitudes optional vector to store original row magnitudes.
+     * @returns return true if all rows have non-zero lengths. Otherwise, return false.
+     * * If false is returned, the magnitudes are stored in the `originalRowMagnitudes` vector but no rows
+     * are altered.
+     */
+    normalizeRowsInPlace(originalRowMagnitudes?: Vector3d): boolean;
+    /**
+     * Returns true if the matrix is singular.
      */
     isSingular(): boolean;
     /**
@@ -825,81 +981,112 @@ export declare class Matrix3d implements BeJSONFunctions {
      */
     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.
-     */
-    private createInverseCoffsWithZeros;
-    /** compute the inverse of this Matrix3d. The inverse is stored for later use.
-     * @returns Return true if the inverse computed.  (False if the columns collapse to a point, line or plane.)
+     * Compute the inverse of `this` Matrix3d. The inverse is stored in `this.inverseCoffs` for later use.
+     * @param useCacheIfAvailable if `true`, use the previously computed inverse if available. If `false`,
+     * recompute the inverse.
+     * @returns return `true` if the inverse is computed. Return `false` if matrix is singular.
      */
     computeCachedInverse(useCacheIfAvailable: boolean): boolean;
-    /** convert a (row,column) index pair to the single index within flattened array of 9 numbers in row-major-order  */
+    /**
+     * Convert a (row,column) index pair to the single index within flattened array of 9 numbers in row-major-order
+     * * **Note:** Out of range row/column is interpreted cyclically.
+     */
     static flatIndexOf(row: number, column: number): number;
-    /** Get a column by index (0,1,2), packaged as a Point4d with given weight.   Out of range index is interpreted cyclically.  */
+    /**
+     * Get elements of column `index` packaged as a Point4d with given `weight`.
+     * * **Note:** Out of range index is interpreted cyclically.
+     */
     indexedColumnWithWeight(index: number, weight: number, result?: Point4d): Point4d;
-    /** return the entry at specific row and column */
+    /** Return the entry at specific row and column */
     at(row: number, column: number): number;
     /** Set the entry at specific row and column */
     setAt(row: number, column: number, value: number): void;
-    /** create a Matrix3d whose columns are scaled copies of this Matrix3d.
-     * @param scaleX scale factor for column x
-     * @param scaleY scale factor for column y
-     * @param scaleZ scale factor for column z
+    /**
+     * Create a Matrix3d whose values are uniformly scaled from `this` Matrix3d.
+     * @param scale scale factor to apply.
      * @param result optional result.
+     * @returns return the scaled matrix.
+     */
+    scale(scale: number, result?: Matrix3d): Matrix3d;
+    /**
+     * Create a Matrix3d whose columns are scaled copies of `this` Matrix3d.
+     * @param scaleX scale factor for column 0
+     * @param scaleY scale factor for column 1
+     * @param scaleZ scale factor for column 2
+     * @param result optional result
      */
     scaleColumns(scaleX: number, scaleY: number, scaleZ: number, result?: Matrix3d): Matrix3d;
-    /** Scale the columns of this Matrix3d.
-     * @param scaleX scale factor for column x
-     * @param scaleY scale factor for column y
-     * @param scaleZ scale factor for column z
+    /**
+     * Scale the columns of `this` Matrix3d in place.
+     * @param scaleX scale factor for column 0
+     * @param scaleY scale factor for column 1
+     * @param scaleZ scale factor for column 2
      */
     scaleColumnsInPlace(scaleX: number, scaleY: number, scaleZ: number): void;
-    /** create a Matrix3d whose rows are scaled copies of this Matrix3d.
-     * @param scaleX scale factor for row x
-     * @param scaleY scale factor for row y
-     * @param scaleZ scale factor for row z
-     * @param result optional result.
+    /**
+     * Create a Matrix3d whose rows are scaled copies of `this` Matrix3d.
+     * @param scaleX scale factor for row 0
+     * @param scaleY scale factor for row 1
+     * @param scaleZ scale factor for row 2
+     * @param result optional result
      */
     scaleRows(scaleX: 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
+     * Scale the rows of `this` Matrix3d in place.
+     * @param scaleX scale factor for row 0
+     * @param scaleY scale factor for row 1
+     * @param scaleZ scale factor for row 2
+     */
+    scaleRowsInPlace(scaleX: number, scaleY: number, scaleZ: number): void;
+    /**
+     * Add scaled values from `other` Matrix3d to `this` Matrix3d.
+     * @param other Matrix3d with values to be added.
      * @param scale scale factor to apply to the added values.
      */
     addScaledInPlace(other: Matrix3d, scale: number): void;
     /**
-     * add scaled values from an outer product.
-     * * The scaled outer product is a "rank 1" matrix.
+     * Add scaled values from an outer product of vectors U and V.
+     * * The scaled outer product is a matrix with `rank 1` (all columns/rows are linearly dependent).
      * * This is useful in constructing mirrors and directional scales.
      * ```
      * equation
      * A += s \columnSubXYZ{U}\rowSubXYZ{V}
      * \\ \matrixXY{A} += s \begin{bmatrix}
-     * U_x * V_x & U_y * V_x & U_z * V_x \\
-     * U_x * V_y & U_y * V_y & U_z * V_y \\
-     * U_x * V_z & U_y * V_z & U_z * V_z \end{bmatrix}
+     * U_x * V_x & U_x * V_y & U_x * V_z \\
+     * U_y * V_x & U_y * V_y & U_y * V_z \\
+     * U_z * V_x & U_z * V_y & U_z * V_z \end{bmatrix}
      * ```
-     * @param other Matrix3d with values to be added
+     * @param vectorU first vector in the outer product.
+     * @param vectorV second vector in the outer product.
      * @param scale scale factor to apply to the added values.
      */
     addScaledOuterProductInPlace(vectorU: 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.
-     * @returns Return the new or repopulated matrix
+    /**
+     * Create a rigid matrix (columns and rows are unit length and pairwise perpendicular) for the given eye coordinate.
+     * * column 2 is parallel to (x,y,z).
+     * * column 0 is perpendicular to column 2 and is in the xy plane.
+     * * column 1 is perpendicular to both. It is the "up" vector on the view plane.
+     * * Multiplying the returned matrix times a local (view) vector gives the world vector.
+     * * Multiplying transpose of the returned matrix times a world vector gives the local (view) vector.
+     * @param x eye x coordinate
+     * @param y eye y coordinate
+     * @param z eye z coordinate
+     * @param result optional preallocated result
      */
-    scale(scale: number, result?: Matrix3d): Matrix3d;
-    /** Return the determinant of this matrix. */
+    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
+    /**
+     * Return an estimate of how independent the columns of `this` matrix are. Near zero is bad (i.e.,
+     * columns are almost dependent and matrix is nearly singular). Near 1 is good (i.e., columns are
+     * almost independent and matrix is invertible).
      */
     conditionNumber(): number;
     /** Return the sum of squares of all entries */
     sumSquares(): number;
     /** Return the sum of squares of diagonal entries */
     sumDiagonalSquares(): number;
-    /** Return the sum of diagonal entries (also known as the trace) */
+    /** Return the matrix `trace` (sum of diagonal entries) */
     sumDiagonal(): number;
     /** Return the Maximum absolute value of any single entry */
     maxAbs(): number;
@@ -909,38 +1096,56 @@ export declare class Matrix3d implements BeJSONFunctions {
     get isIdentity(): boolean;
     /** Test if the off diagonal entries are all nearly zero */
     get isDiagonal(): boolean;
+    /** Sum of squared differences between symmetric pairs (symmetric pairs have indices (1,3), (2,6), and (5,7).) */
+    sumSkewSquares(): number;
+    /** Test if the matrix is (very near to) symmetric */
+    isSymmetric(): boolean;
     /** Test if the stored inverse is present and marked valid */
     get hasCachedInverse(): boolean;
-    /** Test if the below diagonal entries are all nearly zero */
+    /** Test if the below diagonal entries (3,6,7) are all nearly zero */
     get isUpperTriangular(): boolean;
-    /** If the matrix is diagonal and all diagonals are within tolerance, return the first diagonal.  Otherwise return undefined.
+    /** Test if the above diagonal entries (1,2,5) are all nearly zero */
+    get isLowerTriangular(): boolean;
+    /**
+     * If the matrix is diagonal and all diagonals are almost equal, return the first diagonal (entry 0
+     * which is same as entry 4 and 8). Otherwise return `undefined`.
      */
     sameDiagonalScale(): number | undefined;
-    /** Sum of squared differences between symmetric pairs */
-    sumSkewSquares(): number;
-    /** Test if the matrix is a pure rotation.
-     * @param allowMirror whether to widen the test to return true if the matrix is orthogonal (a pure rotation or a mirror)
+    /**
+     * Test if all rows and columns are unit length and are perpendicular to each other, i.e., the matrix is either
+     * a `pure rotation` (determinant is +1) or is a `mirror` (determinant is -1).
+     * * **Note:** such a matrix is called `orthogonal` and its inverse is its transpose.
+     */
+    testPerpendicularUnitRowsAndColumns(): boolean;
+    /**
+     * Test if the matrix is a `rigid` matrix (or `pure rotation`, i.e., columns and rows are unit length and
+     * pairwise perpendicular and determinant is +1).
+     * @param allowMirror whether to widen the test to return true if the matrix is a `mirror` (determinant is -1).
     */
     isRigid(allowMirror?: boolean): boolean;
-    /** Test if all rows and columns are perpendicular to each other and have equal length.
-     * If so, the length (or its negative) is the scale factor from a set of rigid axes to these axes.
-     * * result.rigidAxes is the rigid axes (with the scale factor removed)
-     * * result.scale is the scale factor
+    /**
+     * Test if all rows and columns are perpendicular to each other and have equal length.
+     * If so, the length (or its negative) is the `scale` factor from a set of `orthonormal axes` to
+     * the set of axes created by columns of `this` matrix. Otherwise, returns `undefined`.
+     * @returns returns `{ rigidAxes, scale }` where `rigidAxes` is a Matrix3d with its columns as the rigid axes
+     * (with the scale factor removed) and `scale` is the scale factor.
+     * * Note that determinant of a rigid matrix is +1.
+     * * The context for this method is to determine if the matrix is the product a `rotation` matrix and a uniform
+     * `scale` matrix (diagonal matrix with all diagonal entries the same nonzero number).
      */
     factorRigidWithSignedScale(): {
         rigidAxes: Matrix3d;
         scale: number;
     } | undefined;
-    /** Test if the matrix is shuffles and negates columns. */
+    /** Test if `this` matrix reorders and/or negates the columns of the `identity` matrix. */
     get isSignedPermutation(): 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;
-    /** Adjust the matrix in place so that:
-     * * columns are perpendicular and have unit length
-     * * transpose equals inverse
-     * * mirroring is removed
+    /**
+     * Adjust the matrix in place to make is a `rigid` matrix so that:
+     * * columns are perpendicular and have unit length.
+     * * transpose equals inverse.
+     * * mirroring is removed.
      * @param axisOrder how to reorder the matrix columns
-     * @return whether the instance is rigid on return
+     * @return whether the adjusted matrix is `rigid` on return
      */
     makeRigid(axisOrder?: AxisOrder): boolean;
     /** Create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).
@@ -948,16 +1153,25 @@ export declare class Matrix3d implements BeJSONFunctions {
      * * Mirroring in the matrix is removed.
      */
     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.
+    /**
+     * Create a matrix from a quaternion.
+     * **WARNING:** There is frequent confusion over whether a "from quaternion" matrix is organized by
+     * rows or columns. If you find that the matrix seems to rotate by the opposite angle, transpose it.
+     *
+     * Some math details can be found at
+     * http://marc-b-reynolds.github.io/quaternions/2017/08/08/QuatRotMatrix.html
      */
     static createFromQuaternion(quat: 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.
+    /** Calculate quaternion terms used to convert matrix to a quaternion */
+    private static computeQuatTerm;
+    /**
+     * Create `this` matrix to a quaternion.
+     * **Note:** This calculation requires `this` matrix to have unit length rows and columns.
+     * **WARNING:** There is frequent confusion over whether a "from quaternion" matrix is organized by
+     * rows or columns. If you find that the matrix seems to rotate by the opposite angle, transpose it.
+     *
+     * Some math details can be found at
+     * http://marc-b-reynolds.github.io/quaternions/2017/08/08/QuatRotMatrix.html
      */
     toQuaternion(): Point4d;
 }