omni.graph: OmniGraph Python Scripting

While the core part of OmniGraph is built in C++ there are Python bindings and scripts built on top of it to make it easier to work with.

Importing

The Python interface is exposed in a consistent way so that you can easily find any of the OmniGraph scripting information. Any script can start with this simple import, in the spirit of how popular packages such as numpy and pandas work:

import omni.graph.core as og

Using this module you can access internal documentation through the usual Python mechanisms:

help(og)
dir(og)

Bindings

The first level of support is the Python Bindings which provide a wrapper on top of the C++ ABI of the OmniGraph core. These have been made available from the same import to make user of all OmniGraph functionality consistent. When you are programming in Python you really don’t need to be aware of the C++ underpinnings.

The bound functions have all of the same documentation available at runtime so they can be inspected in the same way you would work with any regular Pythyon scripts. For the most part the bindings follow the C++ ABI closely, with the minor exception of using the standard PEP8 naming conventions rather than the established C++ naming conventions.

For example a C++ ABI function getAttributeType will be named get_attribute_type in the Python binding. This was primarily done to deemphasize the boundary between Python and C++ so that Python writers can stick with Python conventions and C++ writers can stick with C++ conventions.

As the Python world doesn’t have the C++ concept of an interface definition there is no separation between the objects providing the functionality and the objects storing the implementation and data. For example in C++ you would have an AttributeObj which contains a handle to the internal data and a reference to the IAttribute interface definition. In Python you only have the og.Attribute object which encapsulates both.

You can see the online version of the Python documentation at OmniGraph Python API Documentation.

Commands

The One Thing You Need

A lot of the imported submodules and functions available are used internally by generated code and you won’t have much occasion to use them. You can explore the internal documentation to see if any look useful to you. The naming was intentionally made verbose so that it’s easier to discover functionality.

One class deserves special attention though, as it is quite useful for interacting with the OmniGraph.

import omni.graph.core as og
helper = og.OmniGraphHelper()

The OmniGraphHelper class provides functionality for you to change the graph topology, or modify and inspect values within the graph. These are the main functions you want to use - see the internal documentation for details on how to use them.

OmniGraphHelper.omnigraph_node(x)      # Find an og.Node from a variety of descriptions
OmniGraphHelper.omnigraph_attribute(x) # Find an og.Attribute from a variety of descriptions
OmniGraphHelper.edit_graph(x)          # Batch a bunch of graph modification commands
OmniGraphHelper.create_node(x)         # Create a new OmniGraph node
OmniGraphHelper.create_prim(x)         # Create a new USD prim wrapped with an OmniGraph node
OmniGraphHelper.get_values(x)          # Get some OmniGraph attribute values
OmniGraphHelper.set_values(x)          # Set some OmniGraph attribute values
OmniGraphHelper.connect(x)             # Make a connection
OmniGraphHelper.disconnect(x)          # Break a connection

The helper class tries to be tolerant of different types of node and attribute descriptions, so that you can pass in what you have and it will convert to what it needs. (e.g. a node could be a path, an og.Node, or a USD prim)

Contents

OmniGraph Commands

Like other extensions, the OmniGraph extensions expose undoable functionality through some basic commands. A lot of the functionality of the commands can be accessed from the OmniGraphHelper object, described above.

OmniGraph has created a shortcut to allow more natural expression of command execution. The raw method of executing a command is something like this:

import omni.graph.core as og
graph = og.get_current_graph()
omni.kit.commands.execute("CreateNode", graph=graph, node_path="/testSingleton", node_type="omni.graph.examples.python.TestSingleton", create_usd=True)

The abbreviated method, using the constructed cmds object looks like this:

import omni.graph.core as og
graph = og.get_current_graph()
cmds.CreateNode(graph=graph, node_path="/testSingleton", node_type="omni.graph.examples.python.TestSingleton", create_usd=True)

And finally if you use the helper class you can shorten it to this:

import omni.graph.core as og
helper = og.OmniGraphHelper()
helper.create_node("/testSingleton", "omni.graph.examples.python.TestSingleton")

Tip

Running the Python command help(omni.graph.core.cmds) in the script editor will give you a description of all available commands.