.. _blender_utils_clear:

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 :py:func:`~ddg.visualization.blender.utils.clear.clear_scene`, :py:func:`~ddg.visualization.blender.utils.clear.clear_collections`, and :py:func:`~ddg.visualization.blender.utils.clear.clear_objects` are generally used to clear objects.

For example, to clear entire objects in a scene one would run :py:func:`~ddg.visualization.blender.clear.clear_scene`. This is particularly useful to clean up objects before running a code (An alternative is :py:func:`~ddg.visualization.blender.clear.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() # doctest: +SKIP
[bpy.data.objects['L1'], bpy.data.objects['L2'], bpy.data.objects['L3']]
>>> clear.clear_collections([coll3, coll1])
>>> bpy.data.objects.values() # doctest: +SKIP
[bpy.data.objects['L2']]
>>> clear.clear_collections()
>>> bpy.data.objects.values() # doctest: +SKIP
[]

Each function takes iterable of the specified object, i.e. :py:func:`~ddg.visualization.blender.clear.clear_scene` takes iterable of scenes and :py:func:`~ddg.visualization.blender.clear.clear_objects` takes iterable of objects.

The default options for clearing of objects, with the exception of :py:func:`~ddg.visualization.blender.clear.clear_objects`, only perform an unlink.

>>> light4=light('L4')
>>> bpy.data.lights.values() # doctest: +SKIP
[bpy.data.objects['L1'], bpy.data.objects['L2'], bpy.data.objects['L3'], bpy.data.objects['L4']]
>>> bpy.data.objects.values() # doctest: +SKIP
[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() # doctest: +SKIP
[bpy.data.objects['L1'], bpy.data.objects['L2'], bpy.data.objects['L3']]
>>> bpy.data.objects.values() # doctest: +SKIP
[]

The optional argument ``remove_collections`` in :py:func:`~ddg.visualization.blender.clear.clear_collections` and :py:func:`~ddg.visualization.blender.clear.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() # doctest: +SKIP
[bpy.data.collections['1'], bpy.data.collections['2'], bpy.data.collections['3']]
>>> clear.clear_collections(remove_collections=True)
>>> bpy.data.collections.values() # doctest: +SKIP
[]

Clearing specific objects
-------------------------

Clear utils also provides functionality to clear specific objects with :py:func:`~ddg.visualization.blender.clear.clear_meshes`, :py:func:`~ddg.visualization.blender.clear.clear_lights`, :py:func:`~ddg.visualization.blender.clear.clear_lattices`, :py:func:`~ddg.visualization.blender.clear.clear_curves`, :py:func:`~ddg.visualization.blender.clear.clear_cameras`, :py:func:`~ddg.visualization.blender.clear.clear_material`, :py:func:`~ddg.visualization.blender.clear.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() # doctest: +SKIP
[bpy.data.objects['L1']]
>>> clear.clear_lights()
>>> bpy.data.lights.values() # doctest: +SKIP
[]

The optional argument ``only_unused`` can be used in :py:func:`~ddg.visualization.blender.clear.clear_meshes` and :py:func:`~ddg.visualization.blender.clear.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 # doctest: +SKIP
>>> cube1=ddg.to_blender_object(cube()) # Generates a cube that uses a mesh
>>> bpy.data.meshes.new("an_unused_mesh") # doctest: +SKIP
>>> bpy.data.meshes.values() # doctest: +SKIP
[bpy.data.meshes['halfedge_object'], bpy.data.meshes['an_unused_mesh']]
>>> clear.clear_meshes(only_unused=True)
>>> bpy.data.meshes.values() # doctest: +SKIP
[bpy.data.meshes['halfedge_object']] # Used mesh still exists
>>> clear.clear_meshes()
>>> bpy.data.meshes.values() # doctest: +SKIP
[]