mantis/misc_nodes.py

from .utilities.node_common import *
from .base_definitions import MantisNode, NodeSocket, FLOAT_EPSILON
from .xForm_nodes import xFormArmature, xFormBone
from .misc_nodes_socket_templates import *
from math import pi, tau

def TellClasses():
    return [
             # utility
             InputFloat,
             InputIntNode,
             InputVector,
             InputBoolean,
             InputBooleanThreeTuple,
             InputRotationOrder,
             InputTransformSpace,
             InputString,
             InputMatrix,
             InputWidget,
             InputExistingGeometryObject,
             InputExistingGeometryData,
             InputThemeBoneColorSets,
             InputColorSetPallete,
             UtilityCustomProperty,
             UtilityDeclareCollections,
             UtilityCollectionJoin,
             UtilityCollectionHierarchy,
             UtilityGeometryOfXForm,
             UtilityNameOfXForm,
             UtilityPointFromCurve,
             UtilityMatrixFromCurve,
             UtilityMatricesFromCurve,
             UtilityNumberOfCurveSegments,
             UtilityNumberOfSplines,
             UtilityMatrixFromCurveSegment,
             UtilityGetCurvePoint,
             UtilityGetNearestFactorOnCurve,
             UtilityKDChoosePoint,
             UtilityKDChooseXForm,
             UtilityMetaRig,
             UtilityBoneProperties,
             UtilityDriverVariable,
             UtilityDriver,
             UtilityFCurve,
             UtilityKeyframe,
             UtilitySwitch,
             UtilityCombineThreeBool,
             UtilityCombineVector,
             UtilitySeparateVector,
             UtilityCatStrings,
             UtilityGetBoneLength,
             UtilityPointFromBoneMatrix,
             UtilitySetBoneLength,
             UtilityMatrixSetLocation,
             UtilityMatrixGetLocation,
             UtilityMatrixFromXForm,
             UtilityAxesFromMatrix,
             UtilityBoneMatrixHeadTailFlip,
             UtilityMatrixTransform,
             UtilityMatrixInvert,
             UtilityMatrixCompose,
             UtilityMatrixAlignRoll,
             UtilityTransformationMatrix,
             UtilityIntToString,
             UtilityArrayGet,
             UtilityArrayLength,
             UtilitySetBoneMatrixTail,
             # Control flow switches
             UtilityCompare,
             UtilityChoose,
             # useful NoOp:
             UtilityPrint,
            ]

def matrix_from_head_tail(head, tail, normal=None):
    from mathutils import Vector, Matrix
    if normal is None:
        rotation = Vector((0,1,0)).rotation_difference((tail-head).normalized()).to_matrix()
        m= Matrix.LocRotScale(head, rotation, None)
    else: # construct a basis matrix
        m = Matrix.Identity(3)
        axis = (tail-head).normalized()
        conormal = axis.cross(normal)
        m[0]=conormal
        m[1]=axis
        m[2]=normal
        m = m.transposed().to_4x4()
        m.translation=head.copy()
    m[3][3]=(tail-head).length
    return m

def get_mesh_from_curve(curve_name : str, execution_id : str, bContext, ribbon=True):
        from bpy import data
        curve = data.objects.get(curve_name)
        assert curve.type == 'CURVE', f"ERROR: object is not a curve: {curve_name}"
        from .utilities.utilities import mesh_from_curve
        curve_type='ribbon' if ribbon else 'wire'
        m_name = curve_name+'.'+str(hash(curve_name+'.'+curve_type+'.'+execution_id))
        if not (m := data.meshes.get(m_name)):
            m = mesh_from_curve(curve, bContext, ribbon)
            m.name = m_name
        return m

def cleanup_curve(curve_name : str, execution_id : str) -> None:
        import bpy
        curve = bpy_object_get_guarded(curve_name)
        m_name = curve_name+'.'+str(hash(curve.name+'.'+ execution_id))
        if (mesh := bpy.data.meshes.get(m_name)):
            bpy.data.meshes.remove(mesh)

def kd_find(node, points, ref_pt, num_points):
        if num_points == 0:
            raise RuntimeError(f"Cannot find 0 points for {node}")
        from mathutils import kdtree
        kd = kdtree.KDTree(len(points))
        for i, pt in enumerate(points):
            try:
                kd.insert(pt, i)
            except (TypeError, ValueError) as e:
                prRed(f"Cannot get point from for {node}")
                raise e
        kd.balance()
        try:
            if num_points == 1: # make it a list to keep it consistent with
                result = [kd.find(ref_pt)] # find_n which returns a list
            else:
                result = kd.find_n(ref_pt, num_points)
            # the result of kd.find has some other stuff we don't care about
        except (TypeError, ValueError) as e:
            prRed(f"Reference Point {ref_pt} invalid for {node}")
            raise e
        return result

def array_link_init_hierarchy(new_link):
    " Sets up hierarchy connection/dependencies for links created by Arrays."
    if new_link.is_hierarchy:
        connections = new_link.from_node.hierarchy_connections
        dependencies = new_link.to_node.hierarchy_dependencies
    else:
        connections = new_link.from_node.connections
        dependencies = new_link.to_node.dependencies
    connections.append(new_link.to_node)
    dependencies.append(new_link.from_node)

def array_choose_relink(node, indices, array_input, output, ):
    """
        Used to choose the correct link to send out of an array-choose node.
    """
    keep_links = []
    for index in indices:
        l = node.inputs[array_input].links[index]
        keep_links.append(l)
    for link in node.outputs[output].links:
        to_node = link.to_node
        for l in keep_links:
            new_link = l.from_node.outputs[l.from_socket].connect(to_node, link.to_socket)
            array_link_init_hierarchy(new_link)
            node.rerouted.append(new_link) # so I can access this in Schema Solve
        link.die()


def array_choose_data(node, data, output):
    """
        Used to choose the correct data to send out of an array-choose node.
    """
    # We need to make new outputs and link from each one based on the data in the array...
    for i in range(len(data)):
        name = output+"."+str(i).zfill(4)
        node.outputs[name] = NodeSocket(node=node, name=name, is_input=False)
    for i, data_item in enumerate(data):
        node.parameters[output+"."+str(i).zfill(4)] = data_item
    for link in node.outputs[output].links:
        to_node = link.to_node
        for i in range(len(data)):
            # Make a link from the new output.
            new_link = node.outputs[output+"."+str(i).zfill(4)].connect(to_node, link.to_socket)
            array_link_init_hierarchy(new_link)
        link.die()

def zero_radius_error_message(node, curve):
    return f"ERROR: cannot get matrix from zero-radius curve point "\
            "in curve object: {curve.name} for node: {node}. "\
            "This is a limitation of Mantis (For now). Please inspect the curve and ensure "\
            "that each curve point has a radius greater than 0. Sometimes, this error is " \
            "caused by drivers. "

def bpy_object_get_guarded(get_name, node=None):
    result=None
    if not isinstance(get_name, str):
        raise RuntimeError(f"Cannot get object for {node} because the """
                   f"requested name is not a string, but {type(get_name)}. ")

    try:
        import bpy
        result = bpy.data.objects.get(get_name)
    except SystemError:
        raise SystemError(f"184 {node} Cannot get object, {get_name}"
                          " please report this as a bug.")
    return result

#*#-------------------------------#++#-------------------------------#*#
# B A S E  C L A S S E S
#*#-------------------------------#++#-------------------------------#*#

class MantisMiscNode(MantisNode):
    __slots__ = ()
    node_type='UTILITY'

class SimpleInputNode(MantisMiscNode):
    __slots__ = ()
    node_type = 'UTILITY'
    def __init__(self, signature, base_tree, socket_templates=[], additional_parameters={}):
        super().__init__(signature, base_tree, socket_templates, additional_parameters)
        self.prepared, self.executed = True, True

#*#-------------------------------#++#-------------------------------#*#
# U T I L I T Y   N O D E S
#*#-------------------------------#++#-------------------------------#*#

class InputFloat(SimpleInputNode):
    '''A node representing float input'''
    __slots__ = ()
    socket_templates = InputFloatSockets

class InputIntNode(SimpleInputNode):
    '''A node representing integer input'''
    __slots__ = ()
    socket_templates = InputIntSockets

class InputVector(SimpleInputNode):
    '''A node representing vector input'''
    __slots__ = ()
    socket_templates = InputVectorSockets

class InputBoolean(SimpleInputNode):
    '''A node representing boolean input'''
    __slots__ = ()
    socket_templates = InputBooleanSockets

