Node API Design

Inputs

Input sockets are exposed in two different ways, they are positional arguments in the class __init__ signature and are available behind the inputs / i accessor on the nodes.

class SetPosition(BaseNode):
    def __init__(
        self,
        geometry: InputGeometry = None,
        selection: InputBoolean = None,
        position: InputVector = None,
        offset: InputVector = (0.0, 0.0, 0.0),
    ):

We can either pass in nodes / sockets / values into the constructor, or link them after construction.

The g.Cube() is used as a positional argument to geometry, while we explicitly state the offset with a keyword argument. On the second line we scale Position() by 0.5 and then link that to the position input of SetPosition.

with g.tree() as tree:
    sp = g.SetPosition(g.Cube(), offset=g.RandomValue() * 0.1)
    _ = (g.Position() * 0.5) >> sp.i.position

tree

Default Inputs

Some inputs read something other than their stored value when nothing is connected. Blender hides the value of such sockets in the editor: Set Position’s Position reads the position field, its Selection means every element, and many group assets declare a Default Input (an implicit field or context value) for an input. A constructor parameter whose value Blender hides defaults to None, which leaves the socket alone.

For generated asset classes the fallback is spelled out with Default, so it shows in the signature and the reference:

class RandomRotation(AssetGeometryGroup):
    def __init__(
        self,
        id: InputInteger = Default.ID_OR_INDEX,
        ...

The members mirror Blender’s default-input identifiers (Default.POSITION, Default.NORMAL, Default.INDEX, Default.ID_OR_INDEX, Default.INSTANCE_TRANSFORM, Default.HANDLE_LEFT, Default.HANDLE_RIGHT, Default.SCENE_FRAME, Default.UNIFORM_IMAGE_COORDINATES, Default.SELF_OBJECT). Passing a member to any constructor is the same as passing None: nothing is set or linked, the socket keeps its own fallback.

from nodebpy import Default

with g.tree() as tree:
    _ = g.SetPosition(g.Cube(), position=Default.POSITION) >> tree.outputs.geometry()

tree

Outputs

Selection of outputs is done automatically to best match the data types of the inputs. You can be specific with the output though, with outputs available behind the outputs / o accessor.

with g.tree() as tree:
    time = g.SceneTime()

    _ = (
        g.Cube()
        >> g.SetPosition(offset=g.RandomValue(min=-1) * time.o.seconds)
        >> tree.outputs.geometry()
    )

tree

Slicing Inputs and Outputs

You can use slicing to access individual or multiple components of input and output sockets.

with g.tree() as tree:
    sep = g.SeparateXYZ(g.Position())
    comb = g.CombineXYZ(*sep.o)
    comb2 = g.CombineXYZ()

    sep.o[1] >> comb2.i[2]

tree

We can replicate part of a PCA analysis, getting the mean difference of the position field, scaling and combining into a matrix.

with g.tree() as tree:
    pos = g.Position()
    diff = g.FieldAverage.point.vector(pos).o.mean - pos
    matrix = g.CombineMatrix()

    for i, axis1 in enumerate(diff):
        sep = g.FieldAverage.point.vector(diff * axis1)
        for j, axis2 in enumerate(sep.o.mean):
            axis2 >> matrix.i[int(i * 4 + j)]

tree

with g.tree() as tree:
    pos = g.Position().o.position

    _ = g.SetPosition(g.Cube(), position=pos.x, offset=pos.y)

tree

with g.tree() as tree:
    mat = g.CombineMatrix().o.matrix
    mat.translation * 0.5
    mat.rotation >> g.RotateRotation()
    mat.scale + 0.5

tree

with g.tree() as tree:
    col = g.CombineColor().o.color
    col.r + 10
    col.g + 0.5
    col.b * 0.3
    col.a - 0.3
tree