API Reference > core-geometry > 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 matrix with 2-dimensional layout (note: a 2d array can be shown by a matrix)
    [Axx Axy AxzAyx Ayy AyzAzx Azy Azz]\matrixXY{A}
    is stored as 9 numbers in "row-major" order in a Float64Array, viz
    [Axx Axy Axz Ayx Ayy Ayz Azx Azy Azz]\rowMajorMatrixXY{A}
  • If the matrix inverse is known it is stored in the inverseCoffs array.
  • The inverse status (unknown, inverseStored, singular) status is indicated by the inverseState property.
  • Construction methods that are able to trivially construct the inverse, store it immediately and note that in the inverseState.
  • Constructions (e.g. createRowValues) for which the inverse is not immediately known mark the inverseState as unknown.
  • Later queries for the inverse, trigger full computation if needed at that time.
  • 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 Constructor  
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 an outer product.  
applyGivensColumnOp(i: number, j: number, c: number, s: number): void Replace current columns Ui and 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 columns in axisOrder.  
clone(result?: Matrix3d): Matrix3d Return a clone of this matrix.  
columnDotXYZ(columnIndex: AxisIndex, x: number, y: number, z: number): number Dot product of an indexed column with a vector given as x,y,z  
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.  
factorOrthogonalScaleOrthogonal(matrixV: Matrix3d, scale: Point3d, 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).  
factorPerpendicularColumns(matrixC: Matrix3d, matrixU: Matrix3d): boolean Factor this as a product C * U where C has mutually perpendicular columns and  
factorRigidWithSignedScale(): undefined | { rigidAxes: Matrix3d, scale: number } 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(): Readonly<Matrix3d> 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): undefined | Matrix3d return the inverse matrix.  
isAlmostEqual(other: Matrix3d, tol?: number): boolean Test if this and other are within tolerance in all numeric entries.  
isAlmostEqualAllowZRotation(other: Matrix3d, tol?: number): boolean Test if this and other have almost equal Z column and have X and Y columns differing only by a  
isAlmostEqualColumn(columnIndex: AxisIndex, other: Matrix3d, tol?: number): boolean Test if this and other are within tolerance in the column entries specified by columnIndex.  
isAlmostEqualColumnXYZ(columnIndex: AxisIndex, ax: number, ay: number, az: number, tol?: number): boolean Test if column (specified by columnIndex) entries of this and [ax,ay,az] are within tolerance.  
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.  
makeRigid(axisOrder: AxisOrder = AxisOrder.XYZ): boolean Adjust the matrix in place so that:  
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 of this and other  
multiplyInverse(vector: Vector3d, result?: Vector3d): undefined | Vector3d Solve matrix * result = vector.  
multiplyInverseTranspose(vector: Vector3d, result?: Vector3d): undefined | Vector3d Solve matrixTranspose * result = vector.  
multiplyInverseXYZAsPoint3d(x: number, y: number, z: number, result?: Point3d): undefined | Point3d multiply matrixInverse * [x,y,z] and return packaged as Point3d.  
multiplyInverseXYZAsVector3d(x: number, y: number, z: number, result?: Vector3d): undefined | Vector3d multiply matrixInverse * [x,y,z].  
multiplyInverseXYZW(x: number, y: number, z: number, w: number, result?: Point4d): undefined | Point4d multiply matrixInverse * [x,y,z] and return packaged as Point4d with given weight.  
multiplyMatrixInverseMatrix(other: Matrix3d, result?: Matrix3d): undefined | Matrix3d Multiply this matrix times inverse of other  
multiplyMatrixMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d Multiply the instance matrix A by the input matrix B.  
multiplyMatrixMatrixInverse(other: Matrix3d, result?: Matrix3d): undefined | Matrix3d Multiply this matrix times inverse of other  
multiplyMatrixMatrixTranspose(matrixB: Matrix3d, result?: Matrix3d): Matrix3d Multiply this matrix times the transpose of matrixB.  
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(vectorU: XYZ): void Multiply the transpose matrix times column using any 3d object with x,y,z members.  
multiplyTransposeXYZ(x: number, y: number, z: number, result?: Vector3d): Vector3d Multiply the transpose matrix times column using individual numeric inputs.  
multiplyVector(vectorU: Readonly<WritableXYAndZ>, result?: Vector3d): Vector3d Multiply the matrix * vector, treating the vector is a column vector on the right.  
multiplyVectorArrayInPlace(data: XYZ[]): void Multiply matrix * vector for each array member, 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(): undefined | number 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 Scale the columns 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: undefined | Vector3d): void Set entries in one column of the matrix.  
setColumns(vectorX: undefined | Vector3d, vectorY: undefined | Vector3d, 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: undefined | Matrix3d): void Copy contents from another matrix.  
setFromJSON(json?: Matrix3d | 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 transpose of this matrix.  
transposeInPlace(): void Transpose this matrix in place.  
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: undefined | Vector3d, columnB: undefined | Vector3d, columnC: undefined | Vector3d, result?: Matrix3d): Matrix3d Static Create a matrix by distributing vectors to columns in one of 6 orders.  
createColumnsXYW(vectorU: Readonly<WritableXAndY>, u: number, vectorV: Readonly<WritableXAndY>, v: number, vectorW: Readonly<WritableXAndY>, w: number, result?: Matrix3d): Matrix3d Static Create a matrix with each column's x,y parts given XAndY and separate numeric z values.  
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): undefined | Matrix3d Static Return a matrix that rotates a fraction of the angular sweep from vectorA to vectorB.  
createPerpendicularVectorFavorPlaneContainingZ(vectorA: Vector3d, result?: Vector3d): Vector3d Static Return a vector that is perpendicular to the input vectorA.  
createPerpendicularVectorFavorXYPlane(vectorA: Vector3d, result?: Vector3d): Vector3d Static Return a vector that is perpendicular to the input vectorA.  
createRigidFromColumns(vectorA: Vector3d, vectorB: Vector3d, axisOrder: AxisOrder, result?: Matrix3d): undefined | Matrix3d Static Create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).  
createRigidFromMatrix3d(source: Matrix3d, axisOrder: AxisOrder = AxisOrder.XYZ, result?: Matrix3d): undefined | Matrix3d Static Create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).  
createRigidHeadsUp(vectorA: Vector3d, axisOrder: AxisOrder = AxisOrder.ZXY, result?: Matrix3d): Matrix3d Static Construct a rigid matrix using vectorA and its 2 perpendicular.  
createRigidViewAxesZTowardsEye(x: number, y: number, z: number, result?: Matrix3d): Matrix3d Static create a rigid coordinate frame column z parallel to (x,y,z) and column x in the xy plane.  
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): undefined | Matrix3d Static Return the matrix for rotation of angle around axis  
createRotationVectorToVector(vectorA: Vector3d, vectorB: Vector3d, result?: Matrix3d): undefined | Matrix3d 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 axisOrder  
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 for scale factor "s"  
createViewedAxes(rightVector: Vector3d, upVector: Vector3d, leftNoneRight: number = 0, topNoneBottom: number = 0): undefined | Matrix3d Static Create a matrix from "as viewed" right and up vectors.  
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: Readonly<WritableXAndY>, matrix: Matrix3d, vector: Readonly<WritableXAndY>, result?: Point2d): Point2d Static compute origin + matrix * vector using only the xy parts of the inputs.  
xyzMinusMatrixTimesXYZ(origin: Readonly<WritableXYAndZ>, matrix: Matrix3d, vector: Readonly<WritableXYAndZ>, 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: Readonly<WritableXYAndZ>, 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 undefined | Float64Array 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: 30 November, 2023