Linked Duplicate Blender Objects
================================

One can reuse the data (eg. mesh, bmesh, light, camera, etc.) of an existing Blender object
in other new Blender objects using

    - :py:func:`~ddg.visualization.blender.mesh.duplicate_by_properties`.
    - :py:func:`~ddg.visualization.blender.mesh.duplicate_by_transformation_matrices`.
    - :py:func:`~ddg.visualization.blender.mesh.duplicate_linked`.

In the most common use case, this data is a mesh. The resulting Blender objects then share the same mesh,
which can be modified (for exemple in edit mode) to affect all the objects simultaneously.
In order to place the newly created objects in space, a list of 4x4 matrices reprensenting
the transformations from the original object must be passed.

In this example we create 3 linked duplicates of an octahedron.
The first is just translated, the second is rotated and the last is scaled.

   >>> import bpy
   >>> import ddg
   >>> import numpy as np
   >>> import ddg.datastructures.halfedge.surface_generator as gen
   >>> from ddg.visualization.blender.mesh import duplicate_by_transformation_matrices
   >>> from ddg.math.euclidean import rotation_angle_axis
   >>> obj = gen.octahedron()
   >>> bobj = ddg.to_blender_object_helper(obj)
   >>> xTranslation = np.array([[1, 0, 0, 4], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]])
   >>> rotation = rotation_angle_axis((0, 1, 0))
   >>> scaling = np.diag([1, 2, 3, 1])
   >>> matrices = [
   ...     xTranslation,
   ...     xTranslation @ xTranslation @ rotation,
   ...     xTranslation @ xTranslation @ xTranslation @ scaling,
   ... ]
   >>> duplicates = duplicate_by_transformation_matrices(
   ...     bobj, matrices, bpy.context.collection
   ... )

In the most common use case, this data is a mesh. The resulting Blender objects then share the same mesh,
which can be modified (for exemple in edit mode) to affect all the objects simultaneously.
In order to place the newly created objects in space, a list of 4x4 matrices reprensenting
the transformations from the original object must be passed.

The result can be seen here :

.. image:: linked_duplicates.png
    :width: 800px
    :align: center

We can then modify the mesh (here we removed a vertex):

.. image:: linked_duplicates_modified.png
    :width: 800px
    :align: center