Node Properties

Node Instance Methods

Name

In Katana, each node has a name that is guaranteed to be unique across an entire Katana project. This means that when setting the name of a node, the resulting node name may be different from the one that was specified:

node = NodegraphAPI.GetNode('TeapotCreate')
node.setName('Teapot')
print(node.getName())

If the specified name is already in use by another node in the Katana project, Node.setName() adds a numeric suffix to the name, and returns the new unique node name, for example Teapot4 instead of Teapot.

It’s possible to store a string user parameter on a node that custom tools can search for, in order to reference a node in a smaller context. This is a simple pattern that can provide a more localized pseudo node name. See Parameters for more on adding parameters.

Note

Node names cannot contain spaces. Any spaces or invalid characters that are used in a specified node name are converted into underscores. For example, the node name 'Material Plastic' becomes 'Material_Plastic'.

Node.getName() → str

Returns:: The unique name of this node.

Node.setName(name: str, updateExpressions: bool = True) → str

Sets the name of this node based on the given name.

Adds a node_setName event to the event queue if the node name has changed.

Parameters:

name (str) – The name to attempt to set for the node.
updateExpressions (bool) – Flag that controls whether parameter expressions that use the old name of the node are updated to use the new name of the node, as returned by this function.

Returns:

The name that was set, which may contain a numeric suffix after the given name, in order to make the node name unique among all nodes that are part of this Katana project, and which may have certain characters in name replaced with underscores.

Type

Node.getBaseType() → str

Returns:: A string naming the real base type of this node.

Node.getType() → str

Returns:: A string naming the registered type of this node.

Node.setType(typeName: str)

Sets a string naming the registered type of this node.

Adds a node_setType event to the event queue if the type name has changed.

Parameters:: typeName (str) – The name of the type to set for this node.
Note:: This method ignores whether the node is locked against changes.

Parent Node

Node.getParent() → GroupNode | None

Returns:: The GroupNode that is the parent of this node, or None if there is no parent.

Node.setParent(parentNode: GroupNode | None, notify: bool = True) → bool

Sets the parent GroupNode of this node, returning True if the reparenting was successful. If parent is None, this node is orphaned.

Adds a node_setParent event to the event queue if the parent of the node has changed, and if notify is given as True.

Parameters:

parentNode (GroupNode or None) – The Group node to become the new parent for this node, or None to declare this node orphaned.
notify (bool) – True if a node_setParent event should be added to the event queue if setting the parent succeeded, otherwise False.

Returns:

True if setting the parent succeeded, otherwise False.

Parameters

See Parameters.

Node.customReset() → bool

Resets this node’s parameters to factory settings, returning True if a custom reset is implemented; otherwise, False is returned and a generic parameter-by-parameter reset will be attempted.

Returns:: True if the reset succeeded, otherwise False.

Node.isResetPossible() → bool

Returns:: True if this node can be reset, either by a generic parameter reset or by calling customReset(), otherwise False.

Ports

See Connecting Nodes.

The following instance methods are available to control the routing of ports for nodes that are disabled:

Node.getBypassRouting() → dict

Returns:: A dict of output port index to input port index, describing the port routing that takes place when this node is disabled.
See:: isBypassed(), setBypassed()

Node.setBypassRouting(portRouting: dict)

Sets the port routing used when this node is disabled, as a dict of output port index to input port index.

Adds a node_setBypassRouting event to the event queue if the bypass routing has changed.

Parameters:: portRouting (dict) – A map of output port index to input port index, describing the port routing that takes place when this node is disabled.
See:: isBypassed(), setBypassed()

Flags

Node.isAutoRenameAllowed() → bool

Returns:: True if Katana is allowed to automatically rename this node, for example based on the value of a particular string parameter, otherwise False.

Node.setAutoRenameAllowed(autoRenameAllowed: bool)

Sets whether this node is locked against automatic name changes.

Adds a node_setAutoRenameAllowed event to the event queue if the value of the flag has changed.

Parameters:: autoRenameAllowed (bool) – True to allow auto-renaming, False to forbid it.

Node.isBypassed() → bool

Returns:: True if the node is disabled, otherwise False.

Node.setBypassed(bypassed: bool)

Enables or disables the node according to the given bypassed state, controlling whether it participates in its respective node network, or whether it acts as an invisible pass-through.

Adds a node_setBypassed event to the event queue if the disabled state has changed.

Parameters:: bypassed (bool) – True to disable the node, False to enable it.

Node.isLocked(considerParents: bool = False) → bool

Parameters:: considerParents (bool) – Optional flag that controls whether to consider this node locked if any of its ancestors are locked; if a node is considered locked in this way, it cannot be modified via the UI, but can still be modified using the NodegraphAPI.
Returns:: True if this node is locked to prevent changes, otherwise False.

Node.setLocked(locked: bool)

Locks or unlocks the node to prevent or allow changes.

Adds a node_setLocked event to the event queue if the value of the flag has changed.

Parameters:: locked (bool) – True to lock the node against changes, or False to allow changes.

Node.isMarkedForDeletion() → bool