class InputBooleanThreeTuple(SimpleInputNode):
    '''A node representing a tuple of three booleans'''
    __slots__ = ()
    socket_templates = InputBooleanThreeTupleSockets

class InputRotationOrder(SimpleInputNode):
    '''A node representing string input for rotation order'''
    __slots__ = ()
    socket_templates = InputRotationOrderSockets

class InputTransformSpace(SimpleInputNode):
    '''A node representing string input for transform space'''
    __slots__ = ()
    socket_templates = InputTransformSpaceSockets

class InputString(SimpleInputNode):
    '''A node representing string input'''
    __slots__ = ()
    socket_templates = InputStringSockets

class InputMatrix(SimpleInputNode):
    '''A node representing axis-angle quaternion input'''
    __slots__ = ()
    socket_templates = InputMatrixSockets

class InputThemeBoneColorSets(SimpleInputNode):
    '''A node representing the theme's colors'''
    __slots__ = ()
    socket_templates = None

    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree)
        from .mantis_dataclasses import MantisSocketTemplate
        outputs = []
        for i in range(20):
            outputs.append (MantisSocketTemplate(
                name = f"Color {str(i).zfill(2)}",
            ))
        self.outputs.init_sockets(outputs)
        self.init_parameters()

    def fill_parameters(self, ui_node=None):
        if not ui_node:
            from .utilities.utilities import get_ui_node
            ui_node = get_ui_node(self.ui_signature, self.base_tree)
        for i in range(20):
            self.parameters[f"Color {str(i).zfill(2)}"] = ui_node.outputs[i].default_value
        return super().fill_parameters(ui_node)

class InputColorSetPallete(SimpleInputNode):
    '''A node representing the theme's colors'''
    __slots__ = ()
    socket_templates = None

    def fill_parameters(self, ui_node=None):
        if not ui_node:
            from .utilities.utilities import get_ui_node
            ui_node = get_ui_node(self.ui_signature, self.base_tree)
        from .mantis_dataclasses import MantisSocketTemplate
        outputs = []
        for o in ui_node.outputs:
            outputs.append (MantisSocketTemplate( name = o.name,))
        self.outputs.init_sockets(outputs)
        self.init_parameters()
        for o in ui_node.outputs:
            self.parameters[o.name] = o.default_value
        return super().fill_parameters(ui_node)


class UtilityCustomProperty(MantisMiscNode):
    __slots__ = ()
    socket_templates = UtilityCustomPropertySockets
    # TODO this should output a dataclass containing custom prop info
    # then the xForm will use it to assign custom properties

    def bPrepare(self, bContext=None):
        from .mantis_dataclasses import custom_prop_template
        # it's kind of silly to do it this way, but whatever 
        name = self.evaluate_input("Name")
        assert name, "The custom property must have a name."
        prop_type = self.evaluate_input("Type")
        kwargs = {
            "name"        : name,
            "prop_type"   : prop_type,
            "description" : self.evaluate_input("Description"),
        }
        match prop_type:
            case 'BOOL':
                kwargs['default_value_bool'] = self.evaluate_input("Default (Bool)")
            case 'INT':
                kwargs['default_value_int'] = self.evaluate_input("Default (Int)")
                kwargs['min'] = self.evaluate_input("Min (Int)")
                kwargs['soft_min'] = self.evaluate_input("Soft Min (Int)")
                kwargs['max'] = self.evaluate_input("Max (Int)")
                kwargs['soft_max'] = self.evaluate_input("Soft Max (Int)")
            case 'FLOAT':
                kwargs['default_value_float'] = self.evaluate_input("Default (Float)")
                kwargs['min'] = self.evaluate_input("Min (Float)")
                kwargs['soft_min'] = self.evaluate_input("Soft Min (Float)")
                kwargs['max'] = self.evaluate_input("Max (Float)")
                kwargs['soft_max'] = self.evaluate_input("Soft Max (Float)")
            case 'VECTOR':
                kwargs['default_value_vector'] = self.evaluate_input("Default (Vector)")
                kwargs['min'] = self.evaluate_input("Min (Float)")
                kwargs['soft_min'] = self.evaluate_input("Soft Min (Float)")
                kwargs['max'] = self.evaluate_input("Max (Float)")
                kwargs['soft_max'] = self.evaluate_input("Soft Max (Float)")
            case 'STRING':
                kwargs['default_value_string'] = self.evaluate_input("Default (String)")
        my_data = custom_prop_template( **kwargs)
        self.parameters['Custom Property'] = my_data
        self.prepared = True; self.executed = True

class UtilityMatrixFromCurve(MantisMiscNode):
    '''Get a matrix from a curve'''
    __slots__ = ()
    socket_templates = MatrixFromCurveSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Matrix
        import bpy
        mat = Matrix.Identity(4)
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        mode = self.evaluate_input("Mode")
        # DIVISIONS, FACTOR
        if not curve:
            prRed(f"WARN: No curve found for {self}. Using an identity matrix instead.")
            mat[3][3] = 1.0
        elif curve.type != "CURVE":
            prRed(f"WARN: Object {curve.name} is not a curve. Using an identity matrix instead.")
            mat[3][3] = 1.0
        else:
            if bContext is None: bContext = bpy.context # is this wise?
            m = get_mesh_from_curve(curve.name, self.base_tree.execution_id, bContext)
            from .utilities.utilities import data_from_ribbon_mesh
            #
            num_divisions = self.evaluate_input("Total Divisions")
            if mode == 'DIVISIONS' and num_divisions <= 0:
                raise GraphError("The number of divisions in the curve must be 1 or greater.")
            m_index = self.evaluate_input("Matrix Index")
            if mode == 'DIVISIONS' and m_index >= num_divisions:
                prRed(m_index, num_divisions)
                raise GraphError(f"{self} tried to get a matrix-index greater the total number of divisions."
                                  "The matrix index starts at 0. You're probably off by +1.")
            spline_index = self.evaluate_input("Spline Index")
            if spline_index > len(curve.data.splines)-1:
                raise GraphError(f"{self} is attempting to read from a spline in {curve.name} that does not exist."
                                  " Try and reduce the value of Spline Index.")
            splines_factors = [ [] for i in range (spline_index)]
            
            if mode == 'FACTOR':
                factor = self.evaluate_input('Factor')
                factor = min(factor, 1 - 0.0001) # to make our fake tangent work
                factors = [ factor, factor + 0.0001 ]
                # TODO this is technically not accurate, we want the real tangent
                # ... but this should be close enough.
            elif mode == 'FACTOR_WITH_TAIL':
                factor = self.evaluate_input('Factor')
                factor = min(factor, 1 - 0.0001) # to make our fake tangent work
                factors = [ factor,
                            self.evaluate_input('Factor (Tail)')]
            else:  # mode == 'DIVISIONS':
                factors = [1/num_divisions*m_index, 1/num_divisions*(m_index+1)]
            splines_factors.append(factors)
            data = data_from_ribbon_mesh(m, splines_factors, curve.matrix_world)
            if data[spline_index][1][0] < FLOAT_EPSILON: # radius is None:
                raise RuntimeError(zero_radius_error_message(self, curve))
            
            head=data[spline_index][0][0]
            tail= data[spline_index][0][1]
            axis = (tail-head).normalized()
            if axis.length_squared < FLOAT_EPSILON:
                raise RuntimeError(f"Failed to read the curve {curve.name}.")
            normal=data[spline_index][2][0]
            # make sure the normal is perpendicular to the tail
            from .utilities.utilities import make_perpendicular
            normal = make_perpendicular(axis, normal)
            mat = matrix_from_head_tail(head, tail, normal)
            # this is in world space... let's just convert it back
            mat.translation = head - curve.location
            if mode == 'FACTOR':
                mat[3][3]=1.0 # Set the length

            # TODO HACK TODO
            # all the nodes should work in world-space, and it should be the responsibility
            # of the xForm node to convert!

        self.parameters["Matrix"] = mat
        self.prepared = True
        self.executed = True

    def bFinalize(self, bContext=None):
        cleanup_curve(self.evaluate_input("Curve"), self.base_tree.execution_id)

