mantis/misc_nodes.py

from .utilities.node_common import *
from .base_definitions import MantisNode, NodeSocket, FLOAT_EPSILON
from .xForm_nodes import xFormNode
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,
            ]

# This cache is used for storing evaluated curve matrices
# the idea is to get the data once and hold onto it
# this prevents numerous wasteful calls to dg.update()
CURVE_LUT_CACHE = {}
CURVE_HASHES = {}
SPLINE_HASHES ={}

# todo: make a "matrix from 2 u" function, a "matrix for segments" function
# basically I want the SplineLUT to handle all curve matrix getters
class SplineLUT:
    __slots__ = ("u_sample_points", "positions", "tangents", "normals", "hash", "curve_name")

    def __init__(self, u_sample_points, positions, tangents, normals, hash, curve_name):
        # points: ordered iterable of (u, position, tangent, normal)
        # Each vector is an iterable of 3 floats.
        self.u_sample_points = u_sample_points; self.hash = hash; self.curve_name = curve_name
        self.positions = positions; self.tangents = tangents; self.normals = normals

    def data_at_u(self, u):
        if u <= 0 + FLOAT_EPSILON: return self.positions[0], self.tangents[0], self.normals[0]
        elif u >= 1 - FLOAT_EPSILON: return self.positions[-1], self.tangents[-1], self.normals[-1]
        else:
            u_sample_points = self.u_sample_points
            # get the index in the list just above the desired u value
            from bisect import bisect_right # this finds an "insertion point" quickly
            i = bisect_right(u_sample_points, u) 
            u0 = u_sample_points[i-1]; u1 = u_sample_points[i]
            if u - FLOAT_EPSILON >= u0 and u0 <= u + FLOAT_EPSILON :
                factor = (u - u0) / (u1 - u0)
                position = self.positions[i-1].lerp( self.positions[i], factor)
                tangent = self.tangents[i-1].lerp( self.tangents[i], factor).normalized()
                normal = self.normals[i-1].lerp( self.normals[i], factor).normalized()
                return position, tangent, normal
            else: # we're exactly on the vertex.
                return self.positions[i-1], self.tangents[i-1], self.normals[i-1]
    
    def matrix_at_u(self, u):
        from mathutils import Matrix
        position, tangent, normal = self.data_at_u(u)
        normal = (normal - tangent * normal.dot(tangent)).normalized()
        bitangent = normal.cross(tangent).normalized()
        matrix = Matrix.Identity(3)
        matrix[0] = normal
        matrix[1] = tangent
        matrix[2] = bitangent
        matrix.transpose(); matrix = matrix.to_4x4()
        matrix.translation = position
        return matrix

    def matrix_from_start_end_u(self, start_u, end_u):
        from mathutils import Matrix
        position_start, _tangent_start, normal_start = self.data_at_u(start_u)
        position_end, _tangent_end, _normal_end = self.data_at_u(end_u)
        tangent = position_end - position_start
        length = tangent.length
        if tangent.length_squared < FLOAT_EPSILON:
            raise RuntimeError(f"Failed to read the curve {self.curve_name}.")
        tangent.normalize()
        normal = (normal_start - tangent * normal_start.dot(tangent)).normalized()
        bitangent = normal.cross(tangent).normalized()
        matrix = Matrix.Identity(3)
        matrix[0] = normal
        matrix[1] = tangent
        matrix[2] = bitangent
        matrix.transpose(); matrix = matrix.to_4x4()
        matrix.translation = position_start
        matrix[3][3] = length # set the lenght with our HACK metadata thing
        return matrix

    def matrices_from_u_segments(self, u_values=[]):
        return tuple( self.matrix_from_start_end_u(u_values[i], u_values[i+1]) for i in range(len(u_values)-1) )

    def point_and_u_at_nearest_point_on_curve(self, point):
        from mathutils.geometry import intersect_point_line
        # because kd_find can return any number of points it always returns a list
        nearest_point, index, distance = kd_find(self, self.positions, ref_pt=point, )[0]
        # ONE of the segments this point belongs to will have the right value
        max_index = len(self.u_sample_points)-1
        if index >= 0 and index < max_index: # check the line between the found point and the next point
            closest_point, parametric_distance_to = intersect_point_line(
                            point, self.positions[index], self.positions[index + 1],)
            if parametric_distance_to > 0 - FLOAT_EPSILON and parametric_distance_to < 1 + FLOAT_EPSILON:
                # we have found our point
                a = self.u_sample_points[index]; b = self.u_sample_points[index + 1]
                return closest_point, (a + (b - a) * parametric_distance_to)
        if index > 0 and index <= max_index: # check the previous segment
            closest_point, parametric_distance_to = intersect_point_line(
                            point, self.positions[index], self.positions[index - 1],)
            if parametric_distance_to > 0 - FLOAT_EPSILON and parametric_distance_to < 1 + FLOAT_EPSILON:
                # we have found our point
                a = self.u_sample_points[index]; b = self.u_sample_points[index - 1]
                return closest_point, (a + (b - a) * parametric_distance_to)

    def __repr__(self):
        return f"Cached curve {self.curve_name}"


