.. _visualizing_subspaces:

Visualizing Subspaces
=====================

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

For visualization in Blender, a :py:class:`~ddg.geometry.subspaces.Subspace` 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.subspaces.Subspace` 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`.

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

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

A  :py:class:`~ddg.geometry.subspaces.Subspace` 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

    >>> points = [[1, 0, 0, 1], [0, 1, 0, 1]]
    >>> subspace = ddg.geometry.subspaces.Subspace(*points)
    >>> snet = ddg.to_smooth_net(subspace, affine=True, convex=True)
    >>> dnet = ddg.sample_smooth_net(snet, sampling=[0.5, 10, "c"])

.. seealso::

    :ref:`Converting a Subspace to a SmoothNet <converting_subspaces_to_nets>`.

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

.. note::
    When using ``to_smooth_net`` for visualization, the common defaults are
    ``affine=True`` and ``convex=True``.

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 Subspace:

.. 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.subspaces.Subspace` can be handed directly to
:py:func:`~ddg.conversion.blender.core.to_blender_object_helper` together with a
sampling.

.. doctest::

    >>> 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 Subspaces and further for the (converted) nets
depending on the dimension of the Subspace:

.. include:: _to_blender_object/docstring.txt
    :start-line: 154
    :end-line: 168

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

Here are some example code snippets and the images they produce.
The orange balls are all points in ``subspace.points`` that are not at infinity.
For more information about :py:meth:`.Subspace.orthonormalize`,
:py:meth:`.Subspace.center` and :py:meth:`.Subspace.dehomogenize`,
see the :ref:`subspaces user's guide <subspaces>`.

.. doctest::

    >>> s = ddg.geometry.subspaces.Subspace([1, 0, 0, 1], [0, 0.5, 1, 1])
    >>> bobj = ddg.to_blender_object_helper(s, sampling=[0.1, 40, "c"], domain=[[0, 1]])

.. image:: subspace_parametrization_docs_0.png

.. doctest::

    >>> s = ddg.geometry.subspaces.Subspace([1, 0, 0, 1], [0, 1, 0, 1], [0, 0.5, 1, 1])
    >>> bobj = ddg.to_blender_object_helper(
    ...     s, sampling=[0.1, 40, "c"], domain=[[0, 1], [0, 1]]
    ... )

.. image:: subspace_parametrization_docs_1.png

.. doctest::

    >>> s = ddg.geometry.subspaces.Subspace([1, 0, 0, 1], [0, 1, 0, 1], [0, 0.5, 1, 1])
    >>> s = s.orthonormalize()
    >>> bobj = ddg.to_blender_object_helper(
    ...     s, sampling=[0.1, 40, "c"], domain=[[-0.5, 0.5], [-0.5, 0.5]]
    ... )

.. image:: subspace_parametrization_docs_2.png

.. doctest::

    >>> s = ddg.geometry.subspaces.Subspace([1, 0, 0, 1], [0, 1, 0, 1], [0, 0.5, 1, 1])
    >>> s = s.orthonormalize()
    >>> s = s.center([0, 1, 0])
    >>> bobj = ddg.to_blender_object_helper(
    ...     s, sampling=[0.1, 40, "c"], domain=[[-0.5, 0.5], [-0.5, 0.5]]
    ... )

.. image:: subspace_parametrization_docs_3.png