.. _to_blender_object_and_helper:

The Functions to_blender_object and to_blender_object_helper
============================================================

.. note::
   First steps on how to run a script in Blender can be found :ref:`here <blender_getting_started>`.

The functions that visualize ddg objects in Blender are located in the package
:py:mod:`ddg.conversion.blender`. The main function is
:py:func:`~ddg.conversion.blender.core.to_blender_object`, which converts ddg objects to Blender objects, i.e. visualizes them. 

The following objects can be passed to :py:func:`~ddg.conversion.blender.core.to_blender_object` directly:

    - :py:class:`~ddg.datastructures.nets.net.EmptyNet`
    - :py:class:`~ddg.datastructures.nets.net.PointNet`
    - :py:class:`~ddg.datastructures.nets.net.DiscreteNet`
    - :py:class:`~ddg.datastructures.nets.net.DiscreteCurve`
    - :py:class:`~ddg.datastructures.nets.net.NetCollection` (containing discrete nets/curves)
    - :py:class:`~ddg.datastructures.halfedge.surface.Surface`

Other objects, e. g. :ref:`geometric objects <geometry>` or :py:class:`~ddg.datastructures.nets.net.SmoothNet`
have to be converted to one of the above and can not be handed :py:func:`~ddg.conversion.blender.core.to_blender_object` directly.
The conversion can either be done manually or the function :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`
can be used to internally convert and visualize.
For all ddg objects there exist specific guides:

.. toctree::
    :titlesonly:
    :maxdepth: 2
    :glob:

    visualizing_halfedge
    visualizing_nets
    visualizing_subspaces
    visualizing_quadrics
    visualizing_spheres

Here we provide an overview of the general usage of
:py:func:`~ddg.conversion.blender.core.to_blender_object`
and :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`:

.. contents::
   :local:
   :backlinks: none

.. _to_blender_object:

Using to_blender_object
-----------------------

The usage of :py:func:`~ddg.conversion.blender.core.to_blender_object` is straight forward:

.. doctest::

    >>> import ddg
    >>> cube = ddg.datastructures.halfedge.surface_generator.cube()
    >>> blender_object = ddg.to_blender_object(cube)

The signature :py:func:`~ddg.conversion.blender.core.to_blender_object` reads

.. code-block:: python

   >>> def to_blender_object(
   ...     obj,
   ...     accept_all=False,
   ...     depth_bounding=10,
   ...     attributes={},
   ...     material=None,
   ...     collection=None,
   ...     mesh_transformations=[],
   ...     bmesh_transformations=[],
   ...     obj_transformations=[],
   ...     link=True,
   ...     **options
   ... ):
   ...     ...

with the parameters/docstring

.. include:: _to_blender_object/docstring.txt
    :start-line: 9
    :end-line: 93

.. seealso::

    Api documentation of :py:func:`~ddg.conversion.blender.core.to_blender_object`.

Here are some examples:

.. doctest::

    >>> ddg.to_blender_object(
    ...     cube,
    ...     attributes={
    ...         "name": "Cube",
    ...         "location": [1, 1, 1],
    ...         "hide_viewport": False,
    ...         "hide_render": False,
    ...         "scale": [0.5, 0.5, 1],
    ...     },
    ... )
    bpy.data.objects['Cube']

.. doctest::

    >>> col = ddg.visualization.blender.collection.collection("cube_collection")
    >>> black = ddg.visualization.blender.material.material(color=(0, 0, 0))
    >>> ddg.to_blender_object(
    ...     cube,
    ...     attributes={"name": "Cube with material"},
    ...     collection=col,
    ...     material=black,
    ... )
    bpy.data.objects['Cube with material']

.. doctest::

    >>> from ddg.visualization.blender.mesh import shade_smooth
    >>> from ddg.visualization.blender.bmesh import cut_bounding_box
    >>> import numpy as np

    >>> def cut_bb_trafo(bmesh):
    ...     return cut_bounding_box(
    ...         bmesh, np.array([1, 1, 1]), center=np.array([1, 1, 1])
    ...     )
    ...

    >>> ddg.to_blender_object(
    ...     cube,
    ...     attributes={"name": "Transformed cube"},
    ...     mesh_transformations=[shade_smooth],
    ...     bmesh_transformations=[cut_bb_trafo],
    ... )
    bpy.data.objects['Transformed cube']



.. _to_blender_object_helper:

Using to_blender_object_helper
------------------------------

The function :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`
combines the following

    - easy handling of commonly used keyword arguments
    - conversion to objects that can be visualized
    - calling the function :py:func:`~ddg.conversion.blender.core.to_blender_object`.

Its signature and docstring reads

.. code-block:: python

    >>> def to_blender_object_helper(
    ...     obj,
    ...     name=None,
    ...     location=None,
    ...     hide_viewport=None,
    ...     hide_render=None,
    ...     scale=None,
    ...     shade_smooth=False,
    ...     bounding_box=None,
    ...     accept_all=False,
    ...     material=None,
    ...     collection=None,
    ...     **kwargs
    ... ):
    ...     ...


.. seealso::

    Api documentation of :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`.

Here are the examples from above using the helper function:

.. doctest::

    >>> ddg.to_blender_object_helper(
    ...     cube,
    ...     name="Cube to_blender_object_helper version",
    ...     location=[1, 1, 1],
    ...     hide_viewport=False,
    ...     hide_render=False,
    ...     scale=[0.5, 0.5, 1],
    ... )
    bpy.data.objects['Cube to_blender_object_helper version']

.. doctest::

    >>> col = ddg.visualization.blender.collection.collection("cube_collection")
    >>> black = ddg.visualization.blender.material.material(color=(0, 0, 0))
    >>> ddg.to_blender_object_helper(
    ...     cube,
    ...     name="Cube with material to_blender_object_helper version",
    ...     collection=col,
    ...     material=black,
    ... )
    bpy.data.objects['Cube with material to_blender_object_helper version']

.. doctest::

    >>> ddg.to_blender_object_helper(
    ...     cube,
    ...     name="Cube with smooth shading and bounding box",
    ...     shade_smooth=True,
    ...     bounding_box=[1, 1, 1],
    ... )
    bpy.data.objects['Cube with smooth shading and bounding box']

.. note::

    The function :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`
    only supports bounding boxes with ``center=[0,0,0]``.