.. _visualizing_spheres:

Visualizing Spheres
===================

..  seealso::

    :ref:`Visualizing ddg objects in Blender <to_blender_object_and_helper>` for a
    general guide on visualization of ddg objects in Blender and
    usage of :py:func:`~ddg.conversion.blender.core.to_blender_object`
    and :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`.

Circles and 2D spheres in Euclidean 3D space can be visualized in Blender.
For this, a :py:class:`~ddg.geometry.spheres.SphereLike` needs to be
converted to a
:py:class:`~ddg.datastructures.nets.net.SmoothNet`
(:py:class:`~ddg.datastructures.nets.net.SmoothCurve`).
This has to be converted to a :py:class:`~ddg.datastructures.nets.net.DiscreteNet` (or a
:py:class:`~ddg.datastructures.nets.net.DiscreteCurve`), which is achieved by sampling.
This conversion and sampling can be done
manually and the :py:class:`~ddg.datastructures.nets.net.DiscreteNet`
can be handed to :py:func:`~ddg.conversion.blender.core.to_blender_object`. Alternatively,
:py:class:`~ddg.geometry.spheres.SphereLike` can be handed to
:py:func:`~ddg.conversion.blender.core.to_blender_object_helper` which combines the
conversion, the sampling and the call of :py:func:`~ddg.conversion.blender.core.to_blender_object`.

.. note::

    Another possible way to visualize a 2d sphere is to convert it to an
    icosphere, which is a halfedge surface.
    This can be done using the function
    :py:func:`~ddg.conversion.halfedge.geometry.core.to_halfedge`.
    The icosphere can then be visualized in Blender using
    :py:func:`~ddg.conversion.blender.core.to_blender_object`, see
    also :ref:`Visualizing halfedge objects in Blender <visualizing_halfedge>`.
    This conversion is not (yet) part of this guide,
    the internal conversion in
    :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`
    is via SmoothNet and DiscreteNet.

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


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

A :py:class:`~ddg.geometry.spheres.Sphere` can be converted to a
:py:class:`~ddg.datastructures.nets.net.SmoothNet` that can be sampled to a
:py:class:`~ddg.datastructures.nets.net.DiscreteNet`. The function
:py:class:`~ddg.datastructures.nets.conversion.sample_smooth_net`
requires a sampling.

.. doctest::

    >>> import ddg
    >>> import numpy as np

    >>> euc3d = ddg.geometry.euclidean(3)
    >>> sphere = euc3d.sphere(np.array([3.0, 0.0, 1.0, 1.0]), 1.0)
    >>> snet = ddg.to_smooth_net(sphere)
    >>> dnet = ddg.sample_smooth_net(snet, sampling=[0.5, 10, "c"])

.. seealso::

    :ref:`Guide on sampling a SmoothNet <sampling_a_smooth_net>`.


The :py:class:`~ddg.datastructures.nets.net.DiscreteNet` can be visualized:

.. doctest::

    >>> blender_object = ddg.to_blender_object(dnet)


General arguments of the function :py:func:`~ddg.conversion.blender.core.to_blender_object` can
be found in its api documentation: :py:func:`~ddg.conversion.blender.core.to_blender_object`.


There are additional arguments for the DiscreteNets
depending on the dimension of the Sphere:

.. include:: _to_blender_object/docstring.txt
    :start-line: 57
    :end-line: 84

.. seealso::

    :ref:`Usage of to_blender_object <to_blender_object>`.




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`.

A :py:class:`~ddg.geometry.spheres.Sphere` can be handed directly to
:py:func:`~ddg.conversion.blender.core.to_blender_object_helper` together with a
sampling.

.. doctest::

    >>> subspace = ddg.geometry.subspaces.subspace_from_affine_points(
    ...     (0, 0, 0), (1, 0, 0), (0, 1, 0)
    ... )
    >>> blender_object = ddg.to_blender_object_helper(subspace, sampling=[0.5, 10, "c"])


General arguments of the function :py:func:`~ddg.conversion.blender.core.to_blender_object_helper` can
be found in its api documentation: :py:func:`~ddg.conversion.blender.core.to_blender_object_helper`.


There are additional arguments for the (converted) Nets
depending on the dimension of the Sphere:

.. include:: _to_blender_object/docstring.txt
    :start-line: 188
    :end-line: 221

.. seealso::

    :ref:`Usage of to_blender_object_helper <to_blender_object_helper>`.



Examples
--------

An example script of creating a circle and visualizing it in Blender:

.. doctest::

    >>> P1 = np.array([12.0, 0.0, 1.0, 1.0])
    >>> P2 = np.array([0.0, 9.0, 1.0, 1.0])
    >>> P3 = np.array([1.0, 5.0, 4.0, 7.0])
    >>> center = P1 - P3
    >>> euc3d = ddg.geometry.euclidean(3)
    >>> circle = euc3d.sphere(center, 1.0, subspace=[P1, P2, P3])
    >>> snet = ddg.to_smooth_net(circle)
    >>> dnet = ddg.sample_smooth_net(snet, sampling=[0.5, 10, "c"])
    >>> ddg.to_blender_object_helper(dnet)
    bpy.data.objects['SmoothCurve']

Two example renderings:

.. figure:: fordcircles_render.png
      :alt: render of ford circles
      :align: center

      A render of `Ford circles <https://en.wikipedia.org/wiki/Ford_circle>`_ using smooth nets.


.. figure:: icosphere_render.png
  :alt: render of icosphere
  :align: center

  A wireframe render of an icosphere (a Sphere converted to a halfedge object).