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.

Enable Autoload

Enable autoload for the Action Graph Bundle:

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:

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.

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:

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:

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:

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:

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:

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:

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

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:

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:

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

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:

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:

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:

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:

Finally, drag the cube around the scene:

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.