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
$\matrixXY{A}$
is stored as 9 numbers in "row-major" order in a Float64Array, viz
$\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.

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 an outer product.
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 columns in axisOrder.
clone(result?: 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): 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
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.
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.
multiplyInverseTranspose(vector: Vector3d, result?: Vector3d): Vector3d | undefined Solve matrixTranspose * result = vector.
multiplyInverseXYZAsPoint3d(x: number, y: number, z: number, result?: Point3d): Point3d | undefined multiply matrixInverse * [x,y,z] and return packaged as Point3d.
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] and return packaged as Point4d with given weight.
multiplyMatrixInverseMatrix(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined Multiply this matrix times inverse of other
multiplyMatrixMatrix(other: Matrix3d, result?: Matrix3d): Multiply two matrices.
multiplyMatrixMatrixInverse(other: Matrix3d, result?: Matrix3d): Matrix3d | undefined Multiply this matrix times inverse of other
multiplyMatrixMatrixTranspose(matrixB: Matrix3d, result?: Matrix3d): Multiply this matrix times the transpose of matrixB.
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.
multiplyTransposeVector(vector: Vector3d, result?: 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): Multiply the transpose matrix times column using individual numeric inputs.
multiplyVector(vectorU: XYAndZ, result?: 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): 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 | 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 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,
toQuaternion(): convert the matrix to a quaternion.
transpose(result?: Matrix3d): return a transposed matrix.
transposeInPlace(): void transpose this matrix in place.
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, u: number, vectorV: XAndY, v: number, vectorW: XAndY, w: number, result?: 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): 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.
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).
createRigidFromMatrix3d(source: Matrix3d, axisOrder: AxisOrder.XYZ = AxisOrder.XYZ, result?: Matrix3d): Matrix3d | undefined Static create a new orthogonal matrix (perpendicular columns, unit length, transpose is inverse).
createRigidHeadsUp(vectorA: Vector3d, axisOrder: AxisOrder.ZXY = AxisOrder.ZXY, result?: Matrix3d): Static Construct a rigid matrix using createHeadsUpPerpendicular to generate a vector perpendicular to vectorA..
createRigidViewAxesZTowardsEye(x: number, y: number, z: number, result?: 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): 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.ZXY, 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 from "as viewed" right and up vectors.
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: 16 November, 2020