## Matrix3d Class

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 9 entries are stored in row-major order in the coffs array.
• 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.
• constructions method that are able to determine 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.

### Methods

Name Description
constructor(coffs?: Float64Array):
addScaledInPlace(other: Matrix3d, scale: number): void add scaled values from other Matrix3d to this Matrix3d
addScaledOuterProductInPlace(vectorU: Vector3d, vectorV: Vector3d, scale: number): void add scaled values from other Matrix3d to this Matrix3d
applyGivensColumnOp(i: number, j: number, c: number, s: number): void Replace current columns Ui Uj with (cUi - sUj) and (cUj + sUi)
This is used in compute intensive inner loops -- there is no
checking for i,j being 0,1,2

at(row: number, column: number): number return the entry at specific row and column
axisOrderCrossProductsInPlace(axisOrder: AxisOrder): void Form cross products among axes in axisOrder.
clone(result?: Matrix3d): return a clone of this matrix.
columnX(result?: Vector3d): Return (a copy of) the X column
columnXDotColumnY(): number Return the dot product of column X with column Y
columnXMagnitude(): number Return the X column magnitude
columnXMagnitudeSquared(): number Return the X column magnitude squared
columnXYCrossProductMagnitude(): number Return magnitude of columnX cross columnY.
columnY(result?: Vector3d): Return (a copy of)the Y column
columnYMagnitude(): number Return the Y column magnitude
columnYMagnitudeSquared(): number Return the Y column magnitude squared
columnZ(result?: Vector3d): Return (a copy of)the Z column
columnZCrossVector(vector: XYZ, result?: Vector3d): Return the (vector) cross product of the Z column with the vector parameter.
columnZMagnitude(): number Return the Z column magnitude
columnZMagnitudeSquared(): number Return the Z column magnitude squared
computeCachedInverse(useCacheIfAvailable: boolean): boolean compute the inverse of this Matrix3d.
conditionNumber(): number Return an estimate of how independent the columns are.
determinant(): number Return the determinant of this matrix.
dotColumnX(vector: XYZ): number Return the dot product of the vector parameter with the X column.
dotColumnY(vector: XYZ): number Return the dot product of the vector parameter with the Y column.
dotColumnZ(vector: XYZ): number Return the dot product of the vector parameter with the Z column.
dotRowX(vector: XYZ): number Return the dot product of the vector parameter with the X row.
dotRowXXYZ(x: number, y: number, z: number): number Return the dot product of the x,y,z with the X row.
dotRowY(vector: XYZ): number Return the dot product of the vector parameter with the Y row.
dotRowYXYZ(x: number, y: number, z: number): number Return the dot product of the x,y,z with the Y row.
dotRowZ(vector: XYZ): number Return the dot product of the vector parameter with the Z row.
dotRowZXYZ(x: number, y: number, z: number): number Return the dot product of the x,y,z with the Z row.
factorPerpendicularColumns(matrixC: Matrix3d, matrixU: Matrix3d): boolean Factor this as a product C * U where C has mutually perpendicular columns and
U is orthogonal.

