NodeGraphQt Documentation

To create a new node type, subclass NodeGraphQt.BaseNode. You must define a unique __identifier__ and a NODE_NAME. In the __init__ method, call super().__init__() and use add_input(name) and add_output(name) to define the node's ports.

To use the node in a graph, first register the class using node_graph.register_node(MyNode), then instantiate it using node_graph.create_node('identifier.ClassName', name='node_name', pos=(x, y)).

from Qt import QtWidgets
from NodeGraphQt import BaseNode, NodeGraph

class MyNode(BaseNode):
    __identifier__ = 'io.github.jchanvfx'
    NODE_NAME = 'my node'

    def __init__(self):
        super(MyNode, self).__init__()
        self.add_input('foo')
        self.add_output('bar')

if __name__ == '__main__':
    app = QtWidgets.QApplication([])
    node_graph = NodeGraph()
    node_graph.register_node(MyNode)
    node_graph.widget.show()

    # Create node using the identifier and class name
    node_a = node_graph.create_node('io.github.jchanvfx.MyNode', name='node a')
    app.exec_()

To use NodeGraphQt, you must define a custom node class by inheriting from BaseNode. You define a unique __identifier__ and a NODE_NAME. Inside the __init__ method, you use add_input and add_output to define the node's ports. Once the class is registered with a NodeGraph instance using register_node, you can instantiate nodes using create_node with their full identifier and connect them using set_output on the source node and input on the target node.

from Qt import QtWidgets
from NodeGraphQt import NodeGraph, BaseNode

# 1. Define a custom node class
class FooNode(BaseNode):
    __identifier__ = 'io.github.jchanvfx'
    NODE_NAME = 'Foo Node'

    def __init__(self):
        super(FooNode, self).__init__()
        # Create an input port
        self.add_input('in', color=(180, 80, 0))
        # Create an output port
        self.add_output('out')

if __name__ == '__main__':
    app = QtWidgets.QApplication([])

    # 2. Initialize the graph controller
    graph = NodeGraph()

    # 3. Register the node class
    graph.register_node(FooNode)

    # 4. Show the widget
    graph_widget = graph.widget
    graph_widget.show()

    # 5. Create nodes (using the identifier: domain.ClassName)
    node_a = graph.create_node('io.github.jchanvfx.FooNode', name='node A')
    node_b = graph.create_node('io.github.jchanvfx.FooNode', name='node B', pos=(300, 50))

    # 6. Connect node_a to node_b
    # set_output(output_index, input_port_object)
    node_a.set_output(0, node_b.input(0))

    app.exec_()

To integrate NodeGraphQt into Foundry Nuke, you can register the NodeGraph.widget property as a Nuke panel.

Because Nuke's panels.registerWidgetAsPanel often adds unwanted margins to the registered widget, it is recommended to wrap the graph.widget in a custom QtWidgets.QWidget and use a margin-resetting hack (via setContentsMargins(0, 0, 0, 0)) on the parent hierarchy when the widget is shown. This ensures the node graph fills the entire panel area.

from nukescripts import panels
from Qt import QtWidgets, QtCore
from NodeGraphQt import NodeGraph, BaseNode

# 1. Define your nodes
class TestNode(BaseNode):
    __identifier__ = 'nodes.nuke'
    NODE_NAME = 'test node'
    def __init__(self):
        super(TestNode, self).__init__()
        self.add_input('in')
        self.add_output('out 1')
        self.add_output('out 2')

# 2. Initialize the graph and register nodes
graph = NodeGraph()
graph.register_node(TestNode)

# 3. Create a wrapper widget to handle Nuke-specific layout issues
class CustomNodeGraph(QtWidgets.QWidget):
    def __init__(self, parent=None):
        super(CustomNodeGraph, self).__init__(parent)
        layout = QtWidgets.QVBoxLayout(self)
        layout.setContentsMargins(0, 0, 0, 0)
        layout.addWidget(graph.widget)

    def event(self, event):
        if event.type() == QtCore.QEvent.Type.Show:
            # Hack to remove margins from Nuke's panel container
            try:
                parent_widget = self.parentWidget().parentWidget()
                target_widgets = {parent_widget, parent_widget.parentWidget().parentWidget()}
                for widget_layout in target_widgets:
                    widget_layout.layout().setContentsMargins(0, 0, 0, 0)
            except Exception:
                pass
        return super(CustomNodeGraph, self).event(event)

# 4. Register with Nuke
panels.registerWidgetAsPanel(
    widget='CustomNodeGraph',
    name='Custom Node Graph',
    id='nodegraphqt.graph.CustomNodeGraph'
)

You can add custom menus and commands to the main graph context menu using NodeGraph.get_context_menu('graph'). This allows you to create sub-menus and assign functions to specific commands, optionally including keyboard shortcuts.

To add a command, use add_menu(label) to create a sub-menu and add_command(label, func, shortcut) to add an executable item to that menu.

from NodeGraphQt import NodeGraph

# test function.
def my_test(graph):
    selected_nodes = graph.selected_nodes()
    print('Number of nodes selected: {}'.format(len(selected_nodes)))

# create node graph.
node_graph = NodeGraph()

# get the main context menu.
context_menu = node_graph.get_context_menu('graph')

# add a menu called "Foo".
foo_menu = context_menu.add_menu('Foo')

# add "Bar" command to the "Foo" menu.
# we also assign a short cut key "Shift+t" for this example.
foo_menu.add_command('Bar', my_test, 'Shift+t')