ShaderNodes

Bases: Tree

Source code in core/shadernodes.py

class ShaderNodes(Tree):
    def __init__(self, 
            tree_name        : str,
            *,
            fake_user        : bool = False, 
            is_group         : bool = False, 
            prefix           : Optional[str] = None,
            replace_material : bool = False, 
            color_tag        : str = 'NONE',
            ):
        """ > ShaderNodes

        Parameters
        ----------
        tree_name : str
            Shader Nodes name

        fake_user : bool, optional
            set fake_user flag default=False.

        is_group : bool, optional
            tree is a group default=False.

        prefix : str, optional
            name prefix default=None.

        replace_material : bool, optional
            replace material if already exists default=False.

        color_tag : str, default='NONE'
            group or modifier color_tag attribute (groups only)
        """
        super().__init__(
            tree_name, 
            tree_type='ShaderNodeTree', 
            fake_user=fake_user, 
            is_group=is_group, 
            prefix=prefix, 
            replace_material=replace_material,
            color_tag = color_tag,
            )

    # =============================================================================================================================
    # Input Node

    @property
    def input_node(self) -> Node:
        if not self._is_group:
            raise NodeError(f"ShaderNodes '{self._material.name}' is not a group, it doesn't have an input node")
        return super().input_node

    # ====================================================================================================
    # Tree output

    @property
    def output_node(self) -> Node:
        if self._is_group:
            return super().output_node

        for node in self._nodes.values():
            if node._bnode.bl_idname ==  'ShaderNodeOutputMaterial':
                return node

        return Node('ShaderNodeOutputMaterial')

    def get_output_node(self, target: str = 'ALL') -> Node:
        """ Output node

        Standard behavior if Group or within a zone
        """

        # ---------------------------------------------------------------------------
        # Group or within a zone
        # ---------------------------------------------------------------------------

        if self._is_group:
            return super().get_output_node()

        if len(self._output_stack):
            return self._output_stack[-1]

        # ---------------------------------------------------------------------------
        # Output to shader outpout
        # ---------------------------------------------------------------------------

        for node in self._nodes.values():
            if node._bnode.bl_idname == 'ShaderNodeOutputMaterial' and node._bnode.target == target:
                return node
        node = Node('ShaderNodeOutputMaterial')
        node._bnode.target = target
        return node

    def set_surface(self, value: Any, target: str ='ALL') -> None:
        node = self.get_output_node(target=target)
        node.set_input_socket('Surface', value)

    def set_volume(self, value: Any, target: str ='ALL') -> None:
        node = self.get_output_node(target=target)
        node.set_input_socket('Volume', value)

    def set_displacement(self, value: Any, target: str ='ALL') -> None:
        node = self.get_output_node(target=target)
        node.set_input_socket('Displacement', value)

    def set_thickness(self, value: Any, target: str ='ALL') -> None:
        node = self.get_output_node(target=target)
        node.set_input_socket('Thickness', value)

    @property
    def surface(self) -> None:
        raise NodeError(f"Material 'surface' is write only")

    @surface.setter
    def surface(self, value: Any) -> None:
        if isinstance(value, tuple):
            self.set_surface(value[0], target=value[1])
        else:
            self.set_surface(value)

    @property
    def volume(self) -> None:
        raise NodeError(f"Material 'volume' is write only")

    @volume.setter
    def volume(self, value: Any) -> None:
        if isinstance(value, tuple):
            self.set_volume(value[0], target=value[1])
        else:
            self.set_volume(value)

    @property
    def displacement(self) -> None:
        raise NodeError(f"Material 'displacement' is write only")

    @displacement.setter
    def displacement(self, value: Any) -> None:
        if isinstance(value, tuple):
            self.set_displacement(value[0], target=value[1])
        else:
            self.set_displacement(value)

    @property
    def thickness(self) -> None:
        raise NodeError(f"Material 'thickness' is write only")

    @thickness.setter
    def thickness(self, value: Any) -> None:
        if isinstance(value, tuple):
            self.set_thickness(value[0], target=value[1])
        else:
            self.set_thickness(value)

    def aov_output(self, name: Optional[str] =None, color: Optional[Any] =None, value: Optional[Any] =None) -> None:
        node = Node('AOV Output', {'Color': color, 'Value': value}, aov_name=name)

