Node Utilities

Module providing utility functions for the PackageSuperToolAPI related to node creation and manipulation.

PackageSuperToolAPI.NodeUtils.AddNodeRef(destNodeOrGroupParam, key, node)

Adds a reference to a node or a group parameter on a given node using a given string key. This is used in package nodes to store a reference to another node or parameter relevant to that package. Internally, this is done by adding a special user parameter in destNodeOrGroupParam containing an expression pointing to node.

Parameters:

  • destNodeOrGroupParam (NodegraphAPI.Node or NodegraphAPI.GroupParameter) – A node or group parameter where the reference will be stored.

  • key (str) – The key to be used as the name of the reference.

  • node (NodegraphAPI.Node) – The node to be referenced.

Raises:

TypeError – If the first argument supplied is neither a node nor a parameter.

PackageSuperToolAPI.NodeUtils.AddPackageTypeAndPath(node, packageType, locationPath)

Adds the package type and path parameters to the given node.

Parameters:

  • node (NodegraphAPI.Node) – The node to which to add the parameters.

  • packageType (str) – The type of the given node’s package, to store in the parameters created.

  • locationPath (str) – The location path of the given node’s package, to store in the parameters created.

PackageSuperToolAPI.NodeUtils.AppendNode(nodeA, nodeB)

Given two nodes A and B, connects B below A in the node graph. The port connected to A’s output will be connected to the output of B, and the input port of B will be connect to the output port of A.

Parameters:

  • nodeA (Node) – The node under which nodeB should be appended.

  • nodeB (Node) – The node to be appended to nodeA.

Note:

Only handles single input and output ports - only the first (0-index) ports will be reconnected. If nodeA’s output port has multiple sinks, only the first will be reconnected.

PackageSuperToolAPI.NodeUtils.AppendNodes(parentGroupNode, nodes)

Connects the given nodes in a chain, connecting the head of the chain to the last node in the given parent Group node.

Parameters:

  • parentGroupNode (Node) – The parent node.

  • nodes (tuple of Node) – The nodes to append.

PackageSuperToolAPI.NodeUtils.DeleteDeepParameter(parentGroupParam, paramPath)

Deletes the parameter at the given parameter path and any of its parent group parameters if they are empty afterwards.

Parameters:

  • parentGroupParam (NodegraphAPI.GroupParameter) – The parent group parameter in which to delete the parameter with the given path.

  • paramPath (str) – The path to the parameter to delete. This can be a nested parameter path containing “.” separators.

PackageSuperToolAPI.NodeUtils.GetDownstreamNodes(node)

Given a node that belongs to a package, returns the set of all downstream nodes that belong to the same package.

Return type:

set of Node

Parameters:

node (Node) – The node from which to find downstream nodes.

Returns:

The set of all nodes downstream from node.

PackageSuperToolAPI.NodeUtils.GetDownstreamPorts(port)

Given an node port, will traverse to any connected downstream node connections, passing through any group ports. Returns a list of connected input ports

PackageSuperToolAPI.NodeUtils.GetEditPackageForLocationPath(mainNode, locationPath)
Return type:

Package or None

Parameters:

  • mainNode (Node) – The SuperTool Node instance for which to return an edit package for the given location path.

  • locationPath (str) – The location path for which to return the EditPackage.

Returns:

An EditPackage instance for the given location path, or None if no such EditPackage node is found.

PackageSuperToolAPI.NodeUtils.GetEditPackageLocationPaths(mainNode)
Return type:

list of str

Parameters:

mainNode (Node) – The SuperTool Node instance for which to return a list of the names of the edit packages.

Returns:

A list of the names of EditPackage instances for the SuperTool of the given Node instance.

PackageSuperToolAPI.NodeUtils.GetEditPackages(mainNode)
Return type:

list of Package

Parameters:

mainNode (Node) – The SuperTool Node instance for which to return a list of the edit packages.

Returns:

A list of the EditPackage instances for the SuperTool of the given Node instance.

PackageSuperToolAPI.NodeUtils.GetPackageLocationParameterPath()
Return type:

str

Returns:

The path to the parameter which contains the package location.

PackageSuperToolAPI.NodeUtils.GetPackageTypeParameterPath()
Return type:

str

Returns:

The path to the parameter which contains the package type.

PackageSuperToolAPI.NodeUtils.GetRefNode(nodeOrGroupParam, key)

Given a key and a node or group parameter that might contain references to nodes (via the special parameters added by AddNodeRef) returns a node pointed by the reference.

Return type:

NodegraphAPI.Node or None

Parameters:

  • nodeOrGroupParam (NodegraphAPI.Node or NodegraphAPI.GroupParameter) – A node or group parameter where the reference might be stored.

  • key (str) – The key to be used as the name of the reference.

Returns:

The referenced node or None if no reference with the given key is found in the given node or group parameter.

PackageSuperToolAPI.NodeUtils.GetSceneGraphPathExpression(package, path, raiseOnMissing=True)

A utility for generating the getParam() expression which will evaluate to the scene graph path for the package at the given path, for the SuperTool to which the given package belongs.

Return type:

str

Parameters:

  • package (Package) – A package belonging to the SuperTool for which the scene graph path expression should be returned.

  • path (str) – The path corresponding to the package for which a scene graph path expression should be returned.

Returns:

The expression which will evaluate to the scene graph path for the package corresponding to the given path, in the SuperTool to which the give package belongs.

PackageSuperToolAPI.NodeUtils.GetSuperToolGroupName()
Return type:

