Introduction to OmniGraph

Note

This document contains features from OmniGraph version 2022.1.

In this tutorial, you use OmniGraph in Omniverse USD Composer to move one shape in response to another.

Note

While you use Omniverse USD Composer in this tutorial, you can follow similar steps to achieve the same results in other Omniverse Apps.

Load the OmniGraph Extensions

Before you start, you must load the OmniGraph extensions into Omniverse USD Composer.

Open the Extension Manager

In Omniverse USD Composer, click Window > Extensions:

Numbered steps for opening the Extensions manager.

This opens the Extensions manager, which you use to enable and disable Omniverse Extensions.

Enable the Action Graph Bundle

Search for “omni.graph.bundle.action”, and enable the Action Graph Bundle if necessary:

Numbered steps for enabling the |action_graph| Bundle.

This loads the omni.graph.bundle.action Extension bundle into Omniverse USD Composer.

Note

If you can’t to find the omni.graph.bundle.action Extension bundle, remove any filters you may have applied and try again.

Numbered steps for enabling the |action_graph| Bundle.

Enable Autoload

Enable autoload for the Action Graph Bundle:

Arrow pointing to the autoload toggle.

This ensures that Omniverse USD Composer will always load the Extension.

Now that you’ve enabled the Action Graph Bundle, close the Extension manager.

Prepare Your Scene

Prepare your empty scene by adding a cube and a cone.

Add a Cube

Right-click the scene, and click Create > Shapes > Cube:

Numbered steps for creating a cube.

This creates a cube prim at the position of the cursor.

Add a Cone

Similarly, right-click the scene, and click Create > Shapes > Cone to create a cone prim.

Numbered steps for creating a cone.

Now that you have added some Prims to your scene, you are ready to use OmniGraph.

Note

Alternatively, you can use the Create menu in the menu bar to add prims to the scene:

Numbered steps for creating a cone from the menu bar.

Set Up the Graph

It’s time to use OmniGraph in your scene. Specifically, you use an Action Graph to trigger actions in response to a particular event.

Open the Visual Scripting Editor

In the Window menu, click Visual Scripting > Action Graph:

Numbered steps for opening the Action Graph panel.

This opens the Action Graph editor panel.

Create an Action Graph

In the graph editor, click New Action Graph:

Numbered steps for creating an |action_graph|.

This creates an empty Action Graph at the default path. The graph editor now shows your newly-created graph. Next, you add some nodes to the graph!

Adding Nodes to the Graph

Because this is an introductory tutorial, you start simple. You create a graph that automatically moves the cone whenever you move the cube:

The cube and cone moving together.

Read the Cube’s Position

Drag and drop the cube from the Stage panel to the Action Graph panel:

Numbered steps for adding the cube to the Action Graph.

In the popup dialog, select Read Attribute:

Select read attribute.

This creates a Read Prim Attribute node, which can read information from the cube prim that you dragged in.

Next, you specify the attribute you want it to read.

Specify the Cube Attribute

Click the node, and set its Attribute Name to xformOp:translate in the Property panel:

Set the read attribute.

This tells the node to read the xformOp:translate attribute of the cube prim, which is the position of the cube.

Use an Add Node

In the search box, type “Add”, and drag and drop an Add node into the graph editor:

Numbered steps to use an add node.

The Add node adds two numerical values together.

Use an Constant Node

In the search box, type “Constant Point3d”, and drag and drop a Constant Point3d node into the graph editor:

Numbered steps to use a constant node.

Specify the Constant Value

Click the node, and set its X input value to 0.0, its Y value to 0.0, and its Z value to 120.0:

Numbered steps to specify constant attributes.

With this, the Constant Point3d node holds the constant 3-tuple: (0.0, 0.0, 120.0).

Wire up the Nodes

Click and drag the Constant Point3d node’s Value port to the Add node’s First Addend port:

Connect the constant and add nodes.

Similarly, connect the Read Prim Attribute node’s Value port to the Add node’s Second Addend port:

Connect the prim and add nodes.

In summary, you have an Add node that captures two numerical values:

  • The constant numerical tuple, that specifies a positive Z value and neutral X and Y values

  • The variable translation XForm value from the cube prim

The resulting value of the Add node, then, contains the cube’s location with a shift on the positive Z axis by 120.0 units. Next, you pass this value to the cone.

Note

Feel free to drag the nodes around the editor to keep the UI clean and clear.

Write the Cone’s Position

Drag and drop the cone from the Stage panel to the Action Graph panel:

Numbered steps for adding the cone to the Action Graph.

In the popup dialog, select Write Attribute:

Select write attribute.

This creates a Write Prim Attribute node, which can write information to the cone prim that you dragged in.

Next, you specify the attribute you want it to write.

Specify the Cone Attribute

Click the node, and set its Attribute Name to xformOp:translate in the Property panel:

Set the write attribute.

This tells the node to write the xformOp:translate attribute of the cone prim, which is the position of the cone.

Set the write attribute.

Wire up the Add and Write Nodes

Click and drag the Add node’s Sum port to the Write Prim Attribute node’s Value port:

Connect the add and write nodes.

This sets the location of the cone to the resulting sum of the Add node.

Trigger the Node Evaluation

Remember, the Action Graph evaluates its nodes when an event occurs. In this case, you use the “on tick” event.

Use an On Tick Node

In the search box, type “On Tick”, and drag and drop an On Tick node into the graph editor:

Numbered steps to use an on tick node.

The On Tick node fires an execution signal through its Tick execution port every single frame. Therefore, anything connected to its Tick port is evaluated every single frame.

In this case, you want to update the cone’s position on tick.

Wire up the On Tick Event

Click and drag the On Tick node’s Tick port to the Write Prim Attribute node’s Exec In port:

Connect the on tick and write nodes.

Now, every frame, your cone’s position will be updated to the result of the add node, which is the sum of the cube’s location and the constant point tuple (0.0, 0.0, 120.0). In other words, as you move your cube, your cone should move with it, but 120 units higher on the Z axis.

Technical Detail

The execution evaluator works by following node connections downstream and computing the nodes the evaluator encounters until there are no more connections to follow.

In this case, the evaluator executes the network downstream from outputs:tick attribute, whose next node is the Write Prim Attribute node. Before Prim Attribute can be computed, the evaluator evaluates its upstream data-dependency: the Add node, then the Constant Point 3d and Read Prim Attribute nodes. Finally, the Write Prim Attribute node is computed, which sets Torus.xformOp:translate to (0, 0, 0), the origin.

Review Your Work

Click Play in your scene’s toolbar:

Press the play button.

Finally, drag the cube around the scene:

The cube and cone moving together.

The cone moves with the cube, but above it by 120 units.

Common Problems and Caveats

If you encounter problems or have questions, please read through this section find an explanation of your problem, and potential solutions:

Common Problem/Question

Explanation

You are unable connect to a node input due to incompatible types.

Remove all connections from the target node and try reconnecting. When extended types are resolved, the node has to be disconnected to reset the types.

The node is set up correctly, but is not working.

Check the Console panel for error or warning messages, try saving and reloading the scene, and ensure you have loaded the Action Graph extensions bundle.