.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/chaos/advanced/plot_pyvista_3d.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_api_gallery_chaos_advanced_plot_pyvista_3d.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_api_gallery_chaos_advanced_plot_pyvista_3d.py:


Interactive 3D Viewing with PyVista
=========================================

Matplotlib's ``mplot3d`` axes project a 3D scene onto a 2D canvas with only
an approximation of real depth (and no interactive rotation once a figure is
saved as a static image). :func:`physicskit.chaos.visualizers.viewer3d.pyvista_trajectory`
renders the same kind of trajectory -- here, the Rossler attractor,

.. math::

    \dot{x} = -y - z, \qquad \dot{y} = x + a y, \qquad
    \dot{z} = b + z (x - c),

with the classic chaotic parameters :math:`a=0.2`, :math:`b=0.2`,
:math:`c=5.7` -- in a real, camera-navigable 3D scene via
`PyVista <https://pyvista.org>`_ (the optional ``physicskit.chaos[viz3d]``
extra). Call ``.show()`` on the returned plotter for an interactive window;
this example instead renders off-screen and displays the result as a static
image, purely so it can be captured for this gallery. To make the
"only an approximation of real depth" claim concrete rather than asserted,
the same trajectory is also drawn with a plain Matplotlib ``mplot3d`` axes
side by side with the PyVista render, so the two can be compared directly on
the same attractor.

.. GENERATED FROM PYTHON SOURCE LINES 26-40

.. code-block:: Python


    from __future__ import annotations

    import matplotlib.pyplot as plt

    from physicskit.chaos.systems.continuous import Rossler

    try:
        from physicskit.chaos.visualizers.viewer3d import pyvista_trajectory

        _HAS_PYVISTA = True
    except ImportError:
        _HAS_PYVISTA = False








.. GENERATED FROM PYTHON SOURCE LINES 41-45

Render the Rossler attractor
---------------------------------
Colored by sample index (time), so the direction of travel around the
attractor's two lobes is visible at a glance.

.. GENERATED FROM PYTHON SOURCE LINES 45-48

.. code-block:: Python

    system = Rossler()
    _, states = system.trajectory(n_steps=20000, dt=0.02)








.. GENERATED FROM PYTHON SOURCE LINES 49-58

Side by side: projected depth vs. a real 3D scene
-------------------------------------------------------
Left: the same attractor drawn with a plain ``mplot3d`` axes -- a single
fixed camera angle baked in at draw time, with depth conveyed only by
perspective and occlusion. Right: the PyVista render, which (interactively)
can be freely rotated to disentangle the two lobes from any angle; here it
is only a static screenshot, but even that single frame already shows a
cleaner separation of near/far strands than the ``mplot3d`` panel, thanks
to PyVista's real depth-buffered rendering.

.. GENERATED FROM PYTHON SOURCE LINES 58-93

.. code-block:: Python

    fig = plt.figure(figsize=(13, 6))
    ax_mpl = fig.add_subplot(1, 2, 1, projection="3d")
    ax_pv = fig.add_subplot(1, 2, 2)

    ax_mpl.plot(states[:, 0], states[:, 1], states[:, 2], lw=0.3, color="teal")
    ax_mpl.set_xlabel("x")
    ax_mpl.set_ylabel("y")
    ax_mpl.set_zlabel("z")
    ax_mpl.set_title("Matplotlib mplot3d\n(projected depth, fixed camera)")

    if _HAS_PYVISTA:
        plotter = pyvista_trajectory(states, color_by="index", off_screen=True)
        plotter.camera.zoom(1.3)
        screenshot = plotter.screenshot()
        plotter.close()

        ax_pv.imshow(screenshot)
        ax_pv.axis("off")
        ax_pv.set_title("PyVista\n(real 3D scene, off-screen render for this gallery)")
    else:
        ax_pv.text(
            0.5,
            0.5,
            "PyVista is not installed\n(pip install physicskit.chaos[viz3d])\n-- skipping the 3D render for this gallery build.",
            ha="center",
            va="center",
            transform=ax_pv.transAxes,
        )
        ax_pv.axis("off")
        print("PyVista is not installed (pip install physicskit.chaos[viz3d]) -- skipping the 3D render for this gallery build.")

    fig.suptitle("Rossler attractor: projected (mplot3d) vs. real (PyVista) 3D depth")
    fig.tight_layout()

    plt.show()



.. image-sg:: /api/gallery/chaos/advanced/images/sphx_glr_plot_pyvista_3d_001.png
   :alt: Rossler attractor: projected (mplot3d) vs. real (PyVista) 3D depth, Matplotlib mplot3d (projected depth, fixed camera)
   :srcset: /api/gallery/chaos/advanced/images/sphx_glr_plot_pyvista_3d_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    PyVista is not installed (pip install physicskit.chaos[viz3d]) -- skipping the 3D render for this gallery build.





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.261 seconds)


.. _sphx_glr_download_api_gallery_chaos_advanced_plot_pyvista_3d.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_pyvista_3d.ipynb <plot_pyvista_3d.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_pyvista_3d.py <plot_pyvista_3d.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_pyvista_3d.zip <plot_pyvista_3d.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_