.. _user_guide_plotting:

====
Plot
====
DPF-Core has a variety of plotting methods for generating 3D plots of
Ansys models directly from Python. These methods use VTK and leverage
the `PyVista <https://github.com/pyvista/pyvista>`_ library to
simplify plotting. For more information, see the `PyVista Documentation
<https://docs.pyvista.org>`_.


Plot the mesh from the ``Model`` object
---------------------------------------
The :meth:`Model.plot() <ansys.dpf.core.model.Model.plot>` method
plots the mesh of the model immediately after loading it.

This example downloads a simple pontoon mesh from the internet and uses the
:class:`ansys.dpf.core.model` class to load it:

.. code:: python

    >>> import ansys.dpf.core as dpf
    >>> from ansys.dpf.core import examples
    >>> filename = examples.download_pontoon()
    >>> model = dpf.Model(filename)
    >>> model.plot()

.. image:: ../images/plotting/pontoon.png

The default plotter settings display the mesh with edges shown and
lighting enabled. For a list of all keyword arguments, see 
`plot <https://docs.pyvista.org/plotting/plotting.html?highlight=plot#pyvista.plot>`_.


Plot the meshed region
-----------------------
The :meth:`MeshedRegion.plot() <ansys.dpf.core.meshed_region.MeshedRegion.plot>` 
method plots the meshed region. If the meshed region is generated from the model's 
metadata, the plot generated is identical to the plot generated by the
:meth:`Model.plot() <ansys.dpf.core.model.Model.plot>` method.

Plot the meshed region:

.. code:: python

    >>> mesh = model.metadata.meshed_region
    >>> mesh.plot()

.. image:: ../images/plotting/pontoon.png

When a field is provided as the first argument, the mesh is plotted 
using these values.

This example extracts the nodal strain in the X direction:

.. code:: python

    First, extract the X component strain

    >>> strain = model.results.elastic_strain()
    >>> fields = strain.outputs.fields_container()
    >>> field = fields.select_component(0)[0]
    >>> print(field)
    DPF elastic_strain_1.s0 Field
      Location: ElementalNodal
      Unit:
      8640 entities
      Data:1 components and 69120 elementary data

    This ElementalNodal strain must be converted to nodal strain for
    it to be plotted.

    >>> nodal_field = field.to_nodal()
    >>> mesh.plot(nodal_field)

.. image:: ../images/plotting/pontoon_strain.png

.. note::

   Only fields with  ``Nodal`` and ``Elemental`` locations are
   supported. Use the :meth:`to_nodal <ansys.dpf.core.field.Field.to_nodal>`
   operator to convert to the ``Nodal`` location or the
   :class:`ansys.dpf.core.operators.averaging.nodal_to_elemental` 
   class to convert to the ``Elemental`` location.