.. _new_api:

Visualizing low-level geometric data in Blender
===============================================

The library provides some utilities to directly visualize low-level representations of geometric objects.
This can be useful when you want to visualize something that is not a data structure of the library.
Note that this is also what is used under the hood to visualize these data structures.

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: the module]
   :end-before: [end: the module]

Let's setup a Blender scene:

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: setup]
   :end-before: [end: setup]

Meshes
------

A mesh can be represented as a set of vertices and a set of faces. This is called an indexed face set.
Our library provides a very powerful version of IFS, but for sole visualization purposes, having a set of vertices and a set of faces is enough.

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: mesh data]
   :end-before: [end: mesh data]

To visualize this object, one can go step by step,
creating a Blender mesh, adding it to a Blender object and linking this object to a collection of the scene:

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: manual mesh]
   :end-before: [end: manual mesh]

..  image:: new_api/square-before-transformation.png
    :alt: square-before-transformation

One can also apply arbitrary transformations on the mesh to satisfy the visualization purposes:

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: manual mesh trafo]
   :end-before: [end: manual mesh trafo]

..  image:: new_api/square-after-transformation.png
    :alt: square-after-transformation

The steps of the conversion can be reduced to one step by using :py:func:`~ddg.visualization.blender.mesh.mesh_object`

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: new api mesh]
   :end-before: [end: new api mesh]

Curves
------

Similarly curves can be represented as a set of points.

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: curve data]
   :end-before: [end: curve data]

Again one can go step by step,
creating a Blender curve, adding it to a Blender object and linking this object to a collection of the scene.
The noticeable difference here is that the periodicity of the curve is not encoded directly in the set of points, so it needs to be specified additionally when converting:

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: manual curve]
   :end-before: [end: manual curve]

..  image:: new_api/curve-before-transformation.png
    :alt: curve-before-transformation

One can also apply arbitrary transformations on the curve to satisfy the visualization purposes:

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: manual curve trafo]
   :end-before: [end: manual curve trafo]

..  image:: new_api/curve-after-transformation.png
    :alt: curve-after-transformation

The steps of the conversion can be reduced to one step by using :py:func:`~ddg.visualization.blender.curve.curve_object`

.. literalinclude:: ../../../../examples/blender/docs/new_api.py
   :start-after: [begin: new api curve]
   :end-before: [end: new api curve]