API Reference > geometry-core > CartesianGeometry > Matrix3d

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.

Implements

Methods

Name Description
constructor(coffs?: Float64Array): Matrix3d    
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)  
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): Matrix3d return a clone of this matrix.  
columnX(result?: Vector3d): 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): 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): Vector3d Return (a copy of)the Z column  
columnZCrossVector(vector: XYZ, result?: Vector3d): 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  
factorRigidWithSignedScale(): { rigidAxes: Matrix3d, scale: number } | 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(): { angle: Angle, axis: Vector3d, ok: boolean } Compute the (unit vector) axis and angle of rotation.  
getColumn(columnIndex: number, result?: Vector3d): Vector3d Return a (copy of) a column of the matrix.  
getRow(columnIndex: number, result?: Vector3d): Vector3d Return a (copy of) a row of the matrix.  
indexedColumnWithWeight(index: number, weight: number, result?: Point4d): 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]  
multiplyInverseXYZAsVector3d(x: number, y: number, z: number, result?: Vector3d): Vector3d | undefined * multiply matrixInverse * [x,y,z]  
multiplyInverseXYZW(x: number, y: number, z: number, w: number, result?: Point4d): Point4d | undefined * multiply matrixInverse * [x,y,z]  
multiplyMatrixInverseMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined Multiply this matrix times inverse of other  
multiplyMatrixMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d Multiply two matrices.  
multiplyMatrixMatrixInverse(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined Multiply this matrix times inverse of other  
multiplyMatrixMatrixTranspose(other: Matrix3d, result?: Matrix3d): Matrix3d Matrix multiplication this * otherTranspose  
multiplyMatrixTransform(other: Transform, result?: Transform): Transform multiply this Matrix3d (considered as a transform with 0 translation) times other Transform.  
multiplyMatrixTransposeMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d Matrix multiplication thisTranspose * other  
multiplyTransposeVector(vector: Vector3d, result?: Vector3d): 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): Vector3d Multiply the (x,y,z) * matrix, i.e.  
multiplyVector(vector: XYAndZ, result?: Vector3d): 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): Vector3d Multiply the matrix * (x,y,0), i.e.  
multiplyXYZ(x: number, y: number, z: number, result?: Vector3d): Vector3d Multiply the matrix * (x,y,z), i.e.  
multiplyXYZtoXYZ(xyz: XYZ, result: XYZ): 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): Point3d compute origin + this*[x,y,0]  
rowX(result?: Vector3d): Vector3d Return (a copy of) the X row  
rowXMagnitude(): number Return the X row magnitude d  
rowY(result?: Vector3d): Vector3d Return (a copy of) the Y row  
rowYMagnitude(): number Return the Y row magnitude  
rowZ(result?: Vector3d): 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): Matrix3d create a Matrix3d whose values are uniformly scaled from this.  
scaleColumns(scaleX: number, scaleY: number, scaleZ: number, result?: Matrix3d): 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): 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:  
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(): Matrix3dProps Return a json object containing the 9 numeric entries as a single array in row major order,  
toQuaternion(): Point4d convert the matrix to a quaternion.  
transpose(result?: Matrix3d): Matrix3d return the transposed matrix  
transposeInPlace(): void return the transposed matrix  
create90DegreeRotationAroundAxis(axisIndex: number): Matrix3d Static Create a 90 degree rotation around a principal axis  
createCapture(coffs: Float64Array, inverseCoffs?: Float64Array): Matrix3d Static Create a Matrix3d with caller-supplied coefficients and optional inverse coefficients.  
createColumns(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Matrix3d Static Create a matrix from column vectors.  
createColumnsInAxisOrder(axisOrder: AxisOrder, columnA: Vector3d, columnB: Vector3d, columnC: Vector3d | undefined, result?: Matrix3d): 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): Matrix3d Static Create a matrix from column vectors.  
createDirectionalScale(direction: Vector3d, scale: number, result?: Matrix3d): Matrix3d Static Create a matrix that scales along a specified direction.  
createFromQuaternion(quat: Point4d): Matrix3d Static create a matrix from a quaternion.  
createIdentity(result?: Matrix3d): Matrix3d Static create an identity matrix  
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): Vector3d Static * return a vector that is perpendicular to the input direction.  
createPerpendicularVectorFavorXYPlane(vector: Vector3d, result?: Vector3d): 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)  
createRigidFromMatrix3d(source: Matrix3d, axisOrder: AxisOrder = AxisOrder.XYZ, result?: Matrix3d): Matrix3d | undefined Static create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse)  
createRigidHeadsUp(vectorA: Vector3d, axisOrder: AxisOrder = AxisOrder.ZXY, result?: Matrix3d): Matrix3d Static * use createHeadsUpPerpendicular to generate a vectorV perpendicular to vectorA  
createRigidViewAxesZTowardsEye(x: number, y: number, z: number, result?: Matrix3d): Matrix3d Static create a rigid coordinate frame with:  
createRotationAroundAxisIndex(axisIndex: AxisIndex, angle: Angle, result?: Matrix3d): 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): Matrix3d Static Returns a Matrix3d populated by numeric values given in row-major order.  
createRows(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, result?: Matrix3d): Matrix3d Static Create a matrix from row vectors.  
createScale(scaleFactorX: number, scaleFactorY: number, scaleFactorZ: number, result?: Matrix3d): Matrix3d Static Create a matrix with distinct x,y,z diagonal (scale) entries  
createShuffledColumns(vectorU: Vector3d, vectorV: Vector3d, vectorW: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): Matrix3d Static Create a matrix from column vectors, shuffled into place per AxisTriple  
createStandardWorldToView(index: StandardViewIndex, invert: boolean = false, result?: Matrix3d): Matrix3d Static Create a rotation matrix for one of the 8 standard views.  
createUniformScale(scaleFactor: number): Matrix3d 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  
createZero(): Matrix3d 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): Matrix3d Static Return a new Matrix3d constructed from contents of the json value.  
xyPlusMatrixTimesXY(origin: XAndY, matrix: Matrix3d, vector: XAndY, result?: Point2d): Point2d Static compute origin + matrix * vector using only the xy parts of the inputs.  
xyzMinusMatrixTimesXYZ(origin: XYAndZ, matrix: Matrix3d, vector: XYAndZ, result?: Point3d): Point3d Static compute origin - matrix * vector  
xyzPlusMatrixTimesCoordinates(origin: XYZ, matrix: Matrix3d, x: number, y: number, z: number, result?: Point3d): 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): 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): 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 Matrix3d 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: 13 June, 2024