2026-02-16

This commit is contained in:
2026-03-17 15:25:32 -06:00
parent d5dd373de0
commit 60100fbab2
560 changed files with 33397 additions and 20776 deletions
@@ -31,6 +31,7 @@ a material would be searching for the image_materials() function.
"""
import bpy
from ..utils import compat
def collection_all(collection_key):
@@ -42,7 +43,8 @@ def collection_all(collection_key):
collection_meshes(collection_key) + \
collection_others(collection_key) + \
collection_rigidbody_world(collection_key) + \
collection_scenes(collection_key)
collection_scenes(collection_key) + \
collection_instances(collection_key)
def collection_cameras(collection_key):
@@ -189,6 +191,32 @@ def collection_scenes(collection_key):
return distinct(users)
def collection_instances(collection_key):
# returns a list of object keys that instance this collection
# Collection instances are objects with instance_type='COLLECTION' and
# instance_collection pointing to this collection
# Only counts objects that are actually in scene collections
users = []
collection = bpy.data.collections[collection_key]
for obj in bpy.data.objects:
# Skip library-linked and override objects
if compat.is_library_or_override(obj):
continue
# Check if object is a collection instance
if hasattr(obj, 'instance_type') and obj.instance_type == 'COLLECTION':
if hasattr(obj, 'instance_collection') and obj.instance_collection:
if obj.instance_collection.name == collection.name:
# Only count if the instance object is in a scene
# (otherwise the collection isn't really being used)
if object_all(obj.name):
users.append(obj.name)
return distinct(users)
def _scene_collection_contains(parent_collection, target_collection):
# helper that checks whether target_collection exists inside the
# parent_collection hierarchy
@@ -255,6 +283,9 @@ def image_compositors(image_key):
def image_materials(image_key):
# returns a list of material keys that use the image
# Only returns materials that are actually used (in scenes)
# This ensures images are correctly detected as unused when their
# materials are unused (fixes issue #5)
users = []
image = bpy.data.images[image_key]
@@ -263,6 +294,13 @@ def image_materials(image_key):
node_group_users = image_node_groups(image_key)
for mat in bpy.data.materials:
# Skip library-linked and override materials
from ..utils import compat
if compat.is_library_or_override(mat):
continue
# Check if this material uses the image
material_uses_image = False
# if material uses a valid node tree, check each node
if mat.use_nodes and mat.node_tree:
@@ -273,7 +311,7 @@ def image_materials(image_key):
# if the nodes image is our image
if node.image.name == image.name:
users.append(mat.name)
material_uses_image = True
# if image in node in node group in node tree
elif node.type == 'GROUP':
@@ -282,23 +320,38 @@ def image_materials(image_key):
# list of node groups that use this image
if node.node_tree and \
node.node_tree.name in node_group_users:
users.append(mat.name)
material_uses_image = True
# Only add material if it uses the image AND is actually used
if material_uses_image:
# Check if material is actually used (in scenes)
if material_all(mat.name):
users.append(mat.name)
return distinct(users)
def image_node_groups(image_key):
# returns a list of keys of node groups that use this image
# Only returns node groups that are actually used (in scenes)
# This ensures images are correctly detected as unused when their
# node groups are unused (fixes issue #5)
users = []
image = bpy.data.images[image_key]
# for each node group
for node_group in bpy.data.node_groups:
# Skip library-linked and override node groups
from ..utils import compat
if compat.is_library_or_override(node_group):
continue
# if node group contains our image
if node_group_has_image(node_group.name, image.name):
users.append(node_group.name)
# Only add node group if it is actually used (in scenes)
if node_group_all(node_group.name):
users.append(node_group.name)
return distinct(users)
@@ -349,6 +402,9 @@ def image_textures(image_key):
def image_geometry_nodes(image_key):
# returns a list of object keys that use the image through Geometry Nodes
# Only returns objects that are actually used (in scenes)
# This ensures images are correctly detected as unused when their
# objects are unused (fixes issue #5)
users = []
image = bpy.data.images[image_key]
@@ -360,6 +416,19 @@ def image_geometry_nodes(image_key):
from ..utils import compat
for obj in bpy.data.objects:
# Skip library-linked and override objects
if compat.is_library_or_override(obj):
continue
# Check if object is in any scene collection (reuse object_all logic)
# This ensures recursive checking: if the object using the image isn't in a scene,
# the image isn't considered used
obj_scenes = object_all(obj.name)
is_in_scene = bool(obj_scenes)
if not is_in_scene:
continue # Skip objects not in scene collections
# check Geometry Nodes modifiers
if hasattr(obj, 'modifiers'):
for modifier in obj.modifiers:
@@ -438,6 +507,65 @@ def material_all(material_key):
# Check node group usage (materials in node groups used elsewhere)
users.extend(material_node_groups(material_key))
# Check brush usage (materials used by brushes for stroke)
users.extend(material_brushes(material_key))
return distinct(users)
def material_brushes(material_key):
# returns a list of brush keys that use this material
# Brushes use materials for stroke rendering (Grease Pencil brushes)
users = []
try:
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return []
if not hasattr(bpy.data, 'brushes'):
return []
for brush in bpy.data.brushes:
# Grease Pencil brushes use materials via gpencil_settings
if hasattr(brush, 'gpencil_settings'):
gp_settings = brush.gpencil_settings
if gp_settings:
# Check material property in gpencil_settings
if hasattr(gp_settings, 'material'):
gp_mat = gp_settings.material
# Compare by datablock reference to avoid matching linked materials with same name
if gp_mat and gp_mat == material:
users.append(brush.name)
# Check material_index - need to get material from Grease Pencil object
if hasattr(gp_settings, 'material_index'):
mat_idx = gp_settings.material_index
# Check all Grease Pencil objects for this material
for gp_obj in bpy.data.objects:
if gp_obj.type == 'GPENCIL' and gp_obj.data:
gp_data = gp_obj.data
if hasattr(gp_data, 'materials') and gp_data.materials:
if 0 <= mat_idx < len(gp_data.materials):
gp_mat = gp_data.materials[mat_idx]
# Compare by datablock reference to avoid matching linked materials with same name
if gp_mat and gp_mat == material:
users.append(brush.name)
# Also check for stroke_material (some brush types)
if hasattr(brush, 'stroke_material'):
stroke_mat = brush.stroke_material
# Compare by datablock reference to avoid matching linked materials with same name
if stroke_mat and stroke_mat == material:
users.append(brush.name)
# Check for material property (some brush types)
if hasattr(brush, 'material'):
mat = brush.material
# Compare by datablock reference to avoid matching linked materials with same name
if mat and mat == material:
users.append(brush.name)
return distinct(users)
@@ -446,7 +574,10 @@ def material_geometry_nodes(material_key):
# Only counts objects that are in scene collections (recursive check)
users = []
material = bpy.data.materials[material_key]
try:
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return []
# Import compat module for version-safe geometry nodes access
from ..utils import compat
@@ -471,7 +602,8 @@ def material_geometry_nodes(material_key):
ng = compat.get_geometry_nodes_modifier_node_group(modifier)
if ng:
# Check if this node group or any nested node groups contain the material
if node_group_has_material(ng.name, material.name):
# Pass material datablock reference to ensure we match the correct material
if node_group_has_material_by_ref(ng.name, material):
users.append(obj.name)
return distinct(users)
@@ -486,14 +618,18 @@ def material_node_groups(material_key):
# Optimized to return early when usage is found
from ..utils import compat
material = bpy.data.materials[material_key]
try:
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return []
# Check all node groups to see if they contain this material
for node_group in bpy.data.node_groups:
# Skip library-linked and override node groups
if compat.is_library_or_override(node_group):
continue
if node_group_has_material(node_group.name, material.name):
# Use the by_ref version to avoid name collision issues with linked materials
if node_group_has_material_by_ref(node_group.name, material):
# This node group contains the material, check if the node group is used
# Check usage contexts in order of likelihood, return early when found
@@ -550,11 +686,40 @@ def material_node_groups(material_key):
return [] # Material not used in any node groups
def material_node_groups_list(material_key):
# returns a list of node group names that contain this material
# This is used for inspection UI to show which node groups use the material
# Unlike material_node_groups(), this returns all node groups that contain
# the material, regardless of whether they're used
from ..utils import compat
users = []
try:
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return []
# Check all node groups to see if they contain this material
for node_group in bpy.data.node_groups:
# Skip library-linked and override node groups
if compat.is_library_or_override(node_group):
continue
# Use the by_ref version to avoid name collision issues with linked materials
if node_group_has_material_by_ref(node_group.name, material):
users.append(node_group.name)
return distinct(users)
def material_objects(material_key):
# returns a list of object keys that use this material
users = []
material = bpy.data.materials[material_key]
try:
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return []
for obj in bpy.data.objects:
@@ -564,10 +729,12 @@ def material_objects(material_key):
# for each material slot
for slot in obj.material_slots:
# if material slot has a valid material and it is our
# material
if slot.material and slot.material.name == material.name:
users.append(obj.name)
# if material slot has a valid material, check if it's our material
# Compare by datablock reference first to avoid matching linked materials with same name
if slot.material:
# Compare by reference (handles name collisions between local and linked materials)
if slot.material == material:
users.append(obj.name)
return distinct(users)
@@ -585,7 +752,7 @@ def node_group_all(node_group_key):
def node_group_compositors(node_group_key):
# returns a list containing "Compositor" if the node group is used in
# the scene's compositor
# any scene's compositor (either as the compositor's node tree itself, or as a node within it)
users = []
node_group = bpy.data.node_groups[node_group_key]
@@ -593,27 +760,40 @@ def node_group_compositors(node_group_key):
# a list of node groups that use our node group
node_group_users = node_group_node_groups(node_group_key)
# Import compat module for version-safe compositor access
# Import compat and version modules for version-safe compositor access
from ..utils import compat
from ..utils import version
# if our compositor uses nodes and has a valid node tree
scene = bpy.context.scene
if scene.use_nodes:
node_tree = compat.get_scene_compositor_node_tree(scene)
if node_tree:
# check each node in the compositor
for node in node_tree.nodes:
# if the node is a group and has a valid node tree
if hasattr(node, 'node_tree') and node.node_tree:
# if the node group is our node group
if node.node_tree.name == node_group.name:
users.append("Compositor")
# if the node group is in our list of node group users
if node.node_tree.name in node_group_users:
users.append("Compositor")
# Check ALL scenes, not just the current one
for scene in bpy.data.scenes:
# First check: is this node group the compositor's node tree itself?
if version.is_version_at_least(5, 0, 0):
if hasattr(scene, 'compositing_node_tree') and scene.compositing_node_tree:
# Check by reference, not just name (in case user renamed it)
if scene.compositing_node_tree == node_group:
users.append("Compositor")
continue # Already found, skip checking nodes within it
else:
if hasattr(scene, 'node_tree') and scene.node_tree:
# Check by reference, not just name (in case user renamed it)
if scene.node_tree == node_group:
users.append("Compositor")
continue # Already found, skip checking nodes within it
# Second check: is this node group used as a node within the compositor?
if scene.use_nodes:
node_tree = compat.get_scene_compositor_node_tree(scene)
if node_tree:
# check each node in the compositor
for node in node_tree.nodes:
# if the node is a group and has a valid node tree
if hasattr(node, 'node_tree') and node.node_tree:
# if the node group is our node group (check by reference)
if node.node_tree == node_group:
users.append("Compositor")
# if the node group is in our list of node group users
elif node.node_tree.name in node_group_users:
users.append("Compositor")
return distinct(users)
@@ -621,6 +801,8 @@ def node_group_compositors(node_group_key):
def node_group_materials(node_group_key):
# returns a list of material keys that use the node group in their
# node trees
# Note: Unlike image_materials(), this returns ALL materials using the node group,
# not just used ones. This allows node_groups_deep() to check if materials are unused.
users = []
node_group = bpy.data.node_groups[node_group_key]
@@ -629,6 +811,10 @@ def node_group_materials(node_group_key):
node_group_users = node_group_node_groups(node_group_key)
for material in bpy.data.materials:
# Skip library-linked and override materials
from ..utils import compat
if compat.is_library_or_override(material):
continue
# if material uses nodes and has a valid node tree, check each node
if material.use_nodes and material.node_tree:
@@ -754,6 +940,31 @@ def node_group_objects(node_group_key):
return distinct(users)
def _check_node_input_sockets_for_image(node, image_key):
"""Helper function to check if any input socket of a node contains the image.
This handles nodes like Menu Switch that have materials/images in input sockets."""
try:
image = bpy.data.images[image_key]
if not hasattr(node, 'inputs'):
return False
for input_socket in node.inputs:
try:
# Check if socket has a default_value that is an image
if hasattr(input_socket, 'default_value') and input_socket.default_value:
socket_value = input_socket.default_value
# Check if it's an image datablock
if hasattr(socket_value, 'name') and hasattr(socket_value, 'filepath'):
if socket_value.name == image.name or socket_value == image:
return True
except (AttributeError, ReferenceError, RuntimeError, TypeError, KeyError):
continue # Skip this socket if we can't access it
except (KeyError, AttributeError):
return False
return False
def node_group_has_image(node_group_key, image_key):
# recursively returns true if the node group contains this image
# directly or if it contains a node group a node group that contains
@@ -774,9 +985,14 @@ def node_group_has_image(node_group_key, image_key):
if node.image.name == image.name:
has_image = True
# Check input sockets for images (e.g., Menu Switch nodes)
# This handles nodes that have images connected via input sockets
if not has_image:
has_image = _check_node_input_sockets_for_image(node, image_key)
# recurse case
# if node is a node group and has a valid node tree
elif hasattr(node, 'node_tree') and node.node_tree:
if not has_image and hasattr(node, 'node_tree') and node.node_tree:
has_image = node_group_has_image(
node.node_tree.name, image.name)
@@ -855,15 +1071,51 @@ def node_group_has_texture(node_group_key, texture_key):
return has_texture
def node_group_has_material(node_group_key, material_key):
def _check_node_input_sockets_for_material(node, material_key):
"""Helper function to check if any input socket of a node contains the material.
This handles nodes like Menu Switch that have materials in input sockets."""
try:
material = bpy.data.materials[material_key]
return _check_node_input_sockets_for_material_by_ref(node, material)
except (KeyError, AttributeError):
return False
def _check_node_input_sockets_for_material_by_ref(node, material):
"""Helper function to check if any input socket of a node contains the material.
Takes material datablock directly to avoid name collision issues with linked materials."""
if not material or not hasattr(node, 'inputs'):
return False
for input_socket in node.inputs:
try:
# Check socket type - material sockets are typically 'MATERIAL' type
socket_type = getattr(input_socket, 'type', '')
if socket_type == 'MATERIAL' or 'material' in str(socket_type).lower():
# Check if this socket has a default_value that is a material
if hasattr(input_socket, 'default_value') and input_socket.default_value:
socket_material = input_socket.default_value
# Compare by datablock reference to avoid matching linked materials with same name
if socket_material and socket_material == material:
return True
except (AttributeError, ReferenceError, RuntimeError, TypeError, KeyError):
continue # Skip this socket if we can't access it
return False
def node_group_has_material_by_ref(node_group_key, material):
# returns true if a node group contains this material (directly or nested)
# Takes material datablock directly to avoid name collision issues with linked materials
has_material = False
try:
node_group = bpy.data.node_groups[node_group_key]
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return False
if not material:
return False
try:
for node in node_group.nodes:
@@ -883,10 +1135,9 @@ def node_group_has_material(node_group_key, material_key):
# Check the default_value (for unlinked materials)
if hasattr(material_socket, 'default_value'):
socket_material = material_socket.default_value
if socket_material and hasattr(socket_material, 'name'):
if (socket_material.name == material.name or
socket_material == material):
has_material = True
# Compare by datablock reference to avoid matching linked materials with same name
if socket_material and socket_material == material:
has_material = True
except (KeyError, AttributeError, ReferenceError, RuntimeError, TypeError):
pass
@@ -900,11 +1151,10 @@ def node_group_has_material(node_group_key, material_key):
# Check if this socket has a default_value that is a material
if hasattr(input_socket, 'default_value') and input_socket.default_value:
socket_material = input_socket.default_value
if socket_material and hasattr(socket_material, 'name'):
if (socket_material.name == material.name or
socket_material == material):
has_material = True
break # Found it, no need to continue
# Compare by datablock reference to avoid matching linked materials with same name
if socket_material and socket_material == material:
has_material = True
break # Found it, no need to continue
except (AttributeError, ReferenceError, RuntimeError, TypeError):
continue # Skip this socket if we can't access it
@@ -912,8 +1162,8 @@ def node_group_has_material(node_group_key, material_key):
if not has_material and hasattr(node, 'material'):
try:
if node.material:
if (node.material.name == material.name or
node.material == material):
# Compare by datablock reference to avoid matching linked materials with same name
if node.material == material:
has_material = True
break # Found it, no need to continue
except (AttributeError, ReferenceError, RuntimeError):
@@ -926,14 +1176,33 @@ def node_group_has_material(node_group_key, material_key):
except (AttributeError, ReferenceError, RuntimeError):
pass # Skip if bl_idname access fails
# Check for Menu Switch nodes and other nodes with material inputs
# Menu Switch nodes can have materials in any of their input sockets
if not has_material and hasattr(node, 'bl_idname'):
try:
node_type = node.bl_idname
# Check for Menu Switch node (GeometryNodeMenuSwitch)
if node_type == 'GeometryNodeMenuSwitch' or 'MenuSwitch' in node_type:
has_material = _check_node_input_sockets_for_material_by_ref(node, material)
if has_material:
break
except (AttributeError, ReferenceError, RuntimeError):
pass # Skip if bl_idname access fails
# General check: Check all input sockets for materials (catches other node types)
# This is a fallback for any node that might have material inputs
if not has_material:
has_material = _check_node_input_sockets_for_material_by_ref(node, material)
if has_material:
break
# Fallback: Check for any node with a material property (e.g., Set Material)
# This catches other node types that might have materials
if not has_material and hasattr(node, 'material'):
try:
if node.material:
# Check both by name and by direct reference for robustness
if (node.material.name == material.name or
node.material == material):
# Compare by datablock reference to avoid matching linked materials with same name
if node.material == material:
has_material = True
break # Found it, no need to continue
except (AttributeError, ReferenceError, RuntimeError):
@@ -948,8 +1217,8 @@ def node_group_has_material(node_group_key, material_key):
if hasattr(node, 'material'):
try:
if node.material:
if (node.material.name == material.name or
node.material == material):
# Compare by datablock reference to avoid matching linked materials with same name
if node.material == material:
has_material = True
break
except (AttributeError, ReferenceError, RuntimeError):
@@ -962,8 +1231,8 @@ def node_group_has_material(node_group_key, material_key):
if not has_material and hasattr(node, 'node_tree'):
try:
if node.node_tree:
has_material = node_group_has_material(
node.node_tree.name, material.name)
has_material = node_group_has_material_by_ref(
node.node_tree.name, material)
except (KeyError, AttributeError, ReferenceError, RuntimeError):
continue # Skip invalid node groups
@@ -979,6 +1248,18 @@ def node_group_has_material(node_group_key, material_key):
return has_material
def node_group_has_material(node_group_key, material_key):
# returns true if a node group contains this material (directly or nested)
# Wrapper that converts material_key to material datablock for reference-based comparison
try:
material = bpy.data.materials[material_key]
except (KeyError, AttributeError):
return False
return node_group_has_material_by_ref(node_group_key, material)
def particle_all(particle_key):
# returns a list of keys of every data-block that uses this particle
# system
@@ -1168,22 +1449,68 @@ def texture_particles(texture_key):
return distinct(users)
def object_all(object_key):
def object_all(object_key, _visited_objects=None):
# returns a list of scene names where the object is used
# An object is "used" if it's in any collection that's part of any scene's collection hierarchy
# OR if it's in a collection that is instanced (and that instance is in a scene)
# _visited_objects is used to prevent infinite recursion when checking instanced collections
users = []
obj = bpy.data.objects[object_key]
if _visited_objects is None:
_visited_objects = set()
# Prevent infinite recursion
if object_key in _visited_objects:
return []
_visited_objects.add(object_key)
try:
users = []
obj = bpy.data.objects[object_key]
# Get all collections that contain this object
for collection in obj.users_collection:
# Check if this collection is in any scene's hierarchy
for scene in bpy.data.scenes:
if _scene_collection_contains(scene.collection, collection):
if scene.name not in users:
users.append(scene.name)
return distinct(users)
# Get all collections that contain this object
for collection in obj.users_collection:
# Check if this collection is in any scene's hierarchy
for scene in bpy.data.scenes:
if _scene_collection_contains(scene.collection, collection):
if scene.name not in users:
users.append(scene.name)
# Also check if this collection is instanced (and the instance is in a scene)
# Get all objects that instance this collection
for instance_obj in bpy.data.objects:
# Skip library-linked and override objects
if compat.is_library_or_override(instance_obj):
continue
# Check if object is a collection instance
if hasattr(instance_obj, 'instance_type') and instance_obj.instance_type == 'COLLECTION':
if hasattr(instance_obj, 'instance_collection') and instance_obj.instance_collection:
if instance_obj.instance_collection.name == collection.name:
# Check if the instance object is in a scene (using visited set to prevent recursion)
# First check if instance object is directly in a scene collection
instance_direct_scenes = []
for instance_collection in instance_obj.users_collection:
for scene in bpy.data.scenes:
if _scene_collection_contains(scene.collection, instance_collection):
if scene.name not in instance_direct_scenes:
instance_direct_scenes.append(scene.name)
# If instance object is directly in a scene, the instanced collection's objects are used
if instance_direct_scenes:
for scene_name in instance_direct_scenes:
if scene_name not in users:
users.append(scene_name)
else:
# Instance object is not directly in a scene, but might be in an instanced collection
# Recursively check (with visited set to prevent infinite loops)
instance_scenes = object_all(instance_obj.name, _visited_objects)
for scene_name in instance_scenes:
if scene_name not in users:
users.append(scene_name)
return distinct(users)
finally:
_visited_objects.remove(object_key)
def armature_all(armature_key):