def hash_spline(spline) -> int:
    # explicit tuple because Python will make a freakin' generator object otherwise
    spline_metadata = ( spline.type, spline.resolution_u, spline.order_u, 
                        spline.use_cyclic_u, spline.use_endpoint_u,
                        spline.tilt_interpolation, spline.radius_interpolation, )
    if spline.type == 'BEZIER':
        points_data = tuple( ( *bp.co, *bp.handle_left, *bp.handle_right,
                                bp.handle_right_type, bp.handle_left_type,
                                bp.tilt, bp.radius) for bp in spline.bezier_points )
    else:
        points_data = tuple( (*p.co, p.tilt, p.radius ) for p in spline.points )
    return hash( (spline_metadata, points_data) )

def hash_curve(curve, spline_hashes) -> int:
    curve_metadata = ( curve.dimensions, curve.twist_mode, curve.resolution_u, )
    return hash( (curve_metadata, spline_hashes) )

def fill_curve_lut(curve_name, bContext):
    curve = bpy_object_get_guarded( curve_name )

    if not curve: raise RuntimeError(f"WARN: No curve found for {curve_name}.")
    elif curve.type != "CURVE": raise RuntimeError(f"WARN: Object {curve_name} is not a curve.")
    else:
        spline_hashes = tuple( hash_spline(spline) for spline in curve.data.splines)
        curve_hash = hash_curve(curve.data, spline_hashes)
        SPLINE_HASHES[curve.name] = spline_hashes; CURVE_HASHES[curve_name] = curve_hash
        if existing_cache := CURVE_LUT_CACHE.get(curve_name):
            if existing_cache['hash'] == curve_hash: return
        mesh = get_mesh_from_curve(curve_name, "_MANTIS_CACHE_CURVE", bContext)
        curve_lut_cache = []
        from .utilities.utilities import all_data_from_ribbon, DetectRibbons
        for i, ribbon in enumerate(DetectRibbons(mesh)):
            spline_hash = spline_hashes[i]
            if existing_cache := CURVE_LUT_CACHE.get(curve_name):
                if len(existing_cache['spline_LUT']) >= i:
                    if existing_cache['spline_LUT'][i].hash == spline_hash: continue
            # othewise we need to get the data
            # if I ever decide to use the radius in Mantis I'll add it to the LUT
            u_samples, positions, normals, tangents, radii = all_data_from_ribbon(mesh, curve.matrix_world, ribbon)
            for radius in radii:
                if radius < FLOAT_EPSILON: # radius is 0:
                    raise RuntimeError(zero_radius_error_message(None, curve))
            spline_lut = SplineLUT(
                u_samples, positions, tangents, normals, hash=spline_hash, curve_name=curve_name, )
            curve_lut_cache.append(spline_lut)
    
    CURVE_LUT_CACHE[curve_name] = {}
    CURVE_LUT_CACHE[curve_name]['hash'] = curve_hash
    CURVE_LUT_CACHE[curve_name]['spline_LUT'] = curve_lut_cache
    # remove the mesh, it is no longer needed - we have built a cache
    # import bpy
    # bpy.data.meshes.remove(mesh)

def get_from_curve_lut(curve_name, spline_index, bContext, node_for_error=None) -> SplineLUT:
    spline_lookup = None
    try:
        fill_curve_lut(curve_name=curve_name, bContext=bContext)
        spline_lookup = CURVE_LUT_CACHE[curve_name]['spline_LUT'][spline_index]
    except IndexError: # replace with a more helpful error message
        raise IndexError(f"{node_for_error} is attempting to read from a spline in {curve_name} "
                "that does not exist. Try and reduce the value of Spline Index.")
    return spline_lookup


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 kd_find(node, points, ref_pt, num_points = 1):
        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'
    passes=frozenset({'bPrepare',})

