Clear Functions

Clear functions are used to remove different kinds of objects or data in a Blender scene. They are located in ddg.visualization.blender in the modules of the kind of Blender data they clear. For example, to delete collections, you can use collection.clear().

Clearing Objects in Scenes and Collections

To clear your whole Blender scene, you can use the functions scene.clear(), collection.clear(), or object.clear(). This is particularly useful in the beginning of a script, to avoid multiplying objects when re-running the script.

For example, to clear all objects in a scene one would run scene.clear().

>>> import ddg
>>> import ddg.visualization.blender as butils
>>> from ddg.visualization.blender import scene, collection
>>> scene.clear()

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

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

Each function takes an Iterable of the specified object, i.e. scene.clear() takes an Iterable of scenes and object.clear() takes an Iterable of objects.

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

>>> light4 = butils.light.light("L4")
>>> bpy.data.lights.values()
[bpy.data.lights['L1'], bpy.data.lights['L2'], bpy.data.lights['L3'], bpy.data.lights['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.

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

The optional argument remove_collections in collection.clear() and scene.clear() 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']]
>>> butils.collection.clear(remove_collections=True)
>>> bpy.data.collections.values()
[]

Note that not removing collections does not lead to multiplicity of collections when re-running scripts.

Clearing Specific Objects

Further, there are clear functions for the specific types of objects or data created with pyddg. Those functions are mesh.clear(), light.clear(), curve.clear(), camera.clear(), material.clear(), object.clear_lattices(), object.clear_empty_objects(), etc.

Similar to the functions in the previous section, if no Iterable is provided, the function clears all objects of the respective type from the scene.

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

>>> light1 = butils.light.light("L1")
>>> bpy.data.lights.values()
[bpy.data.lights['L1'], bpy.data.lights['L1.001'], bpy.data.lights['L2'], bpy.data.lights['L3']]
>>> butils.light.clear()
>>> bpy.data.lights.values()
[]

The optional argument only_unused can be used in ddg.visualization.mesh.clear() and material.clear() 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['an_unused_mesh']
>>> bpy.data.meshes.values()
[bpy.data.meshes['an_unused_mesh'], bpy.data.meshes['halfedge_object']]
>>> butils.mesh.clear(only_unused=True)
>>> bpy.data.meshes.values()  # Used mesh still exists
[bpy.data.meshes['halfedge_object']]
>>> butils.mesh.clear()
>>> bpy.data.meshes.values()
[]