factorRigidWithSignedScale(): object | undefined Test if all rows and columns are perpendicular to each other and have equal length.
fastSymmetricEigenvalues(leftEigenvectors: Matrix3d, lambda: Vector3d): boolean Factor this (symmetrized) as a product U lambda UT where U is orthogonal, lambda is diagonal.
freeze(): void Freeze this Matrix3d.
getAxisAndAngleOfRotation(): object Compute the (unit vector) axis and angle of rotation.
getColumn(columnIndex: number, result?: Vector3d): Return a (copy of) a column of the matrix.
getRow(columnIndex: number, result?: Vector3d): Return a (copy of) a row of the matrix.
indexedColumnWithWeight(index: number, weight: number, result?: Point4d): Get a column by index (0,1,2), packaged as a Point4d with given weight.
inverse(result?: Matrix3d): Matrix3d | undefined return the inverse matrix.
isAlmostEqual(other: Matrix3d, tol?: number): boolean Test if this Matrix3d and other are within tolerance in all numeric entries.
isExactEqual(other: Matrix3d): boolean Test for exact (bitwise) equality with other.
isRigid(allowMirror: boolean = false): boolean Test if the matrix is a pure rotation.
isSingular(): boolean Returns true if the matrix is singular (i.e.
markSingular(): void Mark this matrix as singular.
maxAbs(): number Return the Maximum absolute value of any single entry
maxDiff(other: Matrix3d): number Return the maximum absolute difference between corresponding entries
multiplyInverse(vector: Vector3d, result?: Vector3d): Vector3d | undefined Solve matrix * result = vector, i.e.
multiplyInverseTranspose(vector: Vector3d, result?: Vector3d): Vector3d | undefined Solve matrix * result = vector, i.e.
multiplyInverseXYZAsPoint3d(x: number, y: number, z: number, result?: Point3d): Point3d | undefined multiply matrixInverse [x,y,z]
Equivalent to solving matrix result = [x,y,z]
* return as a Point3d.

multiplyInverseXYZAsVector3d(x: number, y: number, z: number, result?: Vector3d): Vector3d | undefined multiply matrixInverse [x,y,z]
Equivalent to solving matrix result = [x,y,z]
* return as a Vector3d.

multiplyMatrixInverseMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined Multiply this matrix times inverse of other
@return the matrix result

multiplyMatrixMatrix(other: Matrix3d, result?: Matrix3d): Multiply two matrices.
multiplyMatrixMatrixInverse(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined Multiply this matrix times inverse of other
@return the matrix result

multiplyMatrixMatrixTranspose(other: Matrix3d, result?: Matrix3d): Matrix multiplication `this * otherTranspose`
multiplyMatrixTransform(other: Transform, result?: Transform): multiply this Matrix3d (considered as a transform with 0 translation) times other Transform.
multiplyMatrixTransposeMatrix(other: Matrix3d, result?: Matrix3d): Matrix multiplication `thisTranspose * other`
@return the matrix result

multiplyTransposeVector(vector: Vector3d, result?: Vector3d): Multiply transpose of this matrix times a vector.
multiplyTransposeVectorInPlace(xyzData: XYZ): void Multiply matrix * (x, y, z) using any 3d object given containing those members
multiplyTransposeXYZ(x: number, y: number, z: number, result?: Vector3d): Multiply the (x,y,z) * matrix, i.e.
multiplyVector(vector: XYAndZ, result?: Vector3d): Multiply the matrix * vector, i.e.
multiplyVectorArrayInPlace(data: XYZ[]): void Multiply the matrix * vector, i.e.
multiplyVectorInPlace(xyzData: XYZ): void Multiply matrix * (x, y, z) using any 3d object given containing those members
multiplyXY(x: number, y: number, result?: Vector3d): Multiply the matrix * (x,y,0), i.e.
multiplyXYZ(x: number, y: number, z: number, result?: Vector3d): Multiply the matrix * (x,y,z), i.e.
multiplyXYZtoXYZ(xyz: XYZ, result: XYZ): Multiply the matrix * xyz, place result in (required) return value.
normalizeColumnsInPlace(originalMagnitudes?: Vector3d): boolean Normalize each column in place.
normalizeRowsInPlace(originalMagnitudes?: Vector3d): boolean Normalize each row in place
originPlusMatrixTimesXY(origin: XYZ, x: number, y: number, result?: Point3d): compute `origin + this*[x,y,0]`
rowX(result?: Vector3d): Return (a copy of) the X row
rowXMagnitude(): number Return the X row magnitude d
rowY(result?: Vector3d): Return (a copy of) the Y row
rowYMagnitude(): number Return the Y row magnitude
rowZ(result?: Vector3d): Return (a copy of) the Z row
rowZMagnitude(): number Return the Z row magnitude
sameDiagonalScale(): number | undefined If the matrix is diagonal and all diagonals are within tolerance, return the first diagonal.
scale(scale: number, result?: Matrix3d): create a Matrix3d whose values are uniformly scaled from this.
scaleColumns(scaleX: number, scaleY: number, scaleZ: number, result?: Matrix3d): create a Matrix3d whose columns are scaled copies of this Matrix3d.
scaleColumnsInPlace(scaleX: number, scaleY: number, scaleZ: number): void create a Matrix3d whose columns are scaled copies of this Matrix3d.
scaleRows(scaleX: number, scaleY: number, scaleZ: number, result?: Matrix3d): create a Matrix3d whose rows are scaled copies of this Matrix3d.
setAt(row: number, column: number, value: number): void Set the entry at specific row and column
setColumn(columnIndex: number, value: Vector3d | undefined): void set entries in one column of the matrix.
setColumns(vectorX: Vector3d | undefined, vectorY: Vector3d | undefined, vectorZ?: Vector3d): void Set all columns of the matrix.
setColumnsPoint4dXYZ(vectorU: Point4d, vectorV: Point4d, vectorW: Point4d): void Install data from xyz parts of Point4d (w part of Point4d ignored)
setFrom(other: Matrix3d | undefined): void copy contents from another matrix.
setFromJSON(json?: Matrix3dProps): void copy data from various input forms to this matrix:
Another `Matrix3d`
An array of 3 arrays, each of which has the 3 numbers for a row of the matrix.

setIdentity(): void Set the matrix to an identity.
setRow(rowIndex: number, value: Vector3d): void set entries in one row of the matrix.
setRowValues(axx: number, axy: number, axz: number, ayx: number, ayy: number, ayz: number, azx: number, azy: number, azz: number): void set all entries in the matrix from call parameters appearing in row-major order.
setZero(): void Set the matrix to all zeros.
sumDiagonal(): number Return the sum of diagonal entries (also known as the trace)
sumDiagonalSquares(): number Return the sum of squares of diagonal entries
sumSkewSquares(): number Sum of squared differences between symmetric pairs
sumSquares(): number Return the sum of squares of all entries
symmetricEigenvalues(leftEigenvectors: Matrix3d, lambda: Vector3d): boolean Factor this (symmetrized) as a product U lambda UT where U is orthogonal, lambda is diagonal.
testPerpendicularUnitRowsAndColumns(): boolean Test if all rows and columns are length 1 and are perpendicular to each other.
toJSON(): 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] ]`

toQuaternion(): convert the matrix to a quaternion.
transpose(result?: Matrix3d): return the transposed matrix
transposeInPlace(): void return the transposed matrix
create90DegreeRotationAroundAxis(axisIndex: number): Static Create a 90 degree rotation around a principal axis
createCapture(coffs: Float64Array, inverseCoffs?: Float64Array): Static Create a Matrix3d with caller-supplied coefficients and optional inverse coefficients.
createColumns(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Static Create a matrix from column vectors.
createColumnsInAxisOrder(axisOrder: AxisOrder, columnA: Vector3d, columnB: Vector3d, columnC: Vector3d | undefined, result?: Matrix3d): Static create a matrix by distributing vectors to columns in one of 6 orders.
createColumnsXYW(vectorU: XAndY, uz: number, vectorV: XAndY, vz: number, vectorW: XAndY, wz: number, result?: Matrix3d): Static Create a matrix from column vectors.
createDirectionalScale(direction: Vector3d, scale: number, result?: Matrix3d): Static Create a matrix that scales along a specified direction.
createFromQuaternion(quat: Point4d): Static create a matrix from a quaternion.
createIdentity(result?: Matrix3d): Static create an identity matrix
all diagonal entries (xx,yy,zz) are one
all others are zero.

createPartialRotationVectorToVector(vectorA: Vector3d, fraction: number, vectorB: Vector3d, result?: Matrix3d): Matrix3d | undefined Static Return a matrix that rotates a fraction of the angular sweep from vectorA to vectorB.
createPerpendicularVectorFavorPlaneContainingZ(vector: Vector3d, result?: Vector3d): Static * return a vector that is perpendicular to the input direction.
createPerpendicularVectorFavorXYPlane(vector: Vector3d, result?: Vector3d): Static * return a vector that is perpendicular to the input direction.
createRigidFromColumns(vectorA: Vector3d, vectorB: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d | undefined Static create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse)
vectorA is placed in the first column of the axis order.

createRigidFromMatrix3d(source: Matrix3d, axisOrder: AxisOrder = AxisOrder.XYZ, result?: Matrix3d): Matrix3d | undefined Static create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse)
columns are taken from the source Matrix3d in order indicated by the axis order.

createRigidHeadsUp(vectorA: Vector3d, axisOrder: AxisOrder = AxisOrder.ZXY, result?: Matrix3d): Static use createHeadsUpPerpendicular to generate a vectorV perpendicular to vectorA
construct a frame using createRigidFromColumns (vectorA, vectorB, axisOrder)

createRigidViewAxesZTowardsEye(x: number, y: number, z: number, result?: Matrix3d): Static create a rigid coordinate frame with:
column z points from origin to x,y,z
column x is perpendicular and in the xy plane
* column y is perpendicular to both.

createRotationAroundAxisIndex(axisIndex: AxisIndex, angle: Angle, result?: Matrix3d): Static Returns a rotation of specified angle around an axis
createRotationAroundVector(axis: Vector3d, angle: Angle, result?: Matrix3d): Matrix3d | undefined Static return a rotation of specified angle around an axis
createRotationVectorToVector(vectorA: Vector3d, vectorB: Vector3d, result?: Matrix3d): Matrix3d | undefined Static Returns a matrix that rotates from vectorA to vectorB.
createRowValues(axx: number, axy: number, axz: number, ayx: number, ayy: number, ayz: number, azx: number, azy: number, azz: number, result?: Matrix3d): Static Returns a Matrix3d populated by numeric values given in row-major order.
createRows(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Static Create a matrix from row vectors.
createScale(scaleFactorX: number, scaleFactorY: number, scaleFactorZ: number, result?: Matrix3d): Static Create a matrix with distinct x,y,z diagonal (scale) entries
createShuffledColumns(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Static Create a matrix from column vectors, shuffled into place per AxisTriple
createStandardWorldToView(index: StandardViewIndex, invert: boolean = false, result?: Matrix3d): Static Create a rotation matrix for one of the 8 standard views.
createUniformScale(scaleFactor: number): Static Create a matrix with uniform scale factors
createViewedAxes(rightVector: Vector3d, upVector: Vector3d, leftNoneRight: number = 0, topNoneBottom: number = 0): Matrix3d | undefined Static Create a matrix with
ColumnX points in the rightVector direction
ColumnY points in in the upVectorDirection
* ColumnZ is a unit cross product.

createZero(): Static create a matrix with all zeros.
flatIndexOf(row: number, column: number): number Static convert a (row,column) index pair to the single index within flattened array of 9 numbers in row-major-order
fromJSON(json?: Matrix3dProps): Static Return a new Matrix3d constructed from contents of the json value.
xyPlusMatrixTimesXY(origin: XAndY, matrix: Matrix3d, vector: XAndY, result?: Point2d): Static compute `origin + matrix * vector` using only the xy parts of the inputs.
xyzMinusMatrixTimesXYZ(origin: XYAndZ, matrix: Matrix3d, vector: XYAndZ, result?: Point3d): Static compute `origin - matrix * vector`
xyzPlusMatrixTimesCoordinates(origin: XYZ, matrix: Matrix3d, x: number, y: number, z: number, result?: Point3d): Static compute `origin + matrix * vector` where the final vector is given as direct x,y,z coordinates
xyzPlusMatrixTimesCoordinatesToFloat64Array(origin: XYZ, matrix: Matrix3d, x: number, y: number, z: number, result?: Float64Array): Float64Array Static Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row.
xyzPlusMatrixTimesWeightedCoordinates(origin: XYZ, matrix: Matrix3d, x: number, y: number, z: number, w: number, result?: Point4d): Static Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row.
xyzPlusMatrixTimesWeightedCoordinatesToFloat64Array(origin: XYZ, matrix: Matrix3d, x: number, y: number, z: number, w: number, result?: Float64Array): Float64Array Static Treat the 3x3 matrix and origin as upper 3x4 part of a 4x4 matrix, with 0001 as the final row.
xyzPlusMatrixTimesXYZ(origin: XYZ, matrix: Matrix3d, vector: XYAndZ, result?: Point3d): Static compute `origin + matrix * vector` using all xyz parts of the inputs.
xyzPlusMatrixTimesXYZInPlace(origin: XYZ, matrix: Matrix3d, vector: WritableXYAndZ): void Static compute `origin + matrix * vector` using all xyz parts of the inputs.

### Properties

Name Type Description
coffs Float64Array Matrix contents as a flat array of numbers in row-major order.
hasCachedInverse Accessor ReadOnly boolean Test if the stored inverse is present and marked valid
identity Accessor StaticReadOnly The identity Matrix3d.
inverseCoffs Float64Array | undefined matrix inverse contents.
inverseState InverseMatrixState indicates if inverse is unknown, available, or known singular
isDiagonal Accessor ReadOnly boolean Test if the off diagonal entries are all nearly zero
isIdentity Accessor ReadOnly boolean Test if the matrix is (very near to) an identity
isSignedPermutation Accessor ReadOnly boolean Test if the matrix is shuffles and negates columns.
isUpperTriangular Accessor ReadOnly boolean Test if the below diagonal entries are all nearly zero
isXY Accessor ReadOnly boolean test if all entries in the z row and column are exact 001, i.e.
numComputeCache Static number total number of times a cached inverse was computed.
numUseCache Static number total number of times a cached inverse was used to avoid recompute
useCachedInverse Static boolean Control flag for whether this class uses cached inverse of matrices.

### Defined in

Last Updated: 08 January, 2020