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