.. include:: ../vars.rst
.. _section-data-visualization-getting-started:


Getting Started with Data Visualization
=======================================

===========
Preparation
===========
        
Launch *RTI Shapes Demo* and publish a few squares with different colors.
    
====================================================    
Step 1: Switch to the Data Visualization Perspective
====================================================

.. |ICON_VISUALIZE_16| image:: ../_static/datavisualization/icons/visualize_16.png
.. |ICON_SWITCH_PERSPECTIVE| image:: ../_static/datavisualization/switch_perspective.png

Click on the **Switch to Data Visualization Perspective** button
|ICON_VISUALIZE_16| on the toolbar or select the **Data Visualization
Perspective** entry under the **Visualization** menu.

In the Data Visualization Perspective, some Administration related
views are hidden; to see them, click on the corresponding view icon in
the toolbar or the **View** menu. To switch back to the **Administration**
perspective, click on the **Administration** perspective button on
the top-right corner:

.. figure:: ../_static/datavisualization/switch_perspective.png
    :alt: Switch perspective
    :name: Switch perspective
    :align: center
    :figWidth: 100%
    
===============================
Step 2: Open the Topic Data Tab
===============================
    
From the **DDS Logical View**, click on the **Square** Topic to
open the Topic View. In the **Data Visualization** perspective,
it will automatically switch to the **Topic Data** tab, as seen below:

.. figure:: ../_static/datavisualization/empty_topic_data_tab.png
    :alt: Empty topic data tab
    :name: Empty topic data tab
    :align: center
    :figWidth: 100%

============================
Step 3: Subscribe to a Topic
============================

.. |ICON_SUBSCRIBE| image:: ../_static/datavisualization/subscribe_button.png

Click on the **Subscribe...** button |ICON_SUBSCRIBE| or right-click
on the Topic in the DDS Logical View and select **Subscribe**. This
will open the :ref:`section-data-visualization-create-subscription-dialog`
seen below. You may expand the  **Advanced Settings** to set the QoS,
Content Filter, or DataWriter Filter for the subscription. Click **OK**
to subscribe to the Topic.

.. figure:: ../_static/datavisualization/create_subscription_dialog.png
    :alt: Subscription dialog creation
    :name: Subscription dialog creation
    :align: center
    :figWidth: 100%

===================================================
Step 4: Use the Topic Data Tab and Sample Inspector
===================================================

.. |ICON_SELECT_FIELDS| image:: ../_static/datavisualization/select_fields_button.png

After the Topic has been subscribed to, the Instances Table will show the
latest data of all the instances that have been discovered so far. Select
a row in the table to see the full data structure of the instance's live
data in the Sample Inspector view.

.. figure:: ../_static/datavisualization/topic_data_sample_inspector.png
    :alt: Topic data sample inspector
    :name: Topic data sample inspector
    :align: center
    :figWidth: 100%

You can add and remove columns to the Instances Table by clicking on
the **Select Fields...** button |ICON_SELECT_FIELDS|.


==========================
Step 5: Use the Sample Log
==========================

The :ref:`section-data-visualization-sample-log` view logs every sample
that has been received from selected Topics.

.. figure:: ../_static/datavisualization/samplelog_shot.png
    :alt: Sample log image
    :name: Sample log image
    :align: center
    :figWidth: 100%


************************
Configure the Sample Log
************************

.. |ICON_SAMPLE_LOG| image:: ../_static/datavisualization/samplelog.png
.. |ICON_CONFIGURE| image:: ../_static/datavisualization/icons/configure.png

Click on the **Sample Log** button |ICON_SAMPLE_LOG| on the toolbar or the
**Sample Log** entry in the **Visualization** menu. This will open a new Sample
Log view and its configuration dialog. In the configuration dialog, from the
**Topics** tab, you may select one or more Topics to log. In the **Visible
Columns** tab, you can select the columns that are visible in the table. You
can open the configuration dialog at any time by clicking on the **Configure...**
button |ICON_CONFIGURE|.

.. figure:: ../_static/datavisualization/samplelog_configure_dialog.png
    :alt: Sample configure dialog
    :name: Sample configure dialog
    :align: center
    :figWidth: 100%

**************************
Add Topics to a Sample Log
**************************
    
To directly visualize a Topic in a new Sample Log, right-click on a Topic or
instance and select **Visualize > Sample Log**. If there are existing Sample
Logs that are not logging this Topic, you can also use "Drag and Drop" or the
**Add to Existing View** context menu to add the Topic to one of the existing
Sample Logs. You may also add a DataWriter, DataReader, instance or field to
a Sample Log, which will add the related Topic to the Sample Log.

