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)