class UtilityPointFromCurve(MantisMiscNode):
    '''Get a point from a curve'''
    __slots__ = ()
    socket_templates = PointFromCurveSockets

    def bPrepare(self, bContext = None,):
        import bpy
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        if not curve:
            raise RuntimeError(f"No curve found for {self}.")
        elif curve.type != "CURVE":
            raise GraphError(f"ERROR: Object {curve.name} is not a curve.")
        else:
            if bContext is None: bContext = bpy.context # is this wise?
            m = get_mesh_from_curve(curve.name, self.base_tree.execution_id, bContext)
            from .utilities.utilities import data_from_ribbon_mesh
            #
            num_divisions = 1
            spline_index = self.evaluate_input("Spline Index")
            splines_factors = [ [] for i in range (spline_index)]
            factors = [self.evaluate_input("Factor")]
            splines_factors.append(factors)
            data = data_from_ribbon_mesh(m, splines_factors, curve.matrix_world)
            p = data[spline_index][0][0] - curve.location
        self.parameters["Point"] = p
        self.prepared, self.executed = True, True

    def bFinalize(self, bContext=None):
        cleanup_curve(self.evaluate_input("Curve"), self.base_tree.execution_id)

class UtilityMatricesFromCurve(MantisMiscNode):
    '''Get matrices from a curve'''
    __slots__ = ()
    socket_templates = MatricesFromCurveSockets

    def bPrepare(self, bContext = None,):
        import time
        # start_time = time.time()
        #
        from mathutils import Matrix
        import bpy
        m = Matrix.Identity(4)
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        if not curve:
            prRed(f"WARN: No curve found for {self}. Using an identity matrix instead.")
            m[3][3] = 1.0
        elif curve.type != "CURVE":
            prRed(f"WARN: Object {curve.name} is not a curve. Using an identity matrix instead.")
            m[3][3] = 1.0
        else:
            if bContext is None: bContext = bpy.context # is this wise?
            mesh = get_mesh_from_curve(curve.name, self.base_tree.execution_id, bContext)
            from .utilities.utilities import data_from_ribbon_mesh
            num_divisions = self.evaluate_input("Total Divisions")
            spline_index = self.evaluate_input("Spline Index")
            splines_factors = [ [] for i in range (spline_index)]
            factors = [0.0] + [(1/num_divisions*(i+1)) for i in range(num_divisions)]
            splines_factors.append(factors)
            data = data_from_ribbon_mesh(mesh, splines_factors, curve.matrix_world)
            # [spline_index][points,tangents,normals][datapoint_index]
            from .utilities.utilities import make_perpendicular
            matrices=[]
            for i in range(num_divisions):
                if data[spline_index][1][i] < FLOAT_EPSILON: # radius is None:
                    raise RuntimeError(zero_radius_error_message(self, curve))
                m = matrix_from_head_tail (
                data[spline_index][0][i], data[spline_index][0][i+1],
                make_perpendicular((data[spline_index][0][i+1]-data[spline_index][0][i]).normalized(), data[spline_index][2][i]),)
                m.translation = data[spline_index][0][i] - curve.location
                matrices.append(m)

        for link in self.outputs["Matrices"].links:
            for i, m in enumerate(matrices):
                name = "Matrix"+str(i).zfill(4)
                if not (out := self.outputs.get(name)): # reuse them if there are multiple links.
                    out = self.outputs[name] = NodeSocket(name = name, node=self)
                c = out.connect(link.to_node, link.to_socket)
                # prOrange(c)
                self.parameters[name] = m
                # print (mesh)
            link.die()

        self.prepared = True
        self.executed = True
        # prGreen(f"Matrices from curves took {time.time() - start_time} seconds.")

    def bFinalize(self, bContext=None):
        import bpy
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        m_name = curve.name+'.'+self.base_tree.execution_id
        if (mesh := bpy.data.meshes.get(m_name)):
            prGreen(f"Freeing mesh data {m_name}...")
            bpy.data.meshes.remove(mesh)

class UtilityNumberOfCurveSegments(MantisMiscNode):
    __slots__ = ()
    socket_templates = NumberOfCurveSegmentsSockets

    def bPrepare(self, bContext = None,):
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        spline = curve.data.splines[self.evaluate_input("Spline Index")]
        if spline.type == "BEZIER":
            self.parameters["Number of Segments"] = len(spline.bezier_points)-1
        else:
            self.parameters["Number of Segments"] = len(spline.points)-1
        self.prepared = True
        self.executed = True

class UtilityNumberOfSplines(MantisMiscNode):
    __slots__ = ()
    socket_templates = NumberOfSplinesSockets

    def bPrepare(self, bContext = None,):
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        self.parameters["Number of Splines"] = len(curve.data.splines)
        self.prepared, self.executed = True, True

class UtilityMatrixFromCurveSegment(MantisMiscNode):
    __slots__ = ()
    socket_templates = MatrixFromCurveSegmentSockets

    def bPrepare(self, bContext = None,):
        import bpy
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        if not curve:
            raise RuntimeError(f"No curve found for {self}.")
        elif curve.type != "CURVE":
            raise GraphError(f"ERROR: Object {curve.name} is not a curve.")
        else:
            if bContext is None: bContext = bpy.context # is this wise?
            m = get_mesh_from_curve(curve.name, self.base_tree.execution_id, bContext)
            from .utilities.utilities import data_from_ribbon_mesh
            # this section is dumb, but it is because the data_from_ribbon_mesh
            #  function is designed to pull data from many splines at once (for optimization)
            #  so we have to give it empty splines for each one we skip.
            # TODO: Refactor this to make it so I can select spline index
            spline_index = self.evaluate_input("Spline Index")
            spline = curve.data.splines[spline_index]
            splines_factors = [ [] for i in range (spline_index)]
            factors = [0.0]
            points = spline.bezier_points if spline.type == 'BEZIER' else spline.points
            total_length=0.0
            for i in range(len(points)-1):
                total_length+= (seg_length := (points[i+1].co - points[i].co).length)
                factors.append(seg_length)
            prev_length = 0.0
            for i in range(len(factors)):
                factors[i] = prev_length+factors[i]/total_length
                prev_length=factors[i]
                # Why does this happen? Floating point error?
                if factors[i]>1.0: factors[i] = 1.0
            splines_factors.append(factors)
            #
            data = data_from_ribbon_mesh(m, splines_factors, curve.matrix_world)
            segment_index = self.evaluate_input("Segment Index")
            if data[spline_index][1][segment_index] < FLOAT_EPSILON: # radius is None:
                raise RuntimeError(zero_radius_error_message(self, curve))
            head=data[spline_index][0][segment_index]
            tail= data[spline_index][0][segment_index+1]
            axis = (tail-head).normalized()
            normal=data[spline_index][2][segment_index]
            # make sure the normal is perpendicular to the tail
            from .utilities.utilities import make_perpendicular
            normal = make_perpendicular(axis, normal)
            m = matrix_from_head_tail(head, tail, normal)
            m.translation = head - curve.location
            self.parameters["Matrix"] = m
        self.prepared, self.executed = True, True

    def bFinalize(self, bContext=None):
        cleanup_curve(self.evaluate_input("Curve"), self.base_tree.execution_id)

class UtilityGetCurvePoint(MantisMiscNode):
    __slots__ = ()
    socket_templates = GetCurvePointSockets

    def bPrepare(self, bContext=None):
        import bpy
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        if not curve:
            raise RuntimeError(f"No curve found for {self}.")
        elif curve.type != "CURVE":
            raise GraphError(f"ERROR: Object {curve.name} is not a curve.")
        spline = curve.data.splines[self.evaluate_input("Spline Index")]
        if spline.type == 'BEZIER':
            bez_pt = spline.bezier_points[self.evaluate_input("Index")]
            self.parameters["Point"]=bez_pt.co
            self.parameters["Left Handle"]=bez_pt.handle_left
            self.parameters["Right Handle"]=bez_pt.handle_right
        else:
            pt = spline.points[self.evaluate_input("Index")]
            self.parameters["Point"]=(pt.co[0], pt.co[1], pt.co[2])
        self.prepared, self.executed = True, True

class UtilityGetNearestFactorOnCurve(MantisMiscNode):
    __slots__ = ()
    socket_templates = GetNearestFactorOnCurveSockets

    def bPrepare(self, bContext = None,):
        import bpy
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded( curve_name, self)
        if not curve:
            raise RuntimeError(f"No curve found for {self}.")
        elif curve.type != "CURVE":
            raise GraphError(f"ERROR: Object {curve.name} is not a curve.")
        else:
            if bContext is None: bContext = bpy.context # is this wise?
            m = get_mesh_from_curve(curve.name,
                                    self.base_tree.execution_id,
                                    bContext, ribbon=False)
            # this is confusing but I am not re-writing these old functions
            from .utilities.utilities import FindNearestPointOnWireMesh as nearest_point
            spline_index = self.evaluate_input("Spline Index")
            ref_pt = self.evaluate_input("Reference Point")
            splines_points = [ [] for i in range (spline_index)]
            splines_points.append([ref_pt])
            pt =  nearest_point(m, splines_points)[spline_index][0]
            self.parameters["Factor"] = pt
        self.prepared, self.executed = True, True