__init__(tree_name, *, fake_user=False, is_group=False, prefix=None, replace_material=False, color_tag='NONE')

ShaderNodes

Parameters:

Name	Type	Description	Default
tree_name	str	Shader Nodes name	required
fake_user	bool	set fake_user flag default=False.	False
is_group	bool	tree is a group default=False.	False
prefix	str	name prefix default=None.	None
replace_material	bool	replace material if already exists default=False.	False
color_tag	str	group or modifier color_tag attribute (groups only)	'NONE'

Source code in core/shadernodes.py

def __init__(self, 
        tree_name        : str,
        *,
        fake_user        : bool = False, 
        is_group         : bool = False, 
        prefix           : Optional[str] = None,
        replace_material : bool = False, 
        color_tag        : str = 'NONE',
        ):
    """ > ShaderNodes

    Parameters
    ----------
    tree_name : str
        Shader Nodes name

    fake_user : bool, optional
        set fake_user flag default=False.

    is_group : bool, optional
        tree is a group default=False.

    prefix : str, optional
        name prefix default=None.

    replace_material : bool, optional
        replace material if already exists default=False.

    color_tag : str, default='NONE'
        group or modifier color_tag attribute (groups only)
    """
    super().__init__(
        tree_name, 
        tree_type='ShaderNodeTree', 
        fake_user=fake_user, 
        is_group=is_group, 
        prefix=prefix, 
        replace_material=replace_material,
        color_tag = color_tag,
        )

add_method(target_class, func_name=None, self_attr=None, ret_class=None, **fixed)

Add a method calling the Group.

Parameters:

Name	Type	Description	Default
target_class	type	class to add the method to	required
func_name	str	name of the method to create (snae case version of group name if None) default=None.	None
self_attr	str	self name attribute name default=None.	None
ret_class	type	class to use to transtype the output socket default=None.	None
fixed	dict	fixed values for sockets	{}

Source code in core/treeclass.py

def add_method(self, 
    target_class    : type, 
    func_name       : str = None,
    self_attr       : str = None, 
    ret_class       : type = None, 
    **fixed):
    """ Add a method calling the Group.

    Parameters
    ----------
    target_class : type
        class to add the method to

    func_name : str, optional
        name of the method to create (snae case version of group name if None) default=None.

    self_attr : str, optional
        self name attribute name default=None.

    ret_class : type, optional
        class to use to transtype the output socket default=None.

    fixed : dict
        fixed values for sockets        

    """
    from .nodeclass import Group

    group_name = self._btree.name
    if self._prefix != "":
        group_name = group_name[len(self._prefix) + 1:]

    Group.add_method(group_name, target_class,
        func_name       = func_name,
        self_attr       = self_attr, 
        ret_class       = ret_class, 
        prefix          = self._prefix,
        **fixed)

arrange()

Arrange the nodes in the editor.

Try to arrange properly the nodes from left to right.

This method is called when the Tree is poped from the stack.

Returns:

Type	Description
None

Source code in core/treeclass.py

def arrange(self):
    """ > Arrange the nodes in the editor.

    Try to arrange properly the nodes from left to right.

    This method is called when the Tree is poped from the stack.

    Returns
    -------
    None
    """
    if self._use_arrange:
        treearrange.arrange(self._btree)

clear(keep_nodes=True)

Clear the content of the Tree.

Remove all the nodes in the Tree.

Source code in core/treeclass.py

def clear(self, keep_nodes: bool = True):
    """ Clear the content of the Tree.

    Remove all the nodes in the Tree.
    """
    self._nodes.clear()

    # Keep menu switch nodes to preserver input links
    # They will be deleted at the end

    if keep_nodes:
        del_nodes = []
        self._kept_nodes = []
        for bnode in self._btree.nodes:
            if bnode.bl_idname in ['GeometryNodeMenuSwitch', 'NodeGroupInput']:
                self._kept_nodes.append(bnode)
            else:
                del_nodes.append(bnode)

        for bnode in del_nodes:
            self._btree.nodes.remove(bnode)

    else:
        self._btree.links.clear()
        self._btree.nodes.clear()

