User guide

23 Nodegraph API
The Nodegraph API is a Python interface for creating Katana recipes by adding and connecting nodes, and setting
Parameters. The Nodegraph API cannot access the Scene Graph. In order to understand the limitations of the Node
Graph it’s important to have a clear understanding of the difference between the Node Graph and the Scene
Graph. See Katana For The Impatient for more on this.
The Nodegraph API can be accessed by Python scripts in the Python tab, Super Tools, plug-ins, shelves and other
custom UI. It is available to scripts used running in script and shell modes, but is hidden from, and so should not be
used by Attribute Scripts or Parameter expressions. Attempting to access the Nodegraph API from Attribute Scripts
or Parameter expressions could result in topological changes to the Node Graph whilst it is being evaluated. The
Nodegraph API can only be used inside a running Katana session, it is not a standalone Python module.
Nodegraph API Basics
When Katana iterates over the Scene Graph it performs what is effectively a depth-first graph search. Starting at a
single top level node, it asks for any nodes adjacent to that location, then interrogates each of those nodes on their
adjacent nodes, and so on. For this reason, a Katana Scene Graph is always nested under a single root location.
Creating a New Node
Nodes must be created under the root node, or under a node that accepts child nodes (such as a Group node, or
SuperTool), nested under the root node. To create nodes directly under the root node, you must pass the Node
Graph root location as an argument. To create nodes under a Group node, enter the group location as an argument.
For example, to add a Primitive Create node under the root node enter the following in the Python tab:
# Get the root node
root = NodegraphAPI.GetRootNode()
# Create a new node under the root node
node = NodegraphAPI.CreateNode( 'PrimitiveCreate', root )
This creates a new PrimitiveCreate node, which - in turn - generates a scene graph location containing a single
primitive. By default the PrimitiveCreate node is set to type sphere.
The new node is an instance of a Python class that represents that node type, and may contain additional methods
specifically for working with that type. For example, a Gaffer node has addLight() and getLightPaths() methods
that do not exist for other node types.
NOTE: You can use the Python help function to get information about a particular function call. For