omni.graph: OmniGraph Python

OmniGraph Python Scripting

Extension: omni.graph

Documentation Generated: Jan 26, 2023

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.


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:



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 API (python).

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
controller = og.Controller()

The Controller class provides functionality for you to change the graph topology, or modify and inspect values within the graph.

    r"""Class to provide a simple interface to a variety OmniGraph manipulation functions.

    Provides functions for creating nodes, making and breaking connections, and setting values.
    Graph manipulation functions are undoable, value changes are not.

    Functions are set up to be as flexible as possible, accepting a wide variety of argument variations.

    Here is a summary of the interface methods you can access through this class, grouped by interface class. The ones
    marked with an "*" indicate that they have both a classmethod version and an object method version. In those cases
    the methods use object member values which have corresponding arguments in the classmethod version. (e.g. if the
    method uses the "update_usd" member value then the method will also have a "update_usd:bool" argument)

        \* edit             Perform a collection of edits on a graph (the union of all interfaces)

        async evaluate   Runs evaluation on one or more graphs as a waitable (typically called from async tests)

        evaluate_sync    Runs evaluation on one or more graphs immediately

        attribute        Looks up an og.Attribute from a description

        attribute_path   Looks up an attribute string path from a description

        attribute_type   Looks up an og.Type from a description

        graph            Looks up an og.Graph from a description

        node             Looks up an og.Node from a description

        node_path        Looks up a node string path from a description

        prim             Looks up an Usd.Prim from a description

        prim_path        Looks up a Usd.Prim string path from a description

        split_graph_from_node_path  Separate a graph and a relative node path from a full node path

        \* connect          Makes connections between attribute pairs

        \* create_graph     Creates a new og.Graph

        \* create_node      Creates a new og.Node

        \* create_prim      Creates a new Usd.Prim

        \* create_variable  Creates a new og.IVariable

        \* delete_node      Deletes a list of og.Nodes

        \* disconnect       Breaks connections between attribute pairs

        \* disconnect_all   Breaks all connections to and from specific attributes

        \* expose_prim      Expose a USD prim to OmniGraph through an importing node

        \* create_attribute Create a new dynamic attribute on a node

        \* remove_attribute Remove an existing dynamic attribute from a node

        safe_node_name   Get a node name in a way that's safe for USD

        \* get              Get the value of an attribute's data

        \* get_array_size   Get the number of elements in an array attribute's data

        \* set              Set the value of an attribute's data

    Class Attributes:
        class Keys: Helper for managing the keywords needed for the edit() function

        __path_to_object_map: Mapping from the node or prim path specified to the created node or prim

        OmniGraphError: If the requested operation could not be performed


See the internal documentation at omni.graph.core.Controller for details, or take a tour of how to use the controller with this how-to documentation