.. figure:: ../_static/datavisualization/visualize_context_menu.png
    :alt: Visualiaze context menu
    :name: Visualiaze context menu
    :align: center
    :figWidth: 100%

****************
Inspect a Sample
****************

.. |ICON_PAUSE| image:: ../_static/datavisualization/icons/pause.png

Select a row in the Sample Log to see its full data structure and values in the
:ref:`section-data-visualization-sample-inspector`. When the Sample Log becomes
full, the oldest samples will be deleted when new samples arrive. Toggle the
pause button |ICON_PAUSE| to pause table updates. While paused, newly arriving
samples are still logged in the background. Toggle the pause button again to
resume updates.


==========================
Step 6: Use the Time Chart
==========================

A :ref:`section-data-visualization-time-chart` is a type of view that plots
numeric fields in chart. It also supports saving and loading historical data.

 .. figure:: ../_static/datavisualization/timechart_shot.png
    :alt: Time chart image
    :name: Time chart image
    :align: center
    :figWidth: 100%

************************
Configure the Time Chart
************************

.. |ICON_TIMECHART| image:: ../_static/datavisualization/timechart.png
    
Click on the **Time Chart** button |ICON_TIMECHART| on the toolbar or the
**Time Chart** entry in the **Visualization** menu. This will open a new Time
Chart view and its configuration dialog. The **Select Signals** dialog allows
you to select the signals to be plotted. First, you need to select the Topic.
Then the instances table will show all the instances that have been discovered
so far. Then you can select the instances and fields to be plotted.
Only numeric fields can be chosen.

 .. figure:: ../_static/datavisualization/select_signals.png
    :alt: Time chart select signals
    :name: Time chart select signals
    :align: center
    :figWidth: 100%


After the signals are selected, it will automatically create corresponding
traces in the Time Chart Configuration dialog, as seen below. Each trace has
some properties, such as Trace Color, Point Style, etc. You can select the
trace from the Traces list and set its properties. You can add more Y axes
to the chart from the **Axes** tab.

For the time axis, there are two modes:

* **Auto Scale:** Automatically sets the time axis range to show all
  the samples in the plot buffer upon an update. 
* **Fixed Time Window:** Sets the time axis to a fixed time range. 

.. figure:: ../_static/datavisualization/timechart_configure.png
    :alt: Time chart configuration
    :name: Time chart configuration
    :align: center
    :figWidth: 100%
    
You can open the configuration dialog at any time by clicking on the
**Configure...** button |ICON_CONFIGURE|.

*****************************
Add Signals to the Time Chart
*****************************

To directly plot signals in a new Time Chart, right-click on one or multiple
live numeric fields in the Sample Inspector and select **Visualize > Time Chart**.
If there are existing Time Charts that are not
plotting this field, use **Drag and Drop** or the **Add to
Existing View** context menu to add the Topic to one of the existing
Time Charts. You may also add Topics or instances to a time chart; in
this case, the configuration dialogs will pop up and the Topics or
instances will be preselected.

.. figure:: ../_static/datavisualization/timechart_from_sampleinspector.png
    :alt: Time chart from sample inspector
    :name: Time chart from sample inspector
    :align: center
    :figWidth: 100%

**************************
Use the Time Chart Toolbar
**************************

.. |ICON_ZOOM_BUTTONS| image:: ../_static/datavisualization/zoom_buttons.png
.. |ICON_ARROW_BUTTONS| image:: ../_static/datavisualization/arrow_button.png

The Time Chart's toolbar allows you to manipulate the chart at
runtime. When one of the zoom buttons |ICON_ZOOM_BUTTONS| is selected, the
chart will stop auto-scaling or auto-scrolling so you can perform zoom or
panning operations by clicking on the plot or axes. Use the mouse wheel
to zoom in/out on plot area or axes. You can click on the toggled zoom
button again or the arrow button |ICON_ARROW_BUTTONS| to exit zooming and
restart auto-scaling or auto-scrolling.

********************
Plot Historical Data
********************

.. |ICON_HISTORICAL| image:: ../_static/datavisualization/historicalMode.png

Historical data can be easily loaded by moving the bottom scroll bar
or clicking on the **Switch to History Mode** button |ICON_HISTORICAL|.

=======================
Step 7: Set Preferences
=======================

.. figure:: ../_static/datavisualization/preferences_dialog.png
    :alt: Preferences dialog
    :name: Preferences dialog
    :align: center
    :figWidth: 100%


Data Visualization can be customized to suit your needs through the Preferences
dialog.