| Customize Help

3D graphics lists


You can annotate a 3D display by adding 3D graphics to its 3D graphics list, using functions from the M3dgra...() module.

You can also allocate a 3D graphics list that is not associated with a 3D display using M3dgraAlloc().

Structure of a 3D graphics list

A 3D graphics list has a node-based tree structure; each 3D graphic (except the root node) has a parent 3D graphic that partially defines its position and orientation. You can also use the tree structure to control multiple 3D graphics with a single call to M3dgraControl(), copy multiple 3D graphics with a single call to M3dgraCopy(), and remove multiple 3D graphics with a single call to M3dgraRemove().

The top of every 3D graphics list tree structure is a M_GRAPHIC_TYPE_NODE 3D graphic called the root node. The root node always has the identity transformation matrix.

When you add a 3D graphic to a 3D graphics list, you must specify the label of the parent graphic. You can use M_ROOT_NODE to specify the root node.

A point cloud 3D graphic added to the 3D graphics list using M3ddispSelect() or M3ddispSelectWindow() is always added as a child of the root node.

Controlling settings for multiple 3D graphics

You can control the settings for a 3D graphic and all of its descendents using M3dgraControl() with M_RECURSIVE. This is useful for creating groups of 3D graphics that should have the same settings. For example, you can create a node type graphic using M3dgraNode(), then label the displayed data by creating text 3D graphics (using M3dgraText()) that are children of the node 3D graphic. You can enable or disable visibility for all of these labels at once, using M3dgraControl() with the label of the node 3D graphic, M_VISIBLE, and M_RECURSIVE. Note that this works even though the node 3D graphic itself does not support the M_VISIBLE setting.

Copying multiple 3D graphics

You can copy a 3D graphic and/or all of its descendents using M3dgraCopy() with M_GRAPHIC the label of the source 3D graphic to copy, and the label of the destination 3D graphic (in the same 3D graphics list, or a different one) to be the parent of the copy.

If you specify M_RECURSIVE, all descendents of the source 3D graphic are also copied. The hierarchy of the source 3D graphics is maintained in the copies; the source 3D graphic is copied as a child of the destination 3D graphic, and the children of the source 3D graphic are copied as children of that copy.

If you specify M_CHILDREN_ONLY, only the descendents of the source 3D graphic are copied. The children of the source 3D graphic are copied as children of the destination 3D graphic; the hierarchy is maintained for their descendents.

Removing multiple 3D graphics

You can remove a 3D graphic using M3dgraRemove(). This also removes all of the 3D graphic's descendents.

Changing the positions of multiple 3D graphics

You can change the transformation matrix of a 3D graphic using M3dgraCopy() with M_TRANSFORMATION_MATRIX. The position and orientation of a 3D graphic is determined by adding its transformation matrix to the transformation matrix of its ancestors. You can therefore change the position and/or orientation of multiple 3D graphics by altering the transformation matrix of their parent. For example, you can add the 3D graphics used to annotate a particular point cloud as children of the point cloud 3D graphic. If you change the transformation matrix of the point cloud 3D graphic, all of the annotations automatically move with it.

Setting defaults for 3D graphics added to a 3D graphics list

You can control the default values for 3D graphics added to a 3D graphics list using M3dgraControl() with M_DEFAULT_SETTINGS. Any 3D graphics you subsequently add to the 3D graphics list will be created with these settings.