Creating and Retrieving Nodes

Creating a Node

New nodes must be parented to a node that accepts child nodes, such as the root node (a special node representing the top level of the node graph), a Group or LiveGroup node, or a SuperTool. For example, to add a PrimitiveCreate node under the root node enter the following in the Python tab:

# Get the root node
rootNode = NodegraphAPI.GetRootNode()

# Create a new node under the root node
primNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

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 node. For example, a GafferThree node has a getRootPackage() method that does not exist for other node types.

Note

You can use the Python help function to get information about a particular function call. For example:

help(NodegraphAPI.CreateNode)

NodegraphAPI.CreateNode(type, parent=None)

Create a new node of the given type. If the parent argument is given, the node will be created inside that group. To create a node in the top level of the node graph, pass NodegraphAPI.GetRootNode().

Returns:

The newly created node.

Return type:

Node

Parameters:

• type (str) – Name of the node type.

• parent (GroupNode) – Optional parent group.

Retrieving a Node

You can reference a node using the function GetNode(). For example, to retrieve a node called PrimitiveCreate use:

primNode = NodegraphAPI.GetNode('PrimitiveCreate')

Parameters are referenced in a similar way to nodes, using the function getParameter(). For example, to retrieve the type parameter of a node called PrimitiveCreate, use:

primTypeParam = NodegraphAPI.GetNode('PrimitiveCreate').getParameter('type')

Tip

Shift+middle-drag to the Python tab from a node in the Node Graph tab, or a parameter in the Parameters tab to automatically create the path to that node or parameter. For example, dragging from a node PrimitiveCreate in the node graph produces:

NodegraphAPI.GetNode('PrimitiveCreate')

NodegraphAPI.GetNode(nodeName)

Find existing node by name. Search all created nodes for the node with the given name. The node name is not necessarily the node type. If the node is not found, None is returned.

Returns:

The newly created node.

Return type:

Node or None

Parameters:

nodeName (str) – Name of the node type.

NodegraphAPI.GetRootNode()

Each node graph exists inside a single root node. The root node always exists, even inside a new project.

Return type:

NodegraphAPI.GroupNode

Returns:

The node graph’s root node.

NodegraphAPI.SetRootNode(newNode)

NodegraphAPI.GetAllNodes(includeDeleted=False, sortByName=True)

Get all the created nodes. Return all the nodes that have been created. An empty list means there are no nodes, but this is rare because of the root node.

Parameters:

• includeDeleted (bool) – Include deleted nodes.

• sortByName (bool) – Sort the list of nodes returned by GetAllNodes alphabetically. If False Node names are returned in an arbitrary order.

Returns:

All nodes

Return type:

list of Node

NodegraphAPI.GetAllNodesByType(nodeType, includeDeleted=False, sortByName=True)

Get all the nodes with the specified type. Return all the nodes that have been created. An empty list means there are no nodes, but this is rare because of the root node.

Parameters:

• nodeType (str) – Type of node to return.

• includeDeleted (bool) – Include deleted nodes.

• sortByName (bool) – Sort the list of nodes returned by GetAllNodesByType alphabetically. If False Node names are returned in an arbitrary order.

Returns:

All nodes

Return type:

list of Node

NodegraphAPI.GetViewNode()

Get the node that is currently viewed. When the node is viewed, its output is displayed in the interface.

Return type:

Node or None

NodegraphAPI.GetViewNodes()

Get the nodes that are currently viewed. When the node is viewed, its output is displayed in the interface. :rtype: Node or None

NodegraphAPI.GetAllEditedNodes()

Get all nodes that are being edited. When nodes are edited their parameters are displayed in the user interface. There can be none or several nodes edited at once time.

Return type:

list of Node

NodegraphAPI.GetAllSelectedNodes()

Get all the nodes that are currently selected. Interface operations that effect nodes will be applied to selected nodes. There can be any number of selected nodes at a time.

Return type:

list of Node

NodegraphAPI.GetAllSelectedNodesAndParent()

Get the selected nodes inside a parent. Some interface options can only work on nodes inside a single parent. This convenience function helps to get the selected nodes, but fail if the selection crosses groups.

Return type:

(list of Node, GroupNode)

Raises:

ValueError – All selected nodes are not in the same group

NodegraphAPI.GetAllFloatingNodes()

Get a list of all nodes that are floating. When nodes are interactively created or moved, they become floating nodes. Floating nodes track with the mouse movement until they are placed.

Return type:

list of Node

NodegraphAPI.GetAllThumbnailEnabledNodes()