Returns:: True if this node has been deleted (via delete(), but hasn’t yet been deallocated by the deletion queue, otherwise False.

Node Attributes

Node attributes are mappings of property names to values that will be written to and read from Katana project files when serializing the node graph document. They consist of:

Attributes that represent standard node properties, like Name and Type.
Node Shape Attributes
Attributes from Node Extensions, like the presence of the node’s view and edit flags, the node’s selection state, and the node’s Position in the Node Graph tab’s canvas.

Node.getAttributes() → dict

Returns:: A dict of named static values that are persisted with this node.

Node.setAttributes(attributes: dict)

Assigns new named persistent values to this node, via a string-keyed dict.

Parameters:: attributes (dict) – The mapping of named persistent values to set for this node.

Caution

Node attributes should not be confused with scene graph attributes.

Miscellaneous

Node.delete() → bool

Marks this node and any child nodes it contains for deletion, setting their parent nodes to None, and renaming them with a '__XX_DELETED_' prefix.

Adds a node_delete_begin event to the event queue before marking the nodes for deletion, adds a node_delete event for every node that was marked for deletion, and adds a node_delete_end event after marking the nodes for deletion.

Returns:: True if the node was successfully marked for deletion, otherwise False.
See:: isMarkedForDeletion()

Node.getUpstreamContributingNodes(graphState: GraphState) → set[Node]

Collects and returns all nodes upstream from and including this node, which contribute to the node graph, based on the graph state provided.

Return type:: set of Node
Parameters:: graphState (GraphState) – The Graph State to use at for the node graph traversal. If null, uses the current graph state for the given node.
Returns:: The list of contributing upstream nodes, including the node itself.

Node Extensions

Node Extensions are custom Python modules that provide additional properties on top of the basic properties that are provided by the Node class.

At present, only one Node Extensions module is registered in Katana. It provides storage for a number of additional properties, and corresponding API functions for querying and modifying them, which are made available in the main NodegraphAPI namespace.

Flags

NodegraphAPI.IsNodeEdited(node)

True if the node parameters are displayed. 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:: bool

NodegraphAPI.SetNodeEdited(node, edited, exclusive=False)

Set if the node parameters are displayed. When nodes are edited their parameters are displayed in the user interface. There can be none or several nodes edited at once time. If optional exclusive arg is True, all nodes are unedited before setting the edited flag on specified node.

NodegraphAPI.IsNodeViewed(node)

True if the node results are displayed. When the node is viewed, its output is displayed in the interface.

Return type:: bool

NodegraphAPI.SetNodeViewed(node, viewed, exclusive=False)

Set if the node results are displayed. When the node is viewed, its output is displayed in the interface. If optional exclusive arg is True, all nodes are unviewed before setting the view flag on specified node.

NodegraphAPI.IsNodeSelected(node)

True if the node is selected in the interface. Interface operations that effect nodes will be applied to selected nodes. There can be any number of selected nodes at a time.

Return type:: bool

NodegraphAPI.SetNodeSelected(node, selected)

Set if the node is selected in the interface. Interface operations that effect nodes will be applied to selected nodes. There can be any number of selected nodes at a time.

NodegraphAPI.SetAllSelectedNodes(nodelist)

Replace the nodes that are selected. If the sequence of nodes is empty, all nodes will be unselected. Interface operations that effect nodes will be applied to selected nodes. There can be any number of selected nodes at a time.

NodegraphAPI.IsNodeHidden(node)

NodegraphAPI.SetNodeHidden(node, hide)

NodegraphAPI.IsNodeFloating(node)

True if the node is tracking the mouse position. When nodes are interactively created or moved, they become floating nodes. Floating nodes track with the mouse movement until they are placed.

Return type:: bool

NodegraphAPI.SetNodeFloating(node, flag)

Set if the node is tracking the mouse position. When nodes are interactively created or moved, they become floating nodes. Floating nodes track with the mouse movement until they are placed.

NodegraphAPI.IsNodeThumbnailEnabled(node)

NodegraphAPI.SetNodeThumbnailEnabled(node, enabled)

NodegraphAPI.IsNodeLockedByParents(node)

Return type:: bool
Parameters:: node (NodegraphAPI.Node or None) – The node whose parent nodes to check.
Returns:: True if the contents of any of the given node’s parent nodes are locked, otherwise False.

Node Shape Attributes

Node Shape Attributes are Node Attributes that control the appearance of nodes in the Node Graph tab, such as the node color to display.

NodegraphAPI.GetNodeShapeAttr(node, attrName)

NodegraphAPI.GetNodeShapeAttrs(node)

NodegraphAPI.SetNodeShapeAttr(node, attrName, attrValue)

NodegraphAPI.SetNodeShapeNodeAttrs(node, attrDict)

NodegraphAPI.DeleteNodeShapeAttr(node, attrName)

Caution

Custom node shape attributes can be added, which will be stored and restored when saving and loading a Katana project file (see Node Attributes). It is recommended to store only small amounts of data in custom node shape attributes, so as to keep Katana project files light and fast to load.

Comments

NodegraphAPI.GetNodeComment(node)

Get the user comment on the node

Return type:: string

NodegraphAPI.SetNodeComment(node, comment): Set the user comment.

Position

The SetNodePosition() function sets the position of a node in the Node Graph tab. The following example code demonstrates how a PrimitiveCreate node can be created and then positioned:

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

# Create a new node at the root level
primitiveCreateNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

# Define X & Y values
position = (0, 100)

# Set node position
NodegraphAPI.SetNodePosition(primitiveCreateNode, position)

NodegraphAPI.GetNodePosition(node)

Get the 2D position of the node. Created nodes have the position (0, 0). The position is in y-down integers.

Return type:: (int, int)

NodegraphAPI.SetNodePosition(node, xy)

Set the 2D position of the node. The position is in y-down integers.

Parameters:: xy (int, int) – the new node position

Miscellaneous

NodegraphAPI.GetMenuPath(nodeType)

NodegraphAPI.CheckNodeType(node, stringOrClassTypes)