.. include:: definitions.rstinc

.. _plotting-and-data-acquisition-label:

=============================
Plotting and Data Acquisition
=============================

.. figure:: images/tutorials/plots_and_data_acquisition_tutorial_icon.jpg
  :width: 400
  :alt: Video tutorial about plots and data acquisition.
  :target: https://www.youtube.com/watch?v=CDhQFSLWN0c


To create plots in |AGXUnreal|, the ``AGX Plot Component`` can be used together with one or more ``AGX Data Series`` that hold the plot data.
The ``AGX Plot Component`` can also be used to write data to a (.csv) file on disk for later analysis.


***************
Creating a Plot
***************

1. Add an ``AGX Plot Component`` to your Blueprint.

.. figure:: images/plotting/add_plot_component.jpg
  :alt: Add a new Plot Component.
  :target: _images/add_plot_component.jpg

2. Add one or more ``AGX Plot Data Series`` as variables in your Blueprint by selecting the (+) symbol under ``Variables``. Set the type ``AGX Plot Data Series`` and set a meaningful label.

.. figure:: images/plotting/add_data_series.jpg
  :alt: Add new Data Series.
  :target: _images/add_data_series.jpg

3. In the Blueprint Graph, create a plot by calling the ``Create Plot`` function on the ``AGX Plot Component``.

.. figure:: images/plotting/create_plot.jpg
  :alt: Create Plot function.
  :target: _images/create_plot.jpg

4. Write data to your ``AGX Plot Data Series`` during Simulation by calling the ``Write`` function. Below is an example of a Hinge's angle being plotted against Simulation time.

.. figure:: images/plotting/complete_plot_logic.jpg
  :alt: Writing data to ``AGX Plot Data Series``.
  :target: _images/complete_plot_logic.jpg

Note that here we are using a custom Event bound to Simulation PreStepForward to ensure we write data from each Simulation step.
It can also be done from the regular ``Tick`` event but in that case it is not guaranteed that we get data from all Simulation steps.
This is explained further in :ref:`stepping-mode-label`.
Also, see :ref:`events-and-delegates-label` for more information about events and delegates.


By default, the plot window is automatically opened in your default browser on Play.
This behavior can be controlled through the ``Auto Open Plot Window`` property in the ``AGX Plot Component`` Details Panel.

.. figure:: images/plotting/plot_component_details_panel.jpg
  :alt: AGX Plot Component Details Planel.
  :target: _images/plot_component_details_panel.jpg

Opening the plot window during Play can also be done by clicking the ``Open Plot Window`` button from the Details Panel or by calling the function ``OpenPlotWindow`` on the ``AGX Plot Component``.


********************
Writing Data to File
********************

The ``AGX Plot Component`` can automatically write data to a (.csv) file on disk.
This is controlled through the ``Write To File`` property in the  ``AGX Plot Component`` Details Panel.
If set to true, a file with name given by the ``File Output Name`` property will be created in the project root.


***********
Limitations
***********

Currently, ``AGX Data Series`` that are part of a Blueprint of Component type is not supported.