str

Returns:

The name of the group parameter which contains information about the SuperTool.

PackageSuperToolAPI.NodeUtils.GetUpstreamPort(port)

Given an input (consumer) node port, will traverse to any connected upstream node connection, passing through any group ports. Returns any connected output port.

PackageSuperToolAPI.NodeUtils.IsNodeGuardedFromDeletion(node)
Return type:

bool

Parameters:

node (NodegraphAPI.Node) – The node to check.

Returns:

True if the given node is guarded from deletion, otherwise False.

PackageSuperToolAPI.NodeUtils.NodeDeletionGuard(node)

Marks the node as protected against deletion, which can be tested by calling IsNodeGuardedFromDeletion() and passing a node to check.

Parameters:

node (NodegraphAPI.Node) – The node to guard from deletion.

PackageSuperToolAPI.NodeUtils.PositionMergeInputs(mergeNode)

Evenly positions the nodes connected to the inputs of the given merge node.

Parameters:

mergeNode (NodegraphAPI.Node) – The node whose inputs should be evenly positioned.

PackageSuperToolAPI.NodeUtils.PrependNode(nodeA, nodeB)

Given two nodes A and B, connects B above A in the node graph. The port connected to A’s input will be connected to the input of B, and the output port of B will be connect to the input port of A.

Parameters:

  • nodeA (Node) – The node to which to prepend nodeB.

  • nodeB (Node) – The node to be prepended to nodeA.

Note:

Only handles single input and output ports - only the first (0-index) ports will be reconnected.

PackageSuperToolAPI.NodeUtils.RemoveNodeRef(nodeOrGroupParam, key)

Removes the reference to a node (added by AddNodeRef) with the given key from the given node or group parameter.

Parameters:

  • nodeOrGroupParam (NodegraphAPI.Node or NodegraphAPI.GroupParameter) – A node or group parameter where the reference may have been be stored.

  • key (str) – The key to be used as the name of the reference.

PackageSuperToolAPI.NodeUtils.SetOrCreateDeepArrayParameter(parentGroupParam, paramPath, paramValue)

Sets the value of an array parameter, creating it and any of its parent group parameters as required if they don’t exist.

Return type:

NodegraphAPI.GroupParameter

Parameters:

  • parentGroupParam (NodegraphAPI.GroupParameter) – The parent group parameter in which to set (and create if necessary) the parameter with the given path.

  • paramPath (str) – The path to the parameter whose value should be set. This can be a nested parameter path containing “.” separators.

  • paramValue (list of str or int or float) – A list of values to which the given parameter should be set.

Returns:

The parameter (newly-created if it didn’t already exist), set to the given value.

PackageSuperToolAPI.NodeUtils.SetOrCreateDeepScalarParameter(parentGroupParam, paramPath, paramValue, hintString=None)

Sets the value of a scalar parameter, creating it and any of its parent group parameters as required if they don’t exist.

Return type:

NodegraphAPI.GroupParameter

Parameters:

  • parentGroupParam (NodegraphAPI.GroupParameter) – The parent parameter in which to set (and create if necessary) the parameter with the given path.

  • paramPath (str) – The path to the parameter whose value should be set. This can be a nested parameter path containing “.” separators.

  • paramValue (str or int or float) – The value to which the given parameter should be set.

  • hintString (str or None) – An optional hint string for the parameter.

Returns:

The parameter (newly-created if it didn’t already exist), set to the given value.

PackageSuperToolAPI.NodeUtils.SetOrCreateDeepVectorParameter(parentGroupParam, paramPath, paramValue)
Deprecated:

This function is deprecated. Please use SetOrCreateDeepArrayParameter() instead.

PackageSuperToolAPI.NodeUtils.SetPackageNodeName(package)

Sets the name of the given package’s main node and post-merge stack node (if found).

Parameters:

package (Package) – The package for which to set the node names.

PackageSuperToolAPI.NodeUtils.TransferNodeConnections(oldNode, newNode)

Moves all the connections of a given node to a different node.

Parameters:

  • oldNode (Node) – The node that will be deprived of its connections.

  • newNode (Node) – The node that will gain the connections.

PackageSuperToolAPI.NodeUtils.UpdateChildPackagePaths(inputPackage)

Recursively walks the child packages of the given input package, updating the package location parameters with their location.

Parameters:

inputPackage (Package) – The package whose children’s package location parameters should be updated.

PackageSuperToolAPI.NodeUtils.UpdateEditPackagePaths(mainNode, previousRootLocationPath)

Iterates over the edit packages that are contained in the given SuperTool node and updates their package paths with the current root location path under which locations are created for packages maintained by the SuperTool node.

Parameters:

  • mainNode (Node) – The SuperTool Node instance for which to update edit packages.

  • previousRootLocationPath (str) – The path of the location under which packages were previously edited.

PackageSuperToolAPI.NodeUtils.WireInlineNodes(parentGroupNode, nodes, x=0, y=0)

Connects a list of nodes (using the first input and output ports) that exist inside a given parent group node.

Parameters:

  • parentGroupNode (NodegraphAPI.GroupNode) – The parent group node which encloses the nodes in the given list of nodes.

  • nodes (list of NodegraphAPI.Node) – The list of nodes inside the given parent group node which should be connected together.

  • x (int) – The horizontal offset which should be applied to the given nodes’ positions within the enclosing node.

  • y (int) – The vertical offset which should be applied to the given nodes’ positions within the enclosing node.