class SimpleInputNode(MantisMiscNode):
    __slots__ = ()
    node_type = 'UTILITY'
    passes=frozenset({})
    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

    def fill_parameters(self, ui_node=None):
        from .execution.overlays import handle_overlay_detect, get_socket_idname_data_type, parser_handle_text
        ui_outputs = ui_node.outputs
        node_socket = ui_outputs[0] # this is a simple input node.
        if (value := node_socket.default_value) is not None:
            if hasattr(node_socket, 'use_overlay') and node_socket.use_overlay:
                value = node_socket.overlay_text
                if get_socket_idname_data_type(node_socket.bl_idname) != str:
                    value = parser_handle_text(value)
            if isinstance(value, str) and "$" in value:
                value = handle_overlay_detect(self, node_socket.identifier, node_socket.bl_idname, value)
            self.parameters[node_socket.name] = value
        
#*#-------------------------------#++#-------------------------------#*#
# 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

    def fill_parameters(self, ui_node=None):
        from mathutils import Matrix
        ui_outputs = ui_node.outputs
        node_socket = ui_outputs[0]
        v = node_socket.default_value
        self.parameters[node_socket.name] = Matrix(( tuple(v[0:4]),
                                                     tuple(v[4:8]),
                                                     tuple(v[8:12]),
                                                     tuple(v[12:16]) ))

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
    passes=frozenset({'bPrepare', 'bFinalize'})

    def bPrepare(self, bContext = None,):
        from mathutils import Matrix
        import bpy
        curve_name = self.evaluate_input("Curve"); mode = self.evaluate_input("Mode")
        # DIVISIONS, FACTOR
        if bContext is None: bContext = bpy.context # is this wise?
        spline_index = self.evaluate_input("Spline Index")
        spline_lookup : SplineLUT = get_from_curve_lut(curve_name, spline_index, bContext, self)
        assert(spline_lookup)
        #
        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.")
        if mode == 'FACTOR':
            factor = self.evaluate_input('Factor')
            matrix = spline_lookup.matrix_at_u(factor)
        elif mode == 'FACTOR_WITH_TAIL':
            factor = self.evaluate_input('Factor')
            factor_tail = self.evaluate_input('Factor (Tail)')
            matrix = spline_lookup.matrix_from_start_end_u(factor, factor_tail)
        else:  # mode == 'DIVISIONS':
            factor = 1/num_divisions*m_index
            factor_tail = 1/num_divisions*(m_index+1)
            matrix = spline_lookup.matrix_from_start_end_u(factor, factor_tail)
        
        self.parameters["Matrix"] = matrix
        self.prepared = True
        self.executed = True

#TODO there is no harm in grabbing normal and tangent here, too
class UtilityPointFromCurve(MantisMiscNode):
    '''Get a point from a curve'''
    __slots__ = ()
    socket_templates = PointFromCurveSockets
    passes=frozenset({'bPrepare', 'bFinalize'})

    def bPrepare(self, bContext = None,):
        import bpy
        curve_name = self.evaluate_input("Curve")
        if bContext is None: bContext = bpy.context # is this wise?
        spline_index = self.evaluate_input("Spline Index")
        spline_lookup : SplineLUT = get_from_curve_lut(curve_name, spline_index, bContext, self)
        factor = self.evaluate_input("Factor")
        position, _tan, _nrm = spline_lookup.data_at_u(factor)
        self.parameters["Point"] = position
        self.prepared, self.executed = True, True