class UtilityKDChoosePoint(MantisMiscNode):
    __slots__ = ('rerouted')
    socket_templates = KDChoosePointSockets
    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree, self.socket_templates)
        self.rerouted=[]

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        points= []
        ref_point = self.evaluate_input('Reference Point')
        num_points = self.evaluate_input('Number to Find')
        for i, l in enumerate(self.inputs['Points'].links):
            pt = self.evaluate_input('Points', i)
            points.append(pt)
            if not isinstance(pt, Vector):
                prRed(f"Cannot get point from {l.from_node} for {self}")
        assert ref_point is not None, wrapRed(f"Reference Point {ref_point} is invalid in node {self}")
        result = kd_find(self, points, ref_point, num_points)
        indices = [ found_point[1] for found_point in result  ]
        distances  = [ found_point[2] for found_point in result  ]
        array_choose_relink(self, indices, "Points", "Result Point")
        array_choose_data(self, indices, "Result Index")
        array_choose_data(self, distances, "Result Distance")
        self.prepared, self.executed = True, True

class UtilityKDChooseXForm(MantisMiscNode):
    __slots__ = ('rerouted')
    socket_templates = KDChooseXFormSockets
    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree, self.socket_templates)
        self.rerouted=[]

    def bPrepare(self, bContext = None,):
        if len(self.hierarchy_dependencies)==0 and len(self.hierarchy_connections)==0 and \
                 len(self.connections)==0 and len(self.dependencies)==0:
            self.prepared, self.executed = True, True
            return #Either it is already done or it doesn't matter.
        from mathutils import Vector
        points= []
        ref_point = self.evaluate_input('Reference Point')
        num_points = self.evaluate_input('Number to Find')
        for i, l in enumerate(self.inputs['xForm Nodes'].links):
            matrix = l.from_node.evaluate_input('Matrix')
            if matrix is None:
                raise GraphError(f"Cannot get point from {l.from_node} for {self}. Does it have a matrix?")
            pt = matrix.translation
            if head_tail := self.evaluate_input("Get Point Head/Tail"):
                # get the Y-axis of the basis, assume it is normalized
                y_axis = Vector((matrix[0][1],matrix[1][1], matrix[2][1]))
                pt = pt.lerp(pt+y_axis*matrix[3][3], head_tail)
            points.append(pt)
            if not isinstance(pt, Vector):
                prRed(f"Cannot get point from {l.from_node} for {self}")
        assert ref_point is not None, wrapRed(f"Reference Point {ref_point} is invalid in node {self}")
        result = kd_find(self, points, ref_point, num_points)
        indices = [ found_point[1] for found_point in result  ]
        distances  = [ found_point[2] for found_point in result  ]
        array_choose_relink(self, indices, "xForm Nodes", "Result xForm")
        array_choose_data(self, indices, "Result Index")
        array_choose_data(self, distances, "Result Distance")
        self.prepared, self.executed = True, True

