TreeBuilder

TreeBuilder(
    tree='Geometry Nodes',
    *,
    tree_type='GeometryNodeTree',
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    ignore_visibility=False,
    split_inputs=None,
    clear=False,
)

Builder for creating Blender node trees with a clean Python API.

Supports geometry, shader, and compositor node trees.

Attributes

Name Description
collapse
fake_user
group_input_splits The extra Group Input instances beyond the primary one, each as
ignore_visibility
inputs
layout_snapshot A structural layout snapshot: for every node its type, (x, y)
node_positions A {node name: (x, y)} snapshot of every node’s location.
nodes
outputs
tree

Methods

Name Description
activate_tree Make this tree the active tree for all new node creation.
add
arrange
compositor Create a compositor node tree.
deactivate_tree Whatever tree was previously active is set to be the active one (or None if no previously active tree).
disable_arrange Disable the auto-layout that otherwise runs when this tree’s context
geometry Create a geometry node tree.
link
panel A panel that can group input and output sockets together
shader Create a shader node tree.
split_group_inputs Split the Group Input node into one instance per consumer node,
to_mermaid Generate a Mermaid diagram that represents this tree.
to_plot Draw this tree to an image, styled like Blender’s node editor,
to_python Generate Python source that recreates this tree using nodebpy.

activate_tree

activate_tree()

Make this tree the active tree for all new node creation.

add

add(name)

arrange

arrange()

compositor

compositor(
    name='Compositor Nodes',
    *,
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    split_inputs=None,
    clear=False,
)

Create a compositor node tree.

deactivate_tree

deactivate_tree()

Whatever tree was previously active is set to be the active one (or None if no previously active tree).

disable_arrange

disable_arrange()

Disable the auto-layout that otherwise runs when this tree’s context exits, so explicitly assigned node locations are preserved.

geometry

geometry(
    name='Geometry Nodes',
    *,
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    split_inputs=None,
    clear=False,
)

Create a geometry node tree.

panel

panel(name, *, description='', default_closed=False, reuse=True)

A panel that can group input and output sockets together (tree.inputs.panel / tree.outputs.panel group one direction). Reuses an existing same-named panel under the same parent, so a mixed panel can be declared in separate input and output passes; pass reuse=False to always create a fresh panel — Blender allows several same-named sibling panels, and rebuilding such an interface must not fold them into one. Passing an existing panel (or a previous tree.panel(...) context) instead of a name reopens exactly that panel — the unambiguous spelling generated code uses for the second direction pass over a same-named sibling.

shader

shader(
    name='Shader Nodes',
    *,
    collapse=False,
    arrange='sugiyama',
    fake_user=False,
    split_inputs=None,
    clear=False,
)

Create a shader node tree.

split_group_inputs

split_group_inputs()

Split the Group Input node into one instance per consumer node, with unused sockets hidden — regenerating the editor style that avoids a single input node trailing long noodles. Each instance is named (and labelled, so the editor header shows it) after the interface sockets it carries, making it easy to spot when scanning the tree (Blender de-duplicates repeated names with .001 suffixes as usual), and parented into its consumer’s frame so the arranger’s frame clustering keeps the pair together. Runs automatically on context exit (before auto-layout, so the instances are arranged next to their consumers) when the builder was created with split_inputs=True, or inside a :func:~nodebpy.builder.default_split_inputs scope.

to_mermaid

to_mermaid(fenced=True)

Generate a Mermaid diagram that represents this tree.

This can be used for documentation or visualization purposes. The Mermaid syntax is supported by many tools, including GitHub and Jupyter notebooks.

Arguments

fenced:
    Whether to wrap the output in a fenced code block with mermaid syntax highlighting.

Returns

Name Type Description
A string containing the Mermaid diagram syntax representing this node tree.

to_plot

to_plot(
    filepath,
    *,
    title=None,
    dpi=150,
    node=False,
    open_panels=False,
    width=None,
    axes=False,
)

Draw this tree to an image, styled like Blender’s node editor, for headless review (pip install nodebpy[plot]): its internals, or with node=True the single group node a user adds to another tree, showing the interface sockets with their default values.

See :func:nodebpy.export.to_plot.

to_python

to_python(
    min_chain_length=3,
    strict=True,
    max_inline_width=88,
    snapshot_positions=False,
    keep_reroutes=False,
    top_level='with',
    format=True,
    nodebpy_pkg='nodebpy',
    in_place=False,
)

Generate Python source that recreates this tree using nodebpy.

See :func:nodebpy.codegen.to_python for parameter details.