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.
Raises:	ValueError – Node type not registered.

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()¶

Get the current root node. Each nodegraph will exist inside a single root node. The root node always exists, even inside a new file.

Return type:	`NodegraphAPI.GroupNode`

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.

Return type:	`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()¶