Clear utils

Clear utils are used to clear different elements and objects in a Blender scene.

Each function deletes different types of elements in a scene. From general objects and collections to specific types of objects (i.e. lights, meshes, etc.).

Clearing objects in scenes and collections

The functions clear_scene(), clear_collections(), and clear_objects() are generally used to clear objects.

For example, to clear entire objects in a scene one would run clear_scene(). This is particularly useful to clean up objects before running a code (An alternative is clear_all()).

>>> import ddg
>>> from ddg.visualization.blender import clear
>>> clear.clear_scene()

If an iterable is not provided as an argument, these functions will delete all available objects within a scene.

>>> from ddg.visualization.blender.collection import collection
>>> from ddg.visualization.blender.light import light
>>> coll1 = collection('1')
>>> coll2 = collection('2')
>>> coll3 = collection('3')
>>> light1 = light('L1', collection=coll1)
>>> light2 = light('L2', collection=coll2)
>>> light3 = light('L3', collection=coll3)
>>> bpy.data.objects.values() 
[bpy.data.objects['L1'], bpy.data.objects['L2'], bpy.data.objects['L3']]
>>> clear.clear_collections([coll3, coll1])
>>> bpy.data.objects.values() 
[bpy.data.objects['L2']]
>>> clear.clear_collections()
>>> bpy.data.objects.values() 
[]

Each function takes iterable of the specified object, i.e. clear_scene() takes iterable of scenes and clear_objects() takes iterable of objects.

The default options for clearing of objects, with the exception of clear_objects(), only perform an unlink.

>>> light4=light('L4')
>>> bpy.data.lights.values() 
[bpy.data.objects['L1'], bpy.data.objects['L2'], bpy.data.objects['L3'], bpy.data.objects['L4']]
>>> bpy.data.objects.values() 
[bpy.data.objects['L4']]

Note that L1, L2, and L3 are examples of orphaned data. They are no longer contained in the list of objects but are still stored in memory. The boolean optional argument deep gives the option to delete the data of objects.

>>> clear.clear_collections(deep=True)
>>> bpy.data.lights.values() 
[bpy.data.objects['L1'], bpy.data.objects['L2'], bpy.data.objects['L3']]
>>> bpy.data.objects.values() 
[]

The optional argument remove_collections in clear_collections() and clear_scene() is used if one wants to remove the collections along with its children in a given scene or lists of collections.

>>> bpy.data.collections.values() 
[bpy.data.collections['1'], bpy.data.collections['2'], bpy.data.collections['3']]
>>> clear.clear_collections(remove_collections=True)
>>> bpy.data.collections.values() 
[]

Clearing specific objects

Clear utils also provides functionality to clear specific objects with clear_meshes(), clear_lights(), clear_lattices(), clear_curves(), clear_cameras(), clear_material(), clear_empty_objects(), etc.

Similar to the functions in the previous section, if an iterable is not provided, the function will clear an entire scene of that specific object.

Note that contrary to the functions that clear general objects, using these functions does remove data from memory.

>>> light1 = light('L1')
>>> bpy.data.lights.values() 
[bpy.data.objects['L1']]
>>> clear.clear_lights()
>>> bpy.data.lights.values() 
[]

The optional argument only_unused can be used in clear_meshes() and clear_material() to respectively remove meshes or materials that are not used in a scene.

>>> from ddg.datastructures.halfedge.surface_generator import cube
>>> import bpy 
>>> cube1=ddg.to_blender_object(cube()) # Generates a cube that uses a mesh
>>> bpy.data.meshes.new("an_unused_mesh") 
>>> bpy.data.meshes.values() 
[bpy.data.meshes['halfedge_object'], bpy.data.meshes['an_unused_mesh']]
>>> clear.clear_meshes(only_unused=True)
>>> bpy.data.meshes.values() 
[bpy.data.meshes['halfedge_object']] # Used mesh still exists
>>> clear.clear_meshes()
>>> bpy.data.meshes.values() 
[]