.. _visualizing_quadrics:

Visualizing Quadrics
====================

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

    >>> sphere = ddg.geometry.quadrics.Quadric(np.diag([1, 1, 1, -1]))
    >>> snet = ddg.to_smooth_net(sphere, affine=True)
    >>> dnet = ddg.sample_smooth_net(snet, sampling=[0.5, 10, "c"])

.. seealso::

    :ref:`Converting a Quadric to a SmoothNet <converting_a_quadric_to_a_net>`.

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

.. note::
    When using ``to_smooth_net`` for visualization we need the argument
    ``affine=True`` for visualization in affine coordinates.

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

Depending on the type of the resulting DiscreteNet, i.e. the dimension of the Quadric,
additional arguments can be given to
:py:func:`~ddg.conversion.blender.core.to_blender_object`:

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

.. doctest::

    >>> quadric = ddg.geometry.quadrics.Quadric(np.diag([1, 1, -1, -1]))
    >>> blender_object = ddg.to_blender_object_helper(quadric, sampling=[0.1, 50, "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 Quadrics and further for the (converted) Nets,
depending on the dimension of the Quadric:

.. include:: _to_blender_object/docstring.txt
    :start-line: 171
    :end-line: 181


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

.. doctest::

        >>> sphere = ddg.geometry.quadrics.Quadric(np.diag([1, 1, 1, -1]))
        >>> sphere = ddg.to_blender_object_helper(
        ...     sphere, sampling=[0.1, 20, "c"], name="sphere"
        ... )

        >>> two_sheeted_hyperboloid = ddg.geometry.quadrics.Quadric(
        ...     np.diag([1, 1, -1, 1])
        ... )
        >>> two_sheeted_hyperboloid = ddg.to_blender_object_helper(
        ...     two_sheeted_hyperboloid,
        ...     sampling=[0.1, 20, "c"],
        ...     name="two_sheeted_hyperboloid",
        ...     location=[6, 0, 0],
        ...     bounding_box=[5, 5, 4],
        ... )

        >>> one_sheeted_hyperboloid = ddg.geometry.quadrics.Quadric(
        ...     np.diag([1, 1, -1, -1])
        ... )
        >>> one_sheeted_hyperboloid = ddg.to_blender_object_helper(
        ...     one_sheeted_hyperboloid,
        ...     sampling=[0.1, 20, "c"],
        ...     name="one_sheeted_hyperboloid",
        ...     location=[16, 0, 0],
        ...     bounding_box=[5, 5, 4],
        ... )

.. image:: quadrics.png
    :scale: 40 %
    :align: center