create_input_socket(bl_idname, name, panel='', **props)

Create a new input socket.

This is an input socket of the zone, hence an output socket of the input node.

Parameters:

Name	Type	Description	Default
bl_idname	str	Socket bl_idname	required
name	str	Socket name	required
panel	str	Panel to place the socket in	''
**props	dict	Properties specific to interface socket	{}

Returns:

Type	Description
Socket

Source code in core/treeclass.py

def create_input_socket(self, bl_idname, name, panel="", **props):
    """ Create a new input socket.

    This is an **input socket** of the zone, hence an **output socket** of the input node.

    Parameters
    ----------
    bl_idname : str
        Socket bl_idname

    name : str
        Socket name

    panel : str, optional
        Panel to place the socket in

    **props : dict, optional
        Properties specific to interface socket


    Returns
    -------
    Socket
    """        
    input_node = self.get_input_node()
    socket = input_node.create_socket('OUTPUT', bl_idname, name, panel=panel, **props)
    def_val = props.get('default_value')
    if def_val is not None:
        try:
            utils.get_bsocket(socket).default_value = def_val
        except Exception as e:
            print(f"WARNING Tree.create_input_socket: {str(e)}")

    return socket

current_tree() staticmethod

Get the Current Tree.

Returns None if no tree is currently open

Returns:

Type	Description
Tree	current tree or None

Source code in core/treeclass.py

@staticmethod
def current_tree():
    """ > Get the Current Tree.

    Returns None if no tree is currently open

    Returns
    -------
    Tree
        current tree or None

    """
    if len(Tree.TREE_STACK):
        return Tree.TREE_STACK[-1]
    else:
        return None

get_output_node(target='ALL')

Output node

Standard behavior if Group or within a zone

Source code in core/shadernodes.py

def get_output_node(self, target: str = 'ALL') -> Node:
    """ Output node

    Standard behavior if Group or within a zone
    """

    # ---------------------------------------------------------------------------
    # Group or within a zone
    # ---------------------------------------------------------------------------

    if self._is_group:
        return super().get_output_node()

    if len(self._output_stack):
        return self._output_stack[-1]

    # ---------------------------------------------------------------------------
    # Output to shader outpout
    # ---------------------------------------------------------------------------

    for node in self._nodes.values():
        if node._bnode.bl_idname == 'ShaderNodeOutputMaterial' and node._bnode.target == target:
            return node
    node = Node('ShaderNodeOutputMaterial')
    node._bnode.target = target
    return node

get_signature(include=None, exclude=[], enabled_only=True, with_sockets=False)

Build the closure signature of the tree.

The closure signature is the tuple made of the output signature of the input node and the input signature of the output node

Returns:

Type	Description
Signature

Source code in core/treeclass.py

def get_signature(self, include: list = None, exclude: list = [], enabled_only=True, with_sockets: bool = False):
    """ Build the closure signature of the tree.

    The closure signature is the tuple made of the output signature of the input node
    and the input signature of the output node

    Returns
    -------
    Signature
    """
    return Signature(
        self.input_node.get_signature(
            include         = include,
            exclude         = exclude,
            enabled_only    = enabled_only,
            with_sockets    = with_sockets).outputs,
        self.output_node.get_signature(
            enabled_only    = enabled_only,
            with_sockets    = with_sockets).inputs)

is_geonodes() classmethod

Current Tree is Geometry Nodes.

Returns:

Type	Description
True if Tree is GeoNodes, False otherwise

Source code in core/treeclass.py

@classmethod
def is_geonodes(cls):
    """ > Current Tree is Geometry Nodes.

    Returns
    -------
    True if Tree is GeoNodes, False otherwise
    """
    return cls.current_tree()._btree.bl_idname == 'GeometryNodeTree'

