join_objects_by_texture.py

import bpy
from collections import defaultdict

def get_texture_image(obj):
    """Returns the image texture of the first image node in the first material."""
    if not obj.data.materials:
        return None
    mat = obj.data.materials[0]
    if mat and mat.use_nodes:
        for node in mat.node_tree.nodes:
            if node.type == 'TEX_IMAGE':
                return node.image
    return None

def group_objects_by_texture():
    """Groups mesh objects by their texture image."""
    texture_groups = defaultdict(list)

    for obj in bpy.data.objects:
        if obj.type == 'MESH':
            tex_image = get_texture_image(obj)
            if tex_image:
                texture_groups[tex_image].append(obj)

    return texture_groups

def join_objects_by_texture():
    texture_groups = group_objects_by_texture()

    for image, objs in texture_groups.items():
        if len(objs) < 2:
            continue  # No need to join if only one object

        # Make the first object active
        context = bpy.context
        bpy.ops.object.select_all(action='DESELECT')
        active_obj = objs[0]
        context.view_layer.objects.active = active_obj
        active_obj.select_set(True)

        # Select and join the rest
        for obj in objs[1:]:
            obj.select_set(True)

        bpy.ops.object.join()
        print(f"Joined {len(objs)} objects with texture: {image.name}")

# Run the script
join_objects_by_texture()