/**
 * \page BoxAlgorithm_SignalDisplay Signal display
__________________________________________________________________

Detailed description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Description|
This plugin displays incoming signals. It plots values on the vertical axis while the horizontal axis represents time. 

To display your signal correctly and as smoothly as possible, you may need to configure this box. Please see below for examples.

 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Description|
__________________________________________________________________

Inputs description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Inputs|
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Inputs|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Input1|
Data to display. Signal and Streamed Matrix types are supported.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Input1|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Input2|
Stimulations.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Input2|
 
 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Input3|
Measurement units of the data.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Input3|
__________________________________________________________________

Settings description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Settings|
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Settings|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting1|
Type of display, can be either Scan mode or Scroll mode. In Scan mode, the new data arrives
from left to right and the displayed data does not move. In Scroll mode, the new data always
arrives on the right and all displayed data moves right to left.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting1|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting2|
Automatic vertical (y) scaling mode: Per channel, Global, or None.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting2|
 
 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting3|
How often the vertical scale is refreshed. Only used when automatic vertical scaling mode is not None.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting3|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting4|
Vertical (y) scale for each channel when automatic vertical scaling mode is None.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting4|
 
 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting5|
Vertical (y) offset for each channel when automatic vertical scaling mode is None.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting5|
 
 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting6|
Size of time window to display, in seconds.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting6|
 
 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting7|
Enable bottom (x) ruler?
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting7|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting8|
Enable left (y, vertical) ruler?
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting8|

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Setting9|
Enable multiview? This mode displays several signals on top of each other. It is sometimes called a 'butterfly plot'.
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Setting9|

__________________________________________________________________

Online visualization settings
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_OnlineVisualizationSettings|
By clicking the bar at the top of the window during runtime, the user gets access to the online 
toolbar of the display. This allows settings of the box to be modified during playback.

Online settings :

  The toolbar allows access to the following settings,

  - Scan/scroll mode : this button switches the type of display (scan or scroll)
  - Left/Bottom Ruler : these buttons toggle channel y and x legend (coordinate axes).
  - Channel units : Show channel units. Requires meaningful data from the measurement units stream.
  - Auto vertical scale : Change the vertical (y) scaling mode
  - Vertical scale : Value when automatic scaling is not used
  - Vertical offset : Value when automatic scaling is not used
  - Time Scale : this setting adjusts the time span displayed, in seconds.
  - Select Channels : Allows to show/hide some of the channels by checking/unchecking each channel.
  - Multi-View : Allows to configure what channels should be plotted in an extra graph at the bottom of the Signal Display window. When no channels are selected (default) this extra graph is not displayed. To disable multiview, select 'None' in the channel list.
  - Stimulation colors : Display stimulation name or identifier corresponding to the plotted colors.
  - Information : This button displays information about the data (min/max values and so on).

 \image html signaldisplay_toolbar.png "Signal Display toolbar"
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_OnlineVisualizationSettings|
__________________________________________________________________

Examples description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Examples|

To get some signals displayed right, changing the automatic y scaling may be useful. The provided scaling settings are 

	- Per channel (default) : Every channel will get centered and scaled separately. This should allow viewing arbitrary signals. This is suitable for unfiltered data which may have huge differences in scale and DC between channels.
	- Global : All channels are put to the same scale which is the maximum of all the channels. This mode is suitable for filtered EEG and data which may have long-term trends but where all channels generally stay in the same range. 
	- None: User must specify global center and scale. Display is never automatically rescaled. This is suitable for filtered EEG data where the meaningful range is within known parameters and DC doesn't vary. 

Note that the automatic scalers may include discontinuities in the plot when the scale changes (see below for 'Best practices').

Practical example :

 OpenViBE has a tutorial scenario bundled : box-tutorials/signal-display.xml

 An easy way to test this box consists of generating signals with the Sinus Oscillator plugin (found under 'Data generation' in Designer), and then connecting its signal output to the signal input of the Signal Display plugin.

 \image html signaldisplay_online.png "Visualizing 2 channels using the Signal Display plugin."
 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Examples|

__________________________________________________________________

Miscellaneous description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_SignalDisplay_Miscellaneous|

Best practices

All vertical scaling modes except 'None' will change the scaling dynamically
when the scale of the data appears to have changed. To avoid slow redraws,
the box simply changes the scale and leaves the old part of the signal
as it was, meaning that you may see a discontinuity in the signal, as
for the moment there are two or more different scales visible. The scale
change is marked by small red ticks at the top and bottom of the display. 

For most situations, and to avoid the discontinuities of the automatic
scaling, the following is recommended:

	- First filter the signals meaningfully to remove DC and slow trends by using the Temporal Filter box. For EEG, you can use a bandpass configuration with a range a such as [1,40] hz.
	- Next, set the vertical scaling to 'None' and provide the display box a meaningful fixed scale corresponding to your signal. You can find out a suitable scale by activating 'Left Ruler' when the auto scale is active. Note that when the scale is given in the box parameters, the scale can be saved with the scenario.

Known issues and workarounds

The box supports only two data stream types: Matrix and Signal. Many OpenViBE 
stream types derive from the Streamed Matrix type. In this case, you can 
configure the box to have a Streamed Matrix input socket, and then connect the 
derived stream type to that. Note that the data of the stream not contained in the 
matrix will be ignored. In any case, you may be able to visualize something 
meaningful. In the case of Feature Vector stream, you can try to use the 
Matrix Transpose box on the feature stream first to turn the features into 
channels.

Multiview: Multiview presents all the signals in the same space. 
The different channels are not centered, so if they have large DC differences, 
the view may not show anything meaningful. In this case, filter the signal first.

Scroll mode is known to be slow, notably on Windows. For faster scrolling display, use Linux.

 * |OVP_DocEnd_BoxAlgorithm_SignalDisplay_Miscellaneous|
 */