class UtilityMatricesFromCurve(MantisMiscNode):
    '''Get matrices from a curve'''
    __slots__ = ()
    socket_templates = MatricesFromCurveSockets
    passes=frozenset({'bPrepare', 'bFinalize'})

    def bPrepare(self, bContext = None,):
        curve_name = self.evaluate_input("Curve")
        spline_index = self.evaluate_input("Spline Index")
        import bpy
        if bContext is None: bContext = bpy.context # is this wise?
        spline_lookup : SplineLUT = get_from_curve_lut(curve_name, spline_index, bContext, self)
    
        num_divisions = self.evaluate_input("Total Divisions")
        factors = [0.0] + [(1/num_divisions*(i+1)) for i in range(num_divisions)]
        matrices = spline_lookup.matrices_from_u_segments(factors)

        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)
                self.parameters[name] = m
            link.die()
        self.prepared = True; self.executed = True


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
    passes=frozenset({'bPrepare', 'bFinalize'})

    def bPrepare(self, bContext = None,):
        import bpy
        curve_name = self.evaluate_input("Curve")
        curve = bpy_object_get_guarded(curve_name, self)
        spline_index = self.evaluate_input("Spline Index")
        if bContext is None: bContext = bpy.context # is this wise?
        spline_lookup = get_from_curve_lut(curve_name, spline_index, bContext, self)
        spline = curve.data.splines[spline_index]
        factors = []
        points = spline.bezier_points if spline.type == 'BEZIER' else spline.points
        total_length=0.0
        for i in range(len(points)): # points[i].co[:3] because nurbs have W element :/
            _pt, u = spline_lookup.point_and_u_at_nearest_point_on_curve(points[i].co[:3])
            factors.append(u)
        segment_index = self.evaluate_input("Segment Index")
        m = spline_lookup.matrix_from_start_end_u(factors[segment_index], factors[segment_index+1])
        self.parameters["Matrix"] = m
        self.prepared, self.executed = True, True

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

    def bPrepare(self, bContext=None):
        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")
        spline_index = self.evaluate_input("Spline Index")
        if bContext is None: bContext = bpy.context # is this wise?
        spline_lookup = get_from_curve_lut(curve_name, spline_index, bContext, self)
        ref_pt = self.evaluate_input("Reference Point")
        _closest_point, u = spline_lookup.point_and_u_at_nearest_point_on_curve(ref_pt)
        self.parameters["Factor"] = u
        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

class UtilityDriverVariable(MantisMiscNode):
    '''A node representing an armature object'''
    __slots__ = ()
    socket_templates = DriverVariableSockets
    node_type = "DRIVER"
    passes=frozenset({'bPrepare', 'bRelationship'})

    def reset_execution(self):
        super().reset_execution()
        # clear the pointer properties to prevent using stale pointer data.
        my_var = self.parameters["Driver Variable"]
        if my_var is not None:
            my_var["owner"]   = xForm1 # will be filled in by Driver
            my_var["xForm 1"] = xForm1 # self.GetxForm(index = 1),
            my_var["xForm 2"] = xForm2 # self.GetxForm(index = 2),
        else:
            self.prepared=False

    # 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 (isinstance(node, xFormNode)):
                return node #this will fetch the first one, that's good!
        return None

    def bPrepare(self, bContext=None):
        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"         : None,
            "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"       : None, # not available yet
            "xForm 2"       : None, # not available yet
            "channel"       : dVarChannel,}

        self.parameters["Driver Variable"] = my_var
        self.prepared = True
        
    def bRelationshipPass(self, bContext = None,):
        prepare_parameters(self)
        xF1 = self.GetxForm(index = 1)
        xF2 = self.GetxForm(index = 2)
        # kinda clumsy
        xForm1, xForm2 = None, None
        if xF1 : xForm1 = xF1.bGetObject()
        if xF2 : xForm2 = xF2.bGetObject()
        my_var = self.parameters["Driver Variable"]
        if my_var is not None:
            my_var["owner"]   = xForm1 # will be filled in by Driver
            my_var["xForm 1"] = xForm1 # self.GetxForm(index = 1),
            my_var["xForm 2"] = xForm2 # self.GetxForm(index = 2),
        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 bPrepare(self, bContext = None,):
        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}.")
        # IT IS VERY IMPORTANT to sort the links
        from .base_definitions import links_sort_key
        for inp in {'Keyframes'}:
            self.inputs[inp].links.sort(key=links_sort_key)
        keys.append(extrap_mode)
        self.parameters["fCurve"] = keys
        self.prepared = True
        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
    passes=frozenset({'bRelationship'})
    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
    passes=frozenset({'bRelationship'})
    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 (isinstance(node, xFormNode)):
                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
            if bpy_version < (5, 2, 0):
                flip_modifier["Socket_2"]=axes_flipped[0]
                flip_modifier["Socket_3"]=axes_flipped[1]
                flip_modifier["Socket_4"]=axes_flipped[2]
            else: # this changed in Blender 5.2.0...
                flip_modifier.properties.inputs.Socket_2.value = axes_flipped[0]
                flip_modifier.properties.inputs.Socket_3.value = axes_flipped[1]
                flip_modifier.properties.inputs.Socket_4.value = 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
    passes=frozenset({})

    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
        name = self.evaluate_input("Name")
        bObject = data.curves.get(name)
        if not bObject:
            bObject = data.meshes.get(name)
        if not bObject:
            bObject = data.lattices.get(name)
        if bObject is None:
            raise RuntimeError(f"Could not find a curve, mesh, or lattice 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
    passes=frozenset({})
    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
    passes=frozenset({})
    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