is_shader() classmethod

Current Tree is Shader Nodes.

Returns:

Type	Description
True if Tree is ShaderNodes, False otherwise

Source code in core/treeclass.py

@classmethod
def is_shader(cls):
    """ > Current Tree is Shader Nodes.

    Returns
    -------
    True if Tree is ShaderNodes, False otherwise
    """
    return cls.current_tree()._btree.bl_idname == 'ShaderNodeTree'

link(out_socket, in_socket, handle_dynamic_sockets=False)

Create a link between two sockets.

Parameters:

Name	Type	Description	Default
out_socket	socket	a node output socket	required
in_socket	socket	input socket from another node	required

Returns:

Type	Description
Link

Source code in core/treeclass.py

def link(self, out_socket, in_socket, handle_dynamic_sockets=False):
    """ > Create a link between two sockets.

    Parameters
    ----------
    out_socket : socket
        a node output socket

    in_socket : socket
        input socket from another node


    Returns
    -------
    Link
    """

    #if hasattr(out_socket, '_bsocket'):
    if '_bsocket' in dir(out_socket):
        out_socket = out_socket._bsocket

    #if hasattr(in_socket, '_bsocket'):
    if '_bsocket' in dir(in_socket):
        in_socket = in_socket._bsocket

    link = self._btree.links.new(out_socket, in_socket, handle_dynamic_sockets=handle_dynamic_sockets)

    utils.check_link(link)
    utils.check_zones(self._btree)

    return link

pop(error=False)

Remove this tree from the stack

Important

This methods shouldn't be called directly, better use a with context block.

Raises:

Type	Description
NodeError	if this tree is not the current one
``` python
with Tree("My Name"):	pass
```

Source code in core/treeclass.py

def pop(self, error=False):
    """ > Remove this tree from the stack

    !!! important
        This methods shouldn't be called directly, better use a **with** context block.

    Raises
    ------
    NodeError
        if this tree is not the current one


    ``` python
    with Tree("My Name"):
        pass
    ```
    """
    # ---------------------------------------------------------------------------
    # Ignore changes
    # ---------------------------------------------------------------------------

    if self.ignore:
        print(f"CHANGES IGNORED : Material '{self._btree.name}' already exists. Use 'replace_material=True' to overwite it.")

        assert self._btree.bl_idname == 'ShaderNodeTree'
        assert self._material is not None

        bpy.data.materials.remove(self._material)
        self._btree = None

        return

    if self._loaded:
        return

    # ---------------------------------------------------------------------------
    # Finalize
    # ---------------------------------------------------------------------------

    # Remove kept nodes
    for bnode in self._kept_nodes:
        self._btree.nodes.remove(bnode)

    # Adjust menu inputs
    if self._has_tree and not error:
        for node in self._nodes.values():
            if '_default_menu' in node.__slots__:
                node._tree_is_completed(self._mod_vals)

        innode = self.input_node
        for bsock in innode._bnode.outputs:
            if bsock.type != 'MENU' or not bsock.is_linked:
                continue
            isock = self._interface.by_identifier(bsock.identifier)
            enums = list(utils.get_enums(isock, 'default_value'))
            if not len(enums):
                continue

            for mod in self.get_modifiers().values():

                cur_val = mod.get(bsock.identifier)
                if cur_val is not None and (cur_val < 2 or cur_val > len(enums) + 2):
                    mod[bsock.identifier] = enums.index(isock.default_value) + 2


    # Check dead ends
    warnings = 0
    if not error:
        warnings = self.check_warnings()

    # Remove from stack
    tree = Tree.TREE_STACK.pop()
    if tree != self:
        raise RuntimeError(f"Error in tree stack management")

    # Empty the interface bin
    if (not error) and self._interface is not None:
        self._interface.empty_bin()

    # Last node in error
    if error and len(self._nodes):
        for node in reversed(self._nodes.values()):
            if node._bnode.bl_idname in ['NodeGroupOutput', 'NodeGroupInput']:
                continue
            utils.set_node_error(node._bnode)
            break

    # Arrange the nodes
    self.arrange()

    # Stats
    if self._btree.bl_idname == 'ShaderNodeTree' and self._material is not None:
        name = f"Material '{self._material.name}'"
    else:
        name = f"Tree '{self._btree.name}'"

    print(f"{name} built: {self._str_stats}, warnings: {warnings}")

    Tree._total_nodes += len(self._btree.nodes)
    Tree._total_links += len(self._btree.links)      

push()

Make this tree zone the current one

Important

This methods shouldn't be called directly, better use a with context block.

with Tree("My Name"):
    pass

Source code in core/treeclass.py

def push(self):
    """ > Make this tree zone the current one

    !!! important
        This methods shouldn't be called directly, better use a **with** context block.

    ``` python
    with Tree("My Name"):
        pass
    ```
    """
    Tree.TREE_STACK.append(self)
    return self

register_node(node)

Register a new Node.

This method is called by the Node class constructor. Never call directly.

Registered Nodes are stored in the dictionary : _nodes = bpy.types.Node.name -> Node

Parameters:

Name	Type	Description	Default
node	Node	the newly created Node to register	required

Returns:

Type	Description
Node	the passed argument

Source code in core/treeclass.py

def register_node(self, node):
    """ Register a new Node.

    This method is called by the Node class constructor. Never call directly.

    Registered Nodes are stored in the dictionary : _nodes = bpy.types.Node.name -> Node

    Parameters
    ----------
    node : Node
        the newly created Node to register


    Returns
    -------
    Node
        the passed argument

    """

    self._nodes[node._bnode.name] = node
    if len(self._layouts):
        self._layouts[-1].include_node(node)

    node._stack = NodeError.stack_lines()

    if self._input_node is None and node._bnode.bl_idname == 'NodeGroupInput':
        self._input_node = node

    if self._output_node is None and node._bnode.bl_idname == 'NodeGroupOutput':
        self._output_node = node

    return node

remove_groups(names=None, prefix=None, geonodes=True, shadernodes=True) staticmethod

Remove Groups created by GeoNodes.

Important

This method can only remove groups created by GeoNodes.

Parameters:

Name	Type	Description	Default
names	str or list of strs	name of the node groups to remove (all if None)	None
prefix	str	name prefix for the groups to delete	None
geonodes	bool	remove geometry nodes groups	True
shadernodes	bool	remove shader nodes groups	True

Returns:

Type	Description
None

Source code in core/treeclass.py

@staticmethod
def remove_groups(names=None, prefix=None, geonodes=True, shadernodes=True):
    """ > Remove Groups created by GeoNodes.

    !!! important
         This method can only remove groups created by **GeoNodes**.

    Parameters
    ----------
    names : str or list of strs, optional
        name of the node groups to remove (all if None)

    prefix : str, optional
        name prefix for the groups to delete

    geonodes : bool, default=True
        remove geometry nodes groups

    shadernodes : bool, default=True
        remove shader nodes groups


    Returns
    -------
    None
    """

    groups = []
    if prefix is None:
        prefix_ = ""
    else:
        prefix_ = prefix + ' '

    tree_types = []
    if geonodes:
        tree_types.append('GeometryNodeTree')
    if shadernodes:
        tree_types.append('ShaderNodeTree')

    for group in bpy.data.node_groups:
        if group.bl_idname not in tree_types:
            continue

        if not group.description.startswith('GEONODES'):
            continue

        if prefix is not None and group.name[:len(prefix_)] != prefix_:
            continue

        if names is None:
            pass
        elif isinstance(names, str):
            if group.name != prefix_ + names:
                continue
        elif isinstance(names, list):
            ok = False
            for name in names:
                if group.name == prefix_ + name:
                    ok = True
                    break
            if not ok:
                continue
        else:
            raise Exception(f"Argument names '{names}' is not valid: None, str or list of strs expected")

        groups.append(group)

    print("Remove node groups")
    for group in groups:
        print(' -', group.name)
        bpy.data.node_groups.remove(group)

    print(f"{len(groups)} node groups removed")