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 of vectors U and V.  
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  
columnXDotColumnZ(): number Return the dot product of column X with column Z  
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  
columnYDotColumnZ(): number Return the dot product of column Y with column Z  
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 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 of this matrix 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 as a product V * D * U where V and U are orthogonal and D is diagonal with  
factorPerpendicularColumns(matrixVD: Matrix3d, matrixU: Matrix3d): boolean Factor this matrix as a product VD * U where VD has mutually perpendicular columns and U is orthogonal.  
factorRigidWithSignedScale(result?: Matrix3d): 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 matrix as a product U * lambda * UT where U is an orthogonal matrix and lambda  
freeze(): Readonly<Matrix3d> Freeze this Matrix3d.  
getAxisAndAngleOfRotation(): { angle: Angle, axis: Vector3d, ok: boolean } Compute the (unit vector) axis and angle for the rotation generated by this Matrix3d.  
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 elements of column index 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: booleanfalse): boolean Test if the matrix is a rigid matrix (or pure rotation, i.e., columns and rows are unit length and  
isSingular(): boolean Returns true if the matrix is singular.  
isSymmetric(): boolean Test if the matrix is (very near to) symmetric  
makeRigid(axisOrder: AxisOrderAxisOrder.XYZ): boolean Adjust the matrix in place to make is a rigid matrix 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 for an unknown result.  
multiplyInverseTranspose(vector: Vector3d, result?: Vector3d): undefined | Vector3d Solve matrixTranspose * result = vector for an unknown result.  
multiplyInverseXYZAsPoint3d(x: number, y: number, z: number, result?: Point3d): undefined | Point3d Multiply matrixInverse * [x,y,z] and return result 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 result as a Point4d with the given weight as the last coordinate.  
multiplyMatrixInverseMatrix(other: Matrix3d, result?: Matrix3d): undefined | Matrix3d Multiply inverse of this matrix times other matrix  
multiplyMatrixMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d Multiply this matrix times other matrix  
multiplyMatrixMatrixInverse(other: Matrix3d, result?: Matrix3d): undefined | Matrix3d Multiply this matrix times inverse of other matrix  
multiplyMatrixMatrixTranspose(other: Matrix3d, result?: Matrix3d): Matrix3d Multiply this matrix times the transpose of other matrix  
multiplyMatrixTransform(other: Transform, result?: Transform): Transform Multiply this Matrix3d (considered to be a Transform with 0 origin) times other Transform.  
multiplyMatrixTransposeMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d Multiply the transpose of this matrix times other matrix  
multiplyPoint(point: Point3d, result?: Point3d): Point3d Multiply matrix * point, treating the point as a column vector on the right.  
multiplyTransposeVector(vector: Vector3d, result?: Vector3d): Vector3d Multiply the transpose matrix times a vector.  
multiplyTransposeVectorInPlace(vectorU: XYZ): void Multiply the transpose matrix times [x,y,z] in place, i.e.  
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 matrix * vector, treating the vector is a column vector on the right.  
multiplyVectorArrayInPlace(data: XYZ[]): void Multiply matrix * vector in place for vector in the array, i.e.  
multiplyVectorInPlace(xyzData: XYZ): void Multiply the matrix * (x,y,z) in place, i.e.  
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(originalColumnMagnitudes?: Vector3d): boolean Normalize each column in place.  
normalizeRowsInPlace(originalRowMagnitudes?: Vector3d): boolean Normalize each row in place.  
originPlusMatrixTimesXY(origin: XYZ, x: number, y: number, result?: Point3d): Point3d Compute origin + the matrix * [x,y,0].  
rowX(result?: Vector3d): Vector3d Return (a copy of) the X row  
rowXMagnitude(): number Return the X row magnitude  
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 almost equal, return the first diagonal (entry 0  
scale(scale: number, result?: Matrix3d): Matrix3d Create a Matrix3d whose values are uniformly scaled from this Matrix3d.  
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 in place.  
scaleRows(scaleX: number, scaleY: number, scaleZ: number, result?: Matrix3d): Matrix3d Create a Matrix3d whose rows are scaled copies of this Matrix3d.  
scaleRowsInPlace(scaleX: number, scaleY: number, scaleZ: number): void Scale the rows of this Matrix3d in place.  
setAt(row: number, column: number, value: number): void Set the entry at specific row and column  
setColumn(columnIndex: number, value: Vector3d): void Set entries in one column of the matrix.  
setColumns(vectorX: Vector3d, vectorY: Vector3d, vectorZ?: Vector3d): void Set all columns of the matrix.  
setColumnsPoint4dXYZ(vectorU: Point4d, vectorV: Point4d, vectorW: Point4d): void Set data from xyz parts of Point4d (w part of Point4d ignored)  
setFrom(other: Matrix3d): void Copy contents from the other matrix.  
setFromJSON(json?: Matrix3dProps | Matrix3d): 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 matrix trace (sum of diagonal entries)  
sumDiagonalSquares(): number Return the sum of squares of diagonal entries  
sumSkewSquares(): number Sum of squared differences between symmetric pairs (symmetric pairs have indices (1,3), (2,6), and (5,7).)  
sumSquares(): number Return the sum of squares of all entries  
symmetricEigenvalues(leftEigenvectors: Matrix3d, lambda: Vector3d): boolean Factor this matrix as a product U * lambda * UT where U is an orthogonal matrix and lambda  
testPerpendicularUnitRowsAndColumns(): boolean Test if all rows and columns are unit length and are perpendicular to each other, i.e., the matrix is either  
toJSON(): Matrix3dProps Return a json object containing the 9 numeric entries as a single array in row major order,  
toQuaternion(): Point4d Create this 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: Vector3d, columnB: Vector3d, columnC: 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.  
createFlattenAlongVectorToPlane(sweepVector: Vector3d, planeNormal: Vector3d): undefined | Matrix3d Static Create a matrix which sweeps a vector along sweepVector until it hits the plane through the origin with the given normal.  
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: AxisOrderAxisOrder.XYZ, result?: Matrix3d): undefined | Matrix3d Static Create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).  
createRigidHeadsUp(vectorA: Vector3d, axisOrder: AxisOrderAxisOrder.ZXY, result?: Matrix3d): Matrix3d Static Construct a rigid matrix (orthogonal matrix with +1 determinant) using vectorA and its 2 perpendicular.  
createRigidViewAxesZTowardsEye(x: number, y: number, z: number, result?: Matrix3d): Matrix3d Static Create a rigid matrix (columns and rows are unit length and pairwise perpendicular) for the given eye coordinate.  
createRotationAroundAxisIndex(axisIndex: AxisIndex, angle: Angle, result?: Matrix3d): Matrix3d Static Returns a rotation of specified angle around one of the main axis (X,Y,Z).  
createRotationAroundVector(axis: Vector3d, angle: Angle, result?: Matrix3d): undefined | Matrix3d Static Return the matrix for rotation of angle around desired 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: booleanfalse, 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 factor "s":  
createViewedAxes(rightVector: Vector3d, upVector: Vector3d, leftNoneRight: number0, topNoneBottom: number0): 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 a 3x4 matrix.  
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 Updates vector to be 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 Static ReadOnly 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  
isLowerTriangular Accessor ReadOnly boolean Test if the above diagonal entries (1,2,5) are all nearly zero  
isSignedPermutation Accessor ReadOnly boolean Test if this matrix reorders and/or negates the columns of the identity matrix.  
isUpperTriangular Accessor ReadOnly boolean Test if the below diagonal entries (3,6,7) 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: 28 October, 2024