Class SbMatrix

• ```public class SbMatrix
extends SbBasic```
4x4 matrix class. 4x4 matrix class/datatype used by many Open Inventor node and action classes.

Matrices

The Open Inventor API uses the convention that positions and directions in 3D space are represented by row vectors. Therefore, to apply a transform matrix, the vector is post-multiplied by the matrix as shown in the following figure. Many mathematics and computer graphics books use column vector notation, however there is no functional difference between these two approaches.

Note that the commonly used terms "row major" and "column major" refer to the storage order of the matrix components in memory. This has nothing to do with how you use matrices and vectors with the Open Inventor API. Internally Open Inventor uses the same storage order as OpenGL to allow matrices to be passed efficiently to/from the GPU. When using the Open Inventor API just remember that positions are row vectors, as shown here.

``` [X' Y' Z' 1] = [X Y Z 1] * | m11 m12 m13 m14 |
| m21 m22 m23 m24 |
| m31 m32 m33 m34 |
| m41 m42 m43 m44 |```

Some common 4x4 transform matrices look like this:

``` Identity  | 1 0 0 0 |  Translate  | 1  0  0  0 |  Scale  | Sx  0  0  0 |  RotateX  | 1    0     0 0 |
| 0 1 0 0 |             | 0  1  0  0 |         |  0 Sy  0  0 |           | 0 cosT -sinT 0 |
| 0 0 1 0 |             | 0  0  1  0 |         |  0  0 Sz  0 |           | 0 sinT  cosT 0 |
| 0 0 0 1 |             | Tx Ty Tz 1 |         |  0  0  0  1 |           | 0    0     0 1 |```

Therefore, to create a translation matrix you could initialize the `SbMatrix` object like this (or you could simply use the `setTranslate()` convenience method):

` SbMatrix( 1,0,0,0, 0,1,0,0, 0,0,1,0, Tx,Ty,Tz,1 ) `

For convenience `SbMatrix` allows its values to be accessed using 2D array syntax, like this:

`  value = matrix.getElement( row, column ); `

For example, the translation X, Y, Z values in the above example can be retrieved using:

```  Tx = matrix[3][0]  // Row 3, Column 0
Ty = matrix[3][1]  // Row 3, Column 1
Tz = matrix[3][2]  // Row 3, Column 2 ```

Multiplying points

Points (positions in 3D space) are transformed by post-multiplying the row vector with the transform matrix like this:

`  P' = P * M `
If you need to transform a point by a matrix use the `multVecMatrix()` method as shown here:
``` SbMatrix M;
SbVec3f  src;
SbVec3f dst = M.multVecMatrix( src );```
Note that it is safe to use the same `SbVec3f` object as both src and dst.

In `SbViewVolume`, for example, the projectToScreen() method first calls the getMatrix() method to get the combined model/view/projection matrix, then calls that object's `multVecMatrix()` method to transform the 3D point into normalized clipping space (-1 to 1). (It then does one more step to convert that position to 0..1 normalized screen space but that's not important here.)

Multiplying directions

Vectors that represent a direction in 3D space rather than a position, for example surface normal vectors for geometry, can also be transformed. But in this case the translation portion of the matrix (if any) must not be used. For example, if a matrix contains the translation [10, 20, 30], then transforming the normal vector [0, 0, 1] using `multVecMatrix()` would produce the result [10, 20, 31]. However the correct result is still [0, 0, 1] because translation has no meaning for a direction vector. The method `multDirMatrix()` is provided to transform direction vectors ignoring the translation portion of the matrix.

Generally normals should be transformed by the inverse transpose of the matrix. See standard computer graphic references for the explanation.

``` SbMatrix M;
SbVec3f  src;
SbVec3f dst = M.transpose().inverse().multDirMatrix( src );```
However note that if the matrix is orthonormal, i.e. purely rotational with no scaling or shearing, then the inverse transpose is the same as the original matrix and it is not necessary to compute the inverse transpose.

Multiplying matrices

A series of transforms, for example scale, rotate and translate can be combined into a single transform matrix by multiplying the matrices together. The result of such a multiplication is order dependent. Using the row vector convention, we can say that transforms are applied from "left to right". We normally want scaling applied first, then rotation, then translation, as shown here:

`  P' = P * S * R * T `

So we would build the combined transform matrix M from scale, rotate and translate matrices S, R and T like this:

`  M = S * R * T `

Note that convenience nodes like `SoTransform` do this (combine the scale, rotate and translate) for you automatically. So you don't necessarily need to remember all the details.

If you need to combine matrices yourself, you can use the `multLeft()` or `multRight()` method to multiple each matrix with the combined matrix. The name Â“multLeftÂ” means to pre-multiply the `SbMatrix` object with the specified `SbMatrix` parameter, so we would combine the matrices like this:

``` SbMatrix M, S, R, T;
M = T;
M.multLeft( R );
M.multLeft( S );```
Note that `multLeft()` overwrites the matrix currently in the `SbMatrix` object. So usually (as shown) you will start by making a copy of the first matrix as the starting point for accumulation.

The name Â“multRightÂ” means to post-multiply the `SbMatrix` object with the specified `SbMatrix` parameter. So we would combine the matrices like this:

``` SbMatrix M, S, R, T;
M = S;
M.multRight( R );
M.multRight( T );```
Note that `multRight()` also overwrites the matrix currently in the `SbMatrix` object. So usually (as shown) you will start by making a copy of the first matrix as the starting point for accumulation.

`SbMatrix3`, `SbMatrixd`, `SbRotation`, `SbRotationd`, `SbVec2d`, `SbVec2f`, `SbVec2i32`, `SbVec2s`, `SbVec3d`, `SbVec3f`, `SbVec3i32`, `SbVec3s`, `SbVec4b`, `SbVec4d`, `SbVec4f`, `SbVec4i32`, `SbVec4s`, `SbVec4ub`, `SbVec4ui32`, `SbVec4us`
• Nested Class Summary

Nested Classes
Modifier and Type Class Description
`static class ` `SbMatrix.Decomposition`
`static class ` `SbMatrix.Factorization`
• Field Summary

Fields
Modifier and Type Field Description
`float[]` `array`
• Constructor Summary

Constructors
Constructor Description
`SbMatrix()`
`SbMatrix​(float[] components)`
```SbMatrix​(float c0, float c1, float c2, float c3, float c4, float c5, float c6, float c7, float c8, float c9, float c10, float c11, float c12, float c13, float c14, float c15)```
`SbMatrix​(SbMatrix copyFrom)`
• Method Summary

All Methods
Modifier and Type Method Description
`SbMatrix.Decomposition` `decompose()`
Returns the translation, rotation, scale, and scale orientation components of the matrix.
`SbMatrix.Decomposition` `decompose​(SbVec3f center)`
Decomposes the matrix into a translation, rotation, scale, and scale orientation.
`float` `det3()`
Returns determinant of upper-left 3x3 submatrix.
`float` ```det3​(int r1, int r2, int r3, int c1, int c2, int c3)```
Returns determinant of 3x3 submatrix composed of given row and column indices (0-3 for each).
`float` `det4()`
Returns determinant of entire matrix.
`boolean` ```equals​(SbMatrix m, float tolerance)```
Equality comparison within given tolerance, for each component.
`boolean` `equals​(java.lang.Object obj)`
`SbMatrix.Factorization` `factor()`
Factors a matrix m into 5 pieces: m = r s r^ u t, where r^ means transpose of r, and r and u are rotations, s is a scale, and t is a translation.
`float[]` `getColumn​(int col)`
Gets a column of this matrix.
`float` ```getElement​(int row, int column)```
Gets the value at the specified row and column of this matrix.
`float[]` `getRow​(int row)`
Gets a row of this matrix.
`float[]` `getValue()`
`float` `getValueAt​(int index)`
`static SbMatrix` `identity()`
Returns an identity matrix.
`SbMatrix` `inverse()`
Returns inverse of matrix.
`boolean` `isInvertible()`
Returns true if the matrix is invertible.
`void` `makeIdentity()`
Sets matrix to be identity.
`SbVec3f` `multDirMatrix​(SbVec3f src)`
Pre-multiplies the matrix by the given row vector, giving vector result.
`void` `multiply​(SbMatrix m)`
Post-multiplies the matrix by the given matrix (equivalent to `multRight()` method).
`SbMatrix` `multLeft​(SbMatrix m)`
Pre-multiplies matrix by the given matrix.
`SbLine` `multLineMatrix​(SbLine src)`
Multiplies the given line's origin by the matrix, and the line's direction by the rotation portion of the matrix.
`SbVec3f` `multMatrixVec​(SbVec3f src)`
Post-multiplies matrix by the given column vector, giving a 3D vector result.
`SbVec4f` `multMatrixVec4​(SbVec3f src)`
Posts-multiplies matrix by the given column vector, giving vector result in homogeneous coordinates.
`SbMatrix` `multRight​(SbMatrix m)`
Post-multiplies the matrix by the given matrix.
`SbVec4f` `multVec4Matrix​(SbVec3f src)`
Pre-multiplies matrix by the given row vector, giving vector result in homogeneous coordinates.
`SbVec3f` `multVecMatrix​(SbVec3f src)`
Pre-multiplies matrix by the given row vector, giving a 3D vector result.
`void` `scale​(SbVec3f scaleFactor)`
Scales this matrice by the given vector.
`void` ```setElement​(int row, int column, float value)```
Sets the value at the specified row and column of this matrix.
`void` `setRotate​(SbRotation q)`
Sets matrix to rotate by given rotation.
`void` `setScale​(float s)`
Sets matrix to scale by given uniform factor.
`void` `setScale​(SbVec3f s)`
Sets matrix to scale by given vector.
`void` ```setTransform​(SbVec3f t, SbRotation r, SbVec3f s)```
Composes the matrix based on a translation, rotation, and scale.
`void` ```setTransform​(SbVec3f t, SbRotation r, SbVec3f s, SbRotation so)```
Composes the matrix based on a translation, rotation, scale, and orientation for scale.
`void` ```setTransform​(SbVec3f translation, SbRotation rotation, SbVec3f scaleFactor, SbRotation scaleOrientation, SbVec3f center)```
Composes the matrix based on a translation, rotation, scale, orientation for scale, and center.
`void` `setTranslate​(SbVec3f t)`
Sets matrix to translate by given vector.
`SbMatrix` `setValue​(float[] components)`
`SbMatrix` ```setValue​(float[] components, int startIndex)```
`SbMatrix` ```setValue​(float c0, float c1, float c2, float c3, float c4, float c5, float c6, float c7, float c8, float c9, float c10, float c11, float c12, float c13, float c14, float c15)```
`void` `setValue​(SbMatrix copyFrom)`
`void` `setValue​(SbMatrixd md)`
Sets value from a double precision matrix.
`void` ```setValueAt​(int index, float value)```
`SbMatrix` `times​(SbMatrix m2)`
Multiplies two matrices, returning a matrix result.
`SbVec4f` `times​(SbVec4f v)`
Multiply matrix by given vector.
`static SbMatrix[]` ```toArray​(long nativeArray, long length)```
`void` `translate​(SbVec3f translation)`
Translates this matrice by the given vector.
`SbMatrix` `transpose()`
Returns transpose of matrix.
• Methods inherited from class java.lang.Object

`getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
• Field Detail

• array

`public final float[] array`
• Constructor Detail

• SbMatrix

`public SbMatrix​(SbMatrix copyFrom)`
• SbMatrix

`public SbMatrix​(float[] components)`
• SbMatrix

`public SbMatrix()`
• SbMatrix

```public SbMatrix​(float c0,
float c1,
float c2,
float c3,
float c4,
float c5,
float c6,
float c7,
float c8,
float c9,
float c10,
float c11,
float c12,
float c13,
float c14,
float c15)```
• Method Detail

• getRow

`public float[] getRow​(int row)`
Gets a row of this matrix.
Returns:
an array of 4 floats.
• getColumn

`public float[] getColumn​(int col)`
Gets a column of this matrix.
Returns:
an array of 4 floats.
• setElement

```public void setElement​(int row,
int column,
float value)```
Sets the value at the specified row and column of this matrix.
• getElement

```public float getElement​(int row,
int column)```
Gets the value at the specified row and column of this matrix.
• getValue

`public float[] getValue()`
• getValueAt

`public float getValueAt​(int index)`
• setValue

```public SbMatrix setValue​(float[] components,
int startIndex)```
• setValue

`public SbMatrix setValue​(float[] components)`
• setValue

`public void setValue​(SbMatrix copyFrom)`
• setValue

```public SbMatrix setValue​(float c0,
float c1,
float c2,
float c3,
float c4,
float c5,
float c6,
float c7,
float c8,
float c9,
float c10,
float c11,
float c12,
float c13,
float c14,
float c15)```
• setValueAt

```public void setValueAt​(int index,
float value)```
• isInvertible

`public boolean isInvertible()`
Returns true if the matrix is invertible.
• equals

```public boolean equals​(SbMatrix m,
float tolerance)```
Equality comparison within given tolerance, for each component.
• identity

`public static SbMatrix identity()`
Returns an identity matrix.
• toArray

```public static SbMatrix[] toArray​(long nativeArray,
long length)```
• times

`public SbVec4f times​(SbVec4f v)`
Multiply matrix by given vector. Return m * v
• multiply

`public void multiply​(SbMatrix m)`
Post-multiplies the matrix by the given matrix (equivalent to `multRight()` method). Matrix is replaced by the resulting matrix.
• times

`public SbMatrix times​(SbMatrix m2)`
Multiplies two matrices, returning a matrix result.
• scale

`public void scale​(SbVec3f scaleFactor)`
Scales this matrice by the given vector.
• equals

`public boolean equals​(java.lang.Object obj)`
Overrides:
`equals` in class `java.lang.Object`
• setTransform

```public void setTransform​(SbVec3f t,
SbRotation r,
SbVec3f s)```
Composes the matrix based on a translation, rotation, and scale. A scale orientation value of (0,0,0,1) is used. The center point for scaling and rotation is (0,0,0).
• setTransform

```public void setTransform​(SbVec3f t,
SbRotation r,
SbVec3f s,
SbRotation so)```
Composes the matrix based on a translation, rotation, scale, and orientation for scale. The scaleOrientation chooses the primary axes for the scale. The center point for scaling and rotation is (0,0,0).
• setTransform

```public void setTransform​(SbVec3f translation,
SbRotation rotation,
SbVec3f scaleFactor,
SbRotation scaleOrientation,
SbVec3f center)```
Composes the matrix based on a translation, rotation, scale, orientation for scale, and center. The scaleOrientation chooses the primary axes for the scale. The center is the center point for scaling and rotation.
• transpose

`public SbMatrix transpose()`
Returns transpose of matrix. Matrix is not modified.
• setTranslate

`public void setTranslate​(SbVec3f t)`
Sets matrix to translate by given vector.
• decompose

`public SbMatrix.Decomposition decompose​(SbVec3f center)`
Decomposes the matrix into a translation, rotation, scale, and scale orientation. Any projection information is discarded. The decomposition depends upon choice of center point for rotation and scaling, which is optional as the last parameter. Note that if the center is 0, decompose() is the same as `factor()` where t is translation, u is rotation, s is scaleFactor, and r is scaleOrientation.
• det4

`public float det4()`
Returns determinant of entire matrix.
• det3

`public float det3()`
Returns determinant of upper-left 3x3 submatrix.
• det3

```public float det3​(int r1,
int r2,
int r3,
int c1,
int c2,
int c3)```
Returns determinant of 3x3 submatrix composed of given row and column indices (0-3 for each).
• factor

`public SbMatrix.Factorization factor()`
Factors a matrix m into 5 pieces: m = r s r^ u t, where r^ means transpose of r, and r and u are rotations, s is a scale, and t is a translation. Any projection information is returned in proj.
• translate

`public void translate​(SbVec3f translation)`
Translates this matrice by the given vector.
• decompose

`public SbMatrix.Decomposition decompose()`
Returns the translation, rotation, scale, and scale orientation components of the matrix.
• inverse

`public SbMatrix inverse()`
Returns inverse of matrix. Results are undefined for singular matrices. Uses LU decomposition.
Matrix is not modified.
• multVec4Matrix

`public SbVec4f multVec4Matrix​(SbVec3f src)`
Pre-multiplies matrix by the given row vector, giving vector result in homogeneous coordinates. Use this method to transform a point (position vector).
Use `multDirMatrix()` to transform a normal (direction vector).
• multMatrixVec4

`public SbVec4f multMatrixVec4​(SbVec3f src)`
Posts-multiplies matrix by the given column vector, giving vector result in homogeneous coordinates.
• setValue

`public void setValue​(SbMatrixd md)`
Sets value from a double precision matrix.
• multDirMatrix

`public SbVec3f multDirMatrix​(SbVec3f src)`
Pre-multiplies the matrix by the given row vector, giving vector result. src is assumed to be a direction vector, so translation part of matrix is ignored.

Note: If you need to transform surface points and normal vectors by a matrix, call `multVecMatrix()` for the points and call `multDirMatrix()` for the normals. Generally normals should be transformed by the inverse transpose of the matrix. However note that the inverse transpose is equal to the original matrix if the matrix is orthonormal, i.e. purely rotational with no scaling or shearing.

• multLineMatrix

`public SbLine multLineMatrix​(SbLine src)`
Multiplies the given line's origin by the matrix, and the line's direction by the rotation portion of the matrix.
• multVecMatrix

`public SbVec3f multVecMatrix​(SbVec3f src)`
Pre-multiplies matrix by the given row vector, giving a 3D vector result. The intermediate homogeneous (vec4) value is converted to 3D by dividing the X, Y and Z components by W.

Use this method to transform a point (position vector).
Use `multDirMatrix()` to transform a normal (direction vector).

• setScale

`public void setScale​(float s)`
Sets matrix to scale by given uniform factor.
• multRight

`public SbMatrix multRight​(SbMatrix m)`
Post-multiplies the matrix by the given matrix. Matrix is replaced by the result.
• setScale

`public void setScale​(SbVec3f s)`
Sets matrix to scale by given vector.
• multLeft

`public SbMatrix multLeft​(SbMatrix m)`
Pre-multiplies matrix by the given matrix. Matrix is replaced by the result.
• makeIdentity

`public void makeIdentity()`
Sets matrix to be identity.
• multMatrixVec

`public SbVec3f multMatrixVec​(SbVec3f src)`
Post-multiplies matrix by the given column vector, giving a 3D vector result. The intermediate homogeneous (vec4) value is converted to 3D by dividing the X, Y and Z components by W.
• setRotate

`public void setRotate​(SbRotation q)`
Sets matrix to rotate by given rotation.