The SoGetMatrixAction^{( C++ | Java | .NET )} returns the current transformation matrix for any node derived from SoTransformation^{( C++ | Java | .NET )} or for a path. When you apply this action to any SoTransformation^{( C++ | Java | .NET )} node, it returns the transformation matrix for that node. When you apply it to a path, SoGetMatrixAction^{( C++ | Java | .NET )} accumulates a transformation matrix for all the transformations in the subgraph defined by that path. This action enables you to convert from one coordinate space to another, typically from local space to world space (when you apply it to a path whose head node is the root of the scene graph).

An important distinction between SoGetMatrixAction^{( C++ | Java | .NET )} and other actions is that SoGetMatrixAction^{( C++ | Java | .NET )} does not traverse downward in the scene graph from the node or path to which it is applied. When applied to a node, it returns the current transformation matrix for that node only (and therefore makes sense only for transformation nodes, since all others return identity). When applied to a path, it collects transformation information for all nodes in the path but stops when it reaches the last node in the path chain.

SoGetMatrixAction mtxAction(newRegion);
    

SoGetMatrixAction mtxAction = new SoGetMatrixAction(newRegion);
    

SoGetMatrixAction mtxAction = new SoGetMatrixAction(newRegion);
    

Obtain Results

Two methods return the results of SoGetMatrixAction^{( C++ | Java | .NET )}:

getMatrix()	returns an SbMatrix( C++ | Java ) that is the cumulative transformation matrix for the node or path
getInverse()	returns an SbMatrix that is the inverse of the cumulative transformation matrix for the node or path

The getInverse() method enables you to take a point in world space and map it into an object's local coordinate space. See the Open Inventor C++ Reference Manual for a description of the many convenient methods available for SbMatrix^{( C++ | Java )}. For example, you can use multVecMatrix() to transform a point by a matrix. Use multDirMatrix() to transform a direction vector by a matrix. (Inventor assumes row vectors.)

	Tip: You can convert a point in one object's coordinate space into another object's space by applying a get-matrix action to the first object, transforming the point into world space using the matrix, applying a get-matrix action to the other object, and then transforming the world-space point by the inverse matrix of the second object.

As an example, assume that SoGetMatrixAction^{( C++ | Java | .NET )} is applied to the path shown in Figure 8.3, “ Applying SoGetMatrixAction to a Path ”. The xform1 node contains a translation of (0.0, 0.0, 1.0), and the xform2 node contains a scale of (0.5, 0.5, 0.5).

Figure 8.3.  Applying SoGetMatrixAction to a Path

Each new transformation is premultiplied onto the current transformation matrix. In this case, the matrix multiplication looks like this:

In this example, getMatrix() returns the following matrix:

For texture coordinates, use the getTextureMatrix() and getTextureInverse() methods. See Chapter 7, Textures and the Open Inventor C++ Reference Manual for more information.