class UtilityMetaRig(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = MetaRigSockets

    def bPrepare(self, bContext = None,):
        #kinda clumsy, whatever
        import bpy
        from mathutils import Matrix
        m = Matrix.Identity(4)

        meta_rig  = self.evaluate_input("Meta-Armature")
        if meta_rig is None:
            raise RuntimeError("Invalid input for Meta-Armature.")
        meta_bone = self.evaluate_input("Meta-Bone")
        if meta_rig is None or meta_bone is None:
            raise RuntimeError("Invalid input for Meta-Bone.")

        if meta_rig:
            if ( armOb := bpy.data.objects.get(meta_rig) ):
                m = armOb.matrix_world
                if ( b := armOb.data.bones.get(meta_bone)):
                    # calculate the correct object-space matrix
                    m = Matrix.Identity(3)
                    bones = [] # from the last ancestor, mult the matrices until we get to b
                    while (b): bones.append(b); b = b.parent
                    while (bones): b = bones.pop(); m = m @ b.matrix
                    m = Matrix.Translation(b.head_local) @ m.to_4x4()
                    #
                    m[3][3] = b.length # this is where I arbitrarily decided to store length
                # else:
                #     prRed("no bone for MetaRig node ", self)
        else:
            raise RuntimeError(wrapRed(f"No meta-rig input for MetaRig node {self}"))

        self.parameters["Matrix"] = m
        self.prepared = True
        self.executed = True

class UtilityBoneProperties(SimpleInputNode):
    '''A node representing a bone's gettable properties'''
    __slots__ = ()
    socket_templates = BonePropertiesSockets

    def fill_parameters(self, ui_node=None):
        return

# TODO this should probably be moved to Links
class UtilityDriverVariable(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = DriverVariableSockets
    node_type = "DRIVER"

    def reset_execution(self):
        super().reset_execution()
        # clear this to ensure there are no stale reference pointers
        self.parameters["Driver Variable"] = None
        self.prepared=True

    # NOTE _index for interface consistency
    def evaluate_input(self, input_name, _index=0):
        if input_name == 'Property':
            if self.inputs.get('Property'):
                if self.inputs['Property'].is_linked:
                    trace = trace_single_line(self, input_name)
                    # CANNOT UNDERSTATE HOW CRITICAL THIS CHECK IS
                    if trace[0][-1].node_type == 'XFORM' or isinstance(trace[0][-1], UtilityBoneProperties):
                        return trace[1].name # the name of the socket
            return self.parameters["Property"]
        return super().evaluate_input(input_name)

    def GetxForm(self, index=1):
        trace = trace_single_line(self, "xForm 1" if index == 1 else "xForm 2")
        for node in trace[0]:
            if (node.__class__ in [xFormArmature, xFormBone]):
                return node #this will fetch the first one, that's good!
        return None

    def bRelationshipPass(self, bContext = None,):
        prepare_parameters(self)
        #prPurple ("Executing Driver Variable Node")
        xF1 = self.GetxForm()
        xF2 = self.GetxForm(index=2)
        # kinda clumsy
        xForm1, xForm2 = None, None
        if xF1 : xForm1 = xF1.bGetObject()
        if xF2 : xForm2 = xF2.bGetObject()

        v_type = self.evaluate_input("Variable Type")
        i = self.evaluate_input("Property Index"); dVarChannel = ""
        if not isinstance(i, (int, float)):
            raise RuntimeError(f" {self} has invalid input for \"Property Index\".")
        if (i >= 0): #negative values will use the vector property.
            if self.evaluate_input("Property") == 'location':
                if   i == 0: dVarChannel = "LOC_X"
                elif i == 1: dVarChannel = "LOC_Y"
                elif i == 2: dVarChannel = "LOC_Z"
                else: raise RuntimeError("Invalid property index for %s" % self)
            if self.evaluate_input("Property") == 'rotation':
                if   i == 0: dVarChannel = "ROT_X"
                elif i == 1: dVarChannel = "ROT_Y"
                elif i == 2: dVarChannel = "ROT_Z"
                elif i == 3: dVarChannel = "ROT_W"
                else: raise RuntimeError("Invalid property index for %s" % self)
            if self.evaluate_input("Property") == 'scale':
                if   i == 0: dVarChannel = "SCALE_X"
                elif i == 1: dVarChannel = "SCALE_Y"
                elif i == 2: dVarChannel = "SCALE_Z"
                elif i == 3: dVarChannel = "SCALE_AVG"
                else: raise RuntimeError("Invalid property index for %s" % self)
            if self.evaluate_input("Property") == 'scale_average':
                dVarChannel = "SCALE_AVG"
        if dVarChannel: v_type = "TRANSFORMS"

        my_var = {
            "owner"         : xForm1, # will be filled in by Driver
            "prop"          : self.evaluate_input("Property"), # will be filled in by Driver
            "type"          : v_type,
            "space"         : self.evaluate_input("Evaluation Space"),
            "rotation_mode" : self.evaluate_input("Rotation Mode"),
            "xForm 1"       : xForm1,#self.GetxForm(index = 1),
            "xForm 2"       : xForm2,#self.GetxForm(index = 2),
            "channel"       : dVarChannel,}

        self.parameters["Driver Variable"] = my_var
        print (my_var['prop'])
        self.executed = True

class UtilityKeyframe(MantisMiscNode):
    '''A node representing a keyframe for a F-Curve'''
    __slots__ = ()
    socket_templates = KeyframeSockets
    # TODO: try UTILITY type and remove setup_custom_property stuff
    node_type = "DRIVER" # MUST be run in Pose mode
    def __init__(self, signature, base_tree,):
        super().__init__(signature, base_tree, KeyframeSockets,
                additional_parameters={"Keyframe":{}})
        # TODO: i am not sure this is necessary anymore
        setup_custom_property_inputs_outputs(self)

    def bPrepare(self, bContext = None,):
        key = self.parameters["Keyframe"]
        from mathutils import Vector
        key["co"]= Vector( (self.evaluate_input("Frame"), self.evaluate_input("Value"),))
        key["type"]="GENERATED"
        key["interpolation"] = "LINEAR"
        # eventually this will have the right data, TODO
        # self.parameters["Keyframe"] = key
        self.prepared = True
        self.executed = True

class UtilityFCurve(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = FCurveSockets

    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree, self.socket_templates)
        self.prepared = True

    def reset_execution(self):
        super().reset_execution()
        self.prepared=True

    def bTransformPass(self, bContext = None,):
        prepare_parameters(self)
        extrap_mode = self.evaluate_input("Extrapolation Mode")
        keys = []
        for i in range(len(self.inputs['Keyframes'].links)):
            keys.append( self.evaluate_input('Keyframes', i) )
        if len(keys) <1:
            prOrange(f"WARN: no keys in fCurve {self}.")
        keys.append(extrap_mode)
        self.parameters["fCurve"] = keys
        self.executed = True
#TODO make the keyframe, fCurve data classes instead of dicts!

class UtilityDriver(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = DriverSockets
    node_type = "DRIVER" # MUST be run in Pose mode
    def __init__(self, signature, base_tree):
        from .utilities.drivers import MantisDriver
        super().__init__(signature, base_tree, self.socket_templates,
            additional_parameters = {"Driver":MantisDriver(),})
        setup_custom_property_inputs_outputs(self)
        self.prepared = True

    def reset_execution(self):
        super().reset_execution()
        from .utilities.drivers import MantisDriver
        self.parameters["Driver"]=MantisDriver()
        self.prepared=True

    def bRelationshipPass(self, bContext = None,):
        prepare_parameters(self)
        from .utilities.drivers import MantisDriver
        #prPurple("Executing Driver Node")
        my_vars = []
        keys = self.evaluate_input("fCurve")
        if keys is None or len(keys) <2:
            prWhite(f"INFO: no fCurve connected to {self}; using default fCurve.")
            from mathutils import Vector
            keys = [
                {"co":Vector( (0, 0,)), "type":"GENERATED", "interpolation":"LINEAR" },
                {"co":Vector( (1, 1,)), "type":"GENERATED", "interpolation":"LINEAR" },
                "CONSTANT",]
        for inp in list(self.inputs.keys() )[3:]:
            if (new_var := self.evaluate_input(inp)):
                new_var = dict(new_var) # shared with other consumers -- never rename in place
                new_var["name"] = inp
                my_vars.append(new_var)
            else:
                raise RuntimeError(f"Failed to initialize Driver variable for {self}")
        my_driver ={ "owner"         :  None,
                     "prop"          :  None, # will be filled out in the node that uses the driver
                     "expression"    :  self.evaluate_input("Expression"),
                     "ind"           :  -1, # same here
                     "type"          :  self.evaluate_input("Driver Type"),
                     "vars"          :  my_vars,
                     "keys"          :  keys[:-1],
                     "extrapolation" :  keys[-1] }

        my_driver = MantisDriver(my_driver)

        self.parameters["Driver"].update(my_driver)
        print("Initializing driver %s " % (wrapPurple(self.__repr__())) )
        self.executed = True

class UtilitySwitch(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = SwitchSockets
    node_type = "DRIVER" # MUST be run in Pose mode
    def __init__(self, signature, base_tree):
        from .utilities.drivers import MantisDriver
        super().__init__(signature, base_tree, self.socket_templates,
            additional_parameters={ "Driver":MantisDriver(), })
        self.prepared = True

    # NOTE: _index for interface consistency
    def evaluate_input(self, input_name, _index=0):
        if input_name == 'Parameter':
            if self.inputs['Parameter'].is_connected:
                trace = trace_single_line(self, input_name)
                return trace[1].name # the name of the socket
            return self.parameters["Parameter"]
        return super().evaluate_input(input_name)

    def GetxForm(self,):
        trace = trace_single_line(self, "Parameter" )
        for node in trace[0]:
            if (node.__class__ in [xFormArmature, xFormBone]):
                return node #this will fetch the first one, that's good!
        return None

    def reset_execution(self):
        super().reset_execution()
        from .utilities.drivers import MantisDriver
        self.parameters["Driver"]=MantisDriver()
        self.prepared=True

    def bRelationshipPass(self, bContext = None,):
        #prepare_parameters(self)
        #prPurple ("Executing Switch Node")
        xForm = self.GetxForm()
        if xForm : xForm = xForm.bGetObject()
        if not xForm:
            raise RuntimeError("Could not evaluate xForm for %s" % self)
        from .utilities.drivers import MantisDriver
        my_driver ={ "owner" : None,
                     "prop"  : None, # will be filled out in the node that uses the driver
                     "ind"   : -1, # same here
                     "type"  : "SCRIPTED",
                     "vars"  : [ { "owner" : xForm,
                                   "prop"  : self.evaluate_input("Parameter"),
                                   "name"  : "a",
                                   "type"  : "SINGLE_PROP", } ],
                     "keys"  : [ { "co":(0,0),
                                   "interpolation": "LINEAR",
                                   "type":"KEYFRAME",}, #display type
                                 { "co":(1,1),
                                   "interpolation": "LINEAR",
                                   "type":"KEYFRAME",},],
                      "extrapolation": 'CONSTANT', }
        my_driver   ["expression"] = "a"

        my_driver = MantisDriver(my_driver)
    # this makes it so I can check for type later!

        if self.evaluate_input("Invert Switch") == True:
            my_driver   ["expression"] = "1 - a"

        # this way, regardless of what order things are handled, the
        #  driver is sent to the next node.
        # In the case of some drivers, the parameter may be sent out
        #  before it's filled in (because there is a circular dependency)
        # I want to support this behaviour because Blender supports it.
        # We do not make a copy. We update the driver, so that
        #  the same instance is filled out.
        self.parameters["Driver"].update(my_driver)
        print("Initializing driver %s " % (wrapPurple(self.__repr__())) )
        self.executed = True

class UtilityCombineThreeBool(MantisMiscNode):
    '''A node for combining three booleans into a boolean three-tuple'''
    __slots__ = ()
    socket_templates = CombineThreeBoolSockets

    def reset_execution(self): # need to make sure any references are deleted
        super().reset_execution() # so we prepare the node again to reset them
        if self.parameters["Three-Bool"] is not None:
            for param in self.parameters["Three-Bool"]:
                if isinstance(param, dict):
                    self.prepared=False; break

    def bPrepare(self, bContext = None,):
        self.parameters["Three-Bool"] = (
          self.evaluate_input("X"),
          self.evaluate_input("Y"),
          self.evaluate_input("Z"), )
        self.prepared = True
        self.executed = True

# Note this is a copy of the above. This needs to be de-duplicated.
class UtilityCombineVector(MantisMiscNode):
    '''A node for combining three floats into a vector'''
    __slots__ = ()
    socket_templates = CombineVectorSockets

    def reset_execution(self): # need to make sure any references are deleted
        super().reset_execution() # so we prepare the node again to reset them
        if self.parameters["Vector"] is not None:
            for param in self.parameters["Vector"]:
                if isinstance(param, dict):
                    self.prepared=False; break

    def bPrepare(self, bContext = None,):
        #prPurple("Executing CombineVector Node")
        prepare_parameters(self)
        self.parameters["Vector"] = (
          self.evaluate_input("X"),
          self.evaluate_input("Y"),
          self.evaluate_input("Z"), )
        self.prepared, self.executed = True, True

class UtilitySeparateVector(MantisMiscNode):
    '''A node for separating a vector into three floats'''
    __slots__ = ()
    socket_templates = SeparateVectorSockets

    def bPrepare(self, bContext = None,):
        self.parameters["X"] = self.evaluate_input("Vector")[0]
        self.parameters["Y"] = self.evaluate_input("Vector")[1]
        self.parameters["Z"] = self.evaluate_input("Vector")[2]
        self.prepared, self.executed = True, True

class UtilityCatStrings(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = CatStringsSockets

    def bPrepare(self, bContext = None,):
        self.parameters["OutputString"] = self.evaluate_input("String_1")+self.evaluate_input("String_2")
        self.prepared, self.executed = True, True

# TODO move this to the Xform file
class InputWidget(MantisMiscNode):
    '''A node representing an existing object'''
    __slots__ = ()
    socket_templates = InputWidgetSockets
    node_type = "XFORM"

    def reset_execution(self):
        super().reset_execution()
        self.prepared=False

    def bPrepare(self, bContext=None):
        print(wrapGreen("Executing ")+wrapOrange("InputWidget Node ")+wrapWhite(f"{self}"))
        path = self.evaluate_input('Name')
        axes_flipped = self.evaluate_input('Flip Axes')
        scaling = self.evaluate_input('Scale')
        add_scale_modifier = False
        if scaling[0] != 1.0 or scaling[1] != 1.0 or scaling[2] != 1.0:
            add_scale_modifier = True
        do_mirror = True
        from os import path as os_path
        from .preferences import get_bl_addon_object
        bl_mantis_addon = get_bl_addon_object()
        widgets_path = bl_mantis_addon.preferences.WidgetsLibraryFolder
        path = widgets_path+path # this guards the widgets root so the end-user
        #  can easily change the widgets directory without breaking things
        from .utilities.utilities import get_default_collection
        collection = get_default_collection(collection_type='WIDGET')
        file_name = os_path.split(path)[-1]
        obj_name = os_path.splitext(file_name)[0]
        obj_name_full = obj_name
        if add_scale_modifier:
            obj_name_full+="_scaled_"+".".join(self.ui_signature[1:])
        if any(axes_flipped):
            obj_name_full+="_flipped_"
        for i, axis in enumerate("XYZ"):
            if axes_flipped[i]: obj_name_full+=axis
        from bpy import data
        # what is this code doing? I thought I already linked it... TODO find out
        if  obj_name in data.objects.keys() and not \
            obj_name_full in data.objects.keys():
                self.bObject = data.objects.get(obj_name).copy()
                self.bObject.name = obj_name_full
                collection.objects.link(self.bObject)
        # now check to see if it exists
        elif obj_name_full in data.objects.keys():
            prWhite(f"INFO: {obj_name_full} is already in this .blend file; skipping import.")
            self.bObject = data.objects.get(obj_name_full)
            if any(axes_flipped): # check if we need to add a Flip modifier
                if len(self.bObject.modifiers) > 1 and self.bObject.modifiers[-1].name == "Simple Flip":
                    do_mirror=False
        else:
            from .utilities.utilities import import_object_from_file
            self.bObject = import_object_from_file(path)
            if any(axes_flipped) or add_scale_modifier:
                self.bObject = self.bObject.copy()
                self.bObject.name = obj_name_full
                collection.objects.link(self.bObject)
        # do the scaling...
        if add_scale_modifier:
            if (scale_modifier := self.bObject.modifiers.get("Scale Object Data")) is None:
                scale_modifier = self.bObject.modifiers.new("Scale Object Data", type='NODES')
            ng = data.node_groups.get("Scale Object Data")
            if ng is None:
                from .utilities.geometry_node_graphgen import gen_scale_object_data_modifier
                ng = gen_scale_object_data_modifier()
            scale_modifier.node_group = ng
            scale_modifier['Socket_2']=scaling
        # now we'll check for the mirrors.
        if any(axes_flipped) and do_mirror:
            if (flip_modifier := self.bObject.modifiers.get("Simple Flip")) is None:
                flip_modifier = self.bObject.modifiers.new("Simple Flip", type="NODES")
            ng = data.node_groups.get("Simple Flip")
            if ng is None:
                from .utilities.geometry_node_graphgen import gen_simple_flip_modifier
                ng = gen_simple_flip_modifier()
            flip_modifier.node_group = ng
            # this changed at some point in Blender's versions ehhh
            flip_modifier["Socket_2"]=axes_flipped[0]
            flip_modifier["Socket_3"]=axes_flipped[1]
            flip_modifier["Socket_4"]=axes_flipped[2]
        self.prepared, self.executed = True, True

    def bGetObject(self, mode=''):
        return self.bObject

# TODO move this to the Xform file
class InputExistingGeometryObject(MantisMiscNode):
    '''A node representing an existing object'''
    __slots__ = ()
    socket_templates = InputExistingGeometryObjectSockets
    node_type = "XFORM"

    def reset_execution(self):
        super().reset_execution()
        self.prepared=False

    def bPrepare(self, bContext=None):
        from bpy import data
        ob = None
        if name := self.evaluate_input("Name"):
            ob= data.objects.get( name  )
        if ob is None and name:
            prRed(f"No object found with name {name} in {self}")
        self.bObject=ob
        self.bRegisterObject('OBJECT', ob)
        self.prepared, self.executed = True, True

    def bGetObject(self, mode=''):
        return self.bObject

class InputExistingGeometryData(MantisMiscNode):
    '''A node representing existing object data'''
    __slots__ = ()
    socket_templates = InputExistingGeometrySockets

    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree, self.socket_templates)
        self.prepared = True; self.executed = True

    def reset_execution(self):
        super().reset_execution()
        self.prepared, self.executed = True, True

    # the mode argument is only for interface consistency
    def bGetObject(self, mode=''):
        from bpy import data
        # first try Curve, then try Mesh
        bObject = data.curves.get(self.evaluate_input("Name"))
        if not bObject:
            bObject = data.meshes.get(self.evaluate_input("Name"))
        if bObject is None:
            raise RuntimeError(f"Could not find a mesh or curve datablock named \"{self.evaluate_input('Name')}\" for node {self}")
        return bObject

class UtilityDeclareCollections(MantisMiscNode):
    '''A node to help manage bone collections'''
    __slots__ = ()
    socket_templates = None
    def __init__(self, signature, base_tree):
        # NOTE this one does not use socket template because it is special.
        # The user creates all the sockets for this one.
        super().__init__(signature, base_tree)
        self.prepared, self.executed = True, True

    def reset_execution(self):
        super().reset_execution()
        self.prepared, self.executed = True, True

    def fill_parameters(self, ui_node=None):
        from .mantis_dataclasses import MantisSocketTemplate
        if ui_node is None:
            from .utilities.utilities import get_ui_node
            ui_node = get_ui_node(self.ui_signature, self.base_tree)
        templates=[]
        for out in ui_node.outputs:
            if not (out.name in self.outputs.keys()) :
                templates.append(MantisSocketTemplate(name=out.name,
                        identifier=out.identifier, is_input=False,))
        self.outputs.init_sockets(templates)
        # now we have our parameters, fill them. This is a little inefficient I guess.
        for out in ui_node.outputs:
            self.parameters[out.name] = out.default_value

class UtilityCollectionJoin(MantisMiscNode):
    '''A node to help manage bone collections'''
    __slots__ = ()
    socket_templates = CollectionJoinSockets

    def reset_execution(self):
        super().reset_execution()
        self.prepared, self.executed = False, False

    def bPrepare(self, bContext = None,):
        if self.inputs['Collections'].links:
            bCol_groups = []
            for i, l in enumerate(self.inputs['Collections'].links):
                bCol_group = self.evaluate_input("Collections", index=i)
                if not isinstance(bCol_group, str):
                    bCol_group = str(bCol_group)
                    prOrange(f"Warning: coercing invalid input ({i}) to String in node: {self}")
                bCol_groups.append(bCol_group)
            bCols = '|'.join(bCol_groups)
        else:
            bCols = self.evaluate_input("Collections")
            if not isinstance(bCols, str):
                bCols = str(bCols)
                prOrange(f"Warning: coercing invalid input to String in node: {self}")
        self.parameters['Collection']=bCols
        self.prepared, self.executed = True, True

class UtilityCollectionHierarchy(MantisMiscNode):
    '''A node to help manage bone collections'''
    __slots__ = ()
    socket_templates = CollectionHierarchySockets

    def reset_execution(self):
        super().reset_execution()
        self.prepared, self.executed = False, False

    def bPrepare(self, bContext = None,):
        parent_col = self.evaluate_input('Parent Collection')
        if not isinstance(parent_col, str):
            parent_col = str(parent_col)
            prOrange(f"Warning: coercing invalid Parent Collection to String in node: {self}")
        child_col = self.evaluate_input('Child Collection')
        if not isinstance(child_col, str):
            child_col = str(child_col)
            prOrange(f"Warning: coercing invalid Child Collection to String in node: {self}")
        result = parent_col +">"+child_col
        self.parameters['Collection']=result
        self.prepared, self.executed = True, True

class UtilityGeometryOfXForm(MantisMiscNode):
    '''A node representing existing object data'''
    __slots__ = ()
    socket_templates = GeometryOfXFormSockets
    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree, self.socket_templates)
        self.prepared = True; self.executed = True

    def reset_execution(self):
        super().reset_execution()
        self.prepared, self.executed = True, True

    # mode for interface consistency
    def bGetObject(self, mode=''):
        if not (self.inputs.get('xForm') and self.inputs['xForm'].links):
            prOrange(f"WARN: Cannot retrieve data from {self}, there is no xForm node connected.")
            return None
        xf = self.inputs["xForm"].links[0].from_node
        if xf.node_type == 'XFORM':
            xf_ob = xf.bGetObject()
            if (xf_ob is not None) and xf_ob.type in ['MESH', 'CURVE']:
                return xf_ob.data
        prOrange(f"WARN: Cannot retrieve data from {self}, the connected xForm is not a mesh or curve.")
        return None

class UtilityNameOfXForm(MantisMiscNode):
    '''A node representing existing object data'''
    __slots__ = ()
    socket_templates = NameOfXFormSockets

    # mode for interface consistency
    def bPrepare(self, bContext = None,):
        if not (self.inputs.get('xForm') and self.inputs['xForm'].links):
            raise RuntimeError( f"WARN: Cannot retrieve data from {self},"
                                 " there is no xForm node connected.")
        xf = self.inputs["xForm"].links[0].from_node
        self.parameters["Name"] = xf.evaluate_input('Name')
        self.prepared, self.executed = True, True

class UtilityGetBoneLength(MantisMiscNode):
    '''A node to get the length of a bone matrix'''
    __slots__ = ()
    socket_templates = GetBoneLengthSockets

    def bPrepare(self, bContext = None,):
        if (l := self.evaluate_input("Bone Matrix")) is not None:
            self.parameters["Bone Length"] = l[3][3]
        else:
            other = self.inputs["Bone Matrix"].links[0].from_node
            raise RuntimeError(f"Cannot get matrix for {self} from {other}")
        self.prepared, self.executed = True, True

class UtilityPointFromBoneMatrix(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = PointFromBoneMatrixSockets

    # TODO: find out why this is sometimes not ready at bPrepare phase
    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        matrix = self.evaluate_input("Bone Matrix")
        head, rotation, _scale = matrix.copy().decompose()
        tail = head.copy() + (rotation @ Vector((0,1,0)))*matrix[3][3]
        self.parameters["Point"] = head.lerp(tail, self.evaluate_input("Head/Tail"))
        self.prepared, self.executed = True, True

class UtilitySetBoneLength(MantisMiscNode):
    '''Sets the length of a Bone's matrix'''
    __slots__ = ()
    socket_templates = SetBoneLengthSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        if matrix := self.evaluate_input("Bone Matrix"):
            matrix = matrix.copy()
            # print (self.inputs["Length"].links)
            matrix[3][3] = self.evaluate_input("Length")
            self.parameters["Length"] = self.evaluate_input("Length")
            self.parameters["Bone Matrix"] = matrix
        else:
            raise RuntimeError(f"Cannot get matrix for {self}")
        self.prepared, self.executed = True, True

class UtilityMatrixSetLocation(MantisMiscNode):
    '''Sets the location of a matrix'''
    __slots__ = ()
    socket_templates = MatrixSetLocationSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        if matrix := self.evaluate_input("Matrix"):
            matrix = matrix.copy()
            # print (self.inputs["Length"].links)
            loc = self.evaluate_input("Location")
            matrix[0][3] = loc[0]; matrix[1][3] = loc[1]; matrix[2][3] = loc[2]
            self.parameters["Matrix"] = matrix
        self.prepared, self.executed = True, True

class UtilityMatrixGetLocation(MantisMiscNode):
    '''Gets the location of a matrix'''
    __slots__ = ()
    socket_templates = MatrixGetLocationSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        if matrix := self.evaluate_input("Matrix"):
            self.parameters["Location"] = matrix.to_translation()
        self.prepared = True; self.executed = True

class UtilityMatrixFromXForm(MantisMiscNode):
    """Returns the matrix of the given xForm node."""
    __slots__ = ()
    socket_templates = MatrixFromXFormSockets

    def GetxForm(self):
        trace = trace_single_line(self, "xForm")
        for node in trace[0]:
            if (node.node_type == 'XFORM'):
                return node
        raise GraphError("%s is not connected to an xForm" % self)

    def bPrepare(self, bContext = None,):
        from mathutils import Vector, Matrix
        self.parameters["Matrix"] = Matrix.Identity(4)
        if matrix := self.GetxForm().parameters.get("Matrix"):
            self.parameters["Matrix"] = matrix.copy()
        elif hasattr(self.GetxForm().bObject, "matrix"):
            self.parameters["Matrix"] = self.GetxForm().bObject.matrix.copy()
        elif hasattr(self.GetxForm().bObject, "matrix_world"):
            self.parameters["Matrix"] = self.GetxForm().bObject.matrix_world.copy()
        else:
            prRed(f"Could not find matrix for {self} - check if the referenced object exists.")
        self.prepared = True; self.executed = True

class UtilityAxesFromMatrix(MantisMiscNode):
    """Returns the axes of the given matrix."""
    __slots__ = ()
    socket_templates = AxesFromMatrixSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        if matrix := self.evaluate_input("Matrix"):
            matrix= matrix.copy().to_3x3(); matrix.transpose()
            self.parameters['X Axis'] = matrix[0]
            self.parameters['Y Axis'] = matrix[1]
            self.parameters['Z Axis'] = matrix[2]
        self.prepared = True; self.executed = True

class UtilityBoneMatrixHeadTailFlip(MantisMiscNode):
    __slots__ = ()
    socket_templates = BoneMatrixHeadTailFlipSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector, Matrix, Quaternion
        from bpy.types import Bone
        if matrix := self.evaluate_input("Bone Matrix"):
            axis, roll = Bone.AxisRollFromMatrix(matrix.to_3x3())
            new_mat = Bone.MatrixFromAxisRoll(-1*axis, roll)
            length = matrix[3][3]
            new_mat.resize_4x4()         # last column contains
            new_mat[0][3] = matrix[0][3] + axis[0]*length # x location
            new_mat[1][3] = matrix[1][3] + axis[1]*length # y location
            new_mat[2][3] = matrix[2][3] + axis[2]*length # z location
            new_mat[3][3] = length                           # length
            self.parameters["Bone Matrix"] = new_mat
        self.prepared, self.executed = True, True

class UtilityMatrixTransform(MantisMiscNode):
    __slots__ = ()
    socket_templates = MatrixTransformSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        mat1 = self.evaluate_input("Matrix 1"); mat2 = self.evaluate_input("Matrix 2")
        if mat1 and mat2:
            mat1copy = mat1.copy()
            self.parameters["Out Matrix"] = mat2 @ mat1copy
            self.parameters["Out Matrix"].translation = mat1copy.to_translation()+ mat2.to_translation()
        else:
            raise RuntimeError(wrapRed(f"Node {self} did not receive all matrix inputs..."
                            " found input 1? {mat1 is not None}, 2? {mat2 is not None}"))
        self.prepared, self.executed = True, True

class UtilityMatrixInvert(MantisMiscNode):
    __slots__ = ()
    socket_templates = MatrixInvertSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector
        mat1 = self.evaluate_input("Matrix 1")
        if mat1:
            mat1copy = mat1.copy()
            try:
                self.parameters["Matrix"] = mat1copy.inverted()
            except ValueError as e:
                prRed(f"ERROR: {self}: The matrix cannot be inverted."); prOrange(mat1)
                raise e
        else:
            raise RuntimeError(wrapRed(f"Node {self} did not receive all matrix inputs..."
                                       " found input 1? {mat1 is not None}"))
        self.prepared, self.executed = True, True

class UtilityMatrixCompose(MantisMiscNode):
    __slots__ = ()
    socket_templates = MatrixComposeSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Matrix, Vector
        mode = self.evaluate_input("Mode")
        translation = self.evaluate_input('Translation')
        length = self.evaluate_input('Bone Length')
        match mode:
            case "BASIS":
                matrix= Matrix.Identity(3)
                matrix[0] = self.evaluate_input('X Basis Vector')
                matrix[1] = self.evaluate_input('Y Basis Vector')
                matrix[2] = self.evaluate_input('Z Basis Vector')
                matrix.transpose(); matrix=matrix.to_4x4()
                matrix.translation = translation
            case "CHANNELS":
                rotation    = self.evaluate_input('Rotation')
                scale       = Vector((1,1,1))
                matrix= Matrix.LocRotScale(translation, rotation, scale)
        matrix[3][3]=length # Length
        self.parameters['Matrix']=matrix
        self.prepared = True; self.executed = True

class UtilityMatrixAlignRoll(MantisMiscNode):
    __slots__ = ()
    socket_templates = MatrixAlignRollSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Vector, Matrix
        align_axis = Vector(self.evaluate_input('Alignment Vector'))
        # why do I have to construct a vector here?
        # why is the socket returning a bpy_prop_array ?
        if align_axis.length_squared==0:
            raise RuntimeError(f"WARN: cannot align matrix in {self}"
                                " because the alignment vector is zero.")
        input=self.evaluate_input('Matrix').copy()
        y_axis= input.to_3x3().transposed()[1]
        from .utilities.utilities import project_point_to_plane
        projected=project_point_to_plane(
            align_axis.normalized(), Vector((0,0,0)), y_axis).normalized()
        # now that we have the projected vector, transform the points from
        #   the plane of the y_axis to flat space and get the signed angle
        from math import atan2
        try:
            flattened = (input.to_3x3().inverted() @ projected)
        except ValueError:
            raise ValueError(f"Cannot align the matrix in {self} because it is degenerate.")
        rotation = Matrix.Rotation(atan2(flattened.x, flattened.z), 4, y_axis)
        matrix = rotation @ input.copy()
        matrix.translation=input.translation
        matrix[3][3] = input[3][3]
        self.parameters['Matrix'] = matrix
        self.prepared = True; self.executed = True
        # NOTE: I tried other ways of setting the matrix, including composing
        #  it directly from the Y axis, the normalized projection of the align
        #  axis, and their cross-product. That only nearly worked.
        # this calculation should not work better, but it does. Why?

class UtilityTransformationMatrix(MantisMiscNode):
    __slots__ = ()
    socket_templates = TransformationMatrixSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Matrix, Vector
        if (operation := self.evaluate_input("Operation")) == 'ROTATE_AXIS_ANGLE':
            # this can, will, and should fail if the axis is 0,0,0
            self.parameters["Matrix"] = rotMat = Matrix.Rotation(self.evaluate_input("W"), 4, Vector(self.evaluate_input("Vector")).normalized())
        elif (operation := self.evaluate_input("Operation")) == 'TRANSLATE':
            m = Matrix.Identity(4)
            if axis := self.evaluate_input("Vector"):
                m[0][3]=axis[0];m[1][3]=axis[1];m[2][3]=axis[2]
            self.parameters['Matrix'] = m
        elif (operation := self.evaluate_input("Operation")) == 'SCALE':
            self.parameters["Matrix"] = Matrix.Scale(self.evaluate_input("W"), 4, Vector(self.evaluate_input("Vector")).normalized())
        else:
            raise NotImplementedError(self.evaluate_input("Operation").__repr__()+ "  Operation not yet implemented.")
        self.prepared = True; self.executed = True

class UtilityIntToString(MantisMiscNode):
    __slots__ = ()
    socket_templates = IntToStringSockets

    def bPrepare(self, bContext = None,):
        number = self.evaluate_input("Number")
        zeroes = self.evaluate_input("Zero Padding")
        # I'm casting to int because I want to support any number, even though the node asks for int.
        self.parameters["String"] = str(int(number)).zfill(int(zeroes))
        self.prepared = True; self.executed = True

class UtilityArrayGet(MantisMiscNode):
    __slots__ = ('rerouted')
    socket_templates = ArrayGetSockets
    def __init__(self, signature, base_tree):
        super().__init__(signature, base_tree, self.socket_templates)
        self.rerouted=[]

    def bPrepare(self, bContext = None,):
        from .base_definitions import links_sort_key
        if len(self.rerouted)>0:
            self.prepared, self.executed = True, True
            return #Either it is already done or it doesn't matter.
        elif self.prepared == False:
            # sort the array entries
            for inp in self.inputs.values():
                inp.links.sort(key=links_sort_key)
            oob   = self.evaluate_input("OoB Behaviour")
            index = self.evaluate_input("Index")

            from .utilities.utilities import cap, wrap
            # we must assume that the array has sent the correct number of links
            if oob == 'WRAP':
                index = wrap(0, len(self.inputs['Array'].links), index)
            if oob == 'HOLD':
                index = cap(index, len(self.inputs['Array'].links)-1)
            array_choose_relink(self, [index], "Array", "Output")
        self.prepared, self.executed = True, True

class UtilityArrayLength(MantisMiscNode):
    __slots__ = ()
    socket_templates = UtilityArrayLengthSockets

    def bPrepare(self, bContext = None,):
        self.parameters["Length"] = len(self.inputs["Array"].links)
        self.prepared, self.executed = True, True

class UtilitySetBoneMatrixTail(MantisMiscNode):
    __slots__ = ()
    socket_templates = SetBoneMatrixTailSockets

    def bPrepare(self, bContext = None,):
        from mathutils import Matrix
        matrix = self.evaluate_input("Matrix")
        if matrix is None: matrix = Matrix.Identity(4)
        #just do this for now lol
        self.parameters["Result"] = matrix_from_head_tail(matrix.translation, self.evaluate_input("Tail Location"))
        self.prepared = True; self.executed = True

class UtilityCompare(MantisMiscNode):
    __slots__ = ()
    socket_templates = CompareSockets

    def bPrepare(self, bContext = None,):
        operation=self.evaluate_input("Comparison")
        a = self.evaluate_input("A")
        b = self.evaluate_input("B")
        if a is None:
            raise GraphError(f"Invalid first input for {self}")
        if b is None:
            raise GraphError(f"Invalid second input for {self}")
        if isinstance(a, str) and isinstance(b, str) and \
              operation not in ['EQUAL', 'NOT_EQUAL']:
                   raise GraphError("Strings do not have numerical value to"
                                    " compute greater than or less than.")
        match operation:
            case "EQUAL":
                self.parameters["Result"] = a == b
            case "NOT_EQUAL":
                self.parameters["Result"] = a != b
            case "GREATER_THAN":
                self.parameters["Result"] = a > b
            case "GREATER_THAN_EQUAL":
                self.parameters["Result"] = a >= b
            case "LESS_THAN":
                self.parameters["Result"] = a < b
            case "LESS_THAN_EQUAL":
                self.parameters["Result"] = a <= b
        self.prepared = True; self.executed = True

class UtilityChoose(MantisMiscNode):
    __slots__ = ()
    socket_templates = ChooseSockets

    def reset_execution(self):
        prepared=self.prepared
        super().reset_execution()
        # prevent this node from attempting to prepare again.
        self.prepared, self.executed = prepared, prepared

    def bPrepare(self, bContext = None,):
        if self.outputs['Result'].links: # otherwise this doesn't matter as it is not connected.
            prGreen(f"Executing Choose Node {self}")
            condition = self.evaluate_input("Condition")
            if self.evaluate_input('A') is not None and self.evaluate_input('B') is not None:
                self.parameters['Result'] = self.evaluate_input('B') if condition else self.evaluate_input('A')
            elif self.evaluate_input('A') is None and self.evaluate_input('B') is None:
                if condition: link = self.inputs['B'].links[0]
                else: link = self.inputs['A'].links[0]
                from_node = link.from_node; from_socket  = link.from_socket
                for link in self.outputs['Result'].links:
                    from_node.outputs[from_socket].connect(link.to_node, link.to_socket)
                    link.die()
                self.flush_links()
                # attempting to init the connections seems more error prone than leaving them be.
            else:
                raise GraphError(f"Choose Node {self} has incorrect types.")
        self.prepared = True; self.executed = True

class UtilityPrint(MantisMiscNode):
    __slots__ = ()
    socket_templates = PrintSockets

    def bPrepare(self, bContext = None,):
        if my_input := self.evaluate_input("Input"):
            print("Preparation phase: ", wrapWhite(self), wrapGreen(my_input))
        self.prepared = True

    def bTransformPass(self, bContext = None,):
        if my_input := self.evaluate_input("Input"):
            print("Execution phase: ", wrapWhite(self), wrapGreen(my_input))
        self.executed = True