- NB: last update for OpenViBE 1.1.0 (pictures may not fully correspond).
OpenViBE Designer is an authoring tool dedicated to creating and executing OpenViBE scenarios. It is targeted at a broad range of users, including
- students and researchers of the BCI community
- neurophysiology experts who need a tool for signal processing and visualisation in the context of brain activity
- clinicians looking for a tool to conduct neurofeedback experiments
It relies on a graphical user interface to provide signal processing tools in an intuitive way, and doesn’t require any programming skills.
Each of these tools comes as a plugin, which communicates with the application via a generic interface hiding implementation details. As a result, it is easy for a programmer to extend the range of tools provided with the platform.
Thanks to an active open-source community, an ever growing number of these signal processing boxes, or ‘box algorithms’ in OpenViBE terminology, are available in the Designer. Users may arrange any number of these boxes in a very flexible fashion, considering there is virtually no limit as to the number of boxes that may be included in a given BCI scenario.
Once a scenario is created, it may be run from the Designer, which provides a toolbar for playing, pausing and stepping through a scenario. A number of box algorithms are available for direct visualisation of results, from simple 2D displays such as power spectrum and signal display to 3D paradigms such as 3D topographical mapping. The layout of these displays may be customised as desired at scenario editing time using the window manager module of the Designer.
The following sections are an overview of the main features of the Designer tool, and make for a quick and easy introduction to its usage. Here are the topics covered in this overview :
- the top level menu bar
- the toolbar, which provides immediate access to the most common actions
- the ‘boxes‘ tree view
- the status bar, which provides performance information when a scenario is being run
- the console which prints Info, Warning or Error messages
- a scenario editor window, where boxes may be arranged together in order to fulfill the task at hand.
Options available from the menu bar are presently restricted to actions involving handling and exiting the application. Scenarios may be saved to XML files. Several scenarios may be edited simultaneously, and the active scenario may be changed by clicking onto the corresponding tab at the top of the scenario editor window. Here is a list of options from the menu bar and their shortcuts if available:
- New – Ctrl+n
- Open – Ctrl+o
- Save – Ctrl+s
- Save As
- Close - Ctrl+w
- Quit – Alt+F4
- Undo – Ctrl+z
- Redo – Ctrl+y
- Cut – Ctrl+x
- Copy – Ctrl+c
- Paste – Ctrl+v
- Delete – Del
The File menu handles standard scenario operations such as creation, saving and closing. Note that the application won’t quit as long as at least one scenario is running.
The Edit menu allows the user to cut/copy/paste selections (in a scenario or across scenarios). These options can also be accessed when right-clicking on a box. User actions are saved during scenario editing and can be retrieved through undo-redo.
The last item, called ‘Preferences’, displays the Configuration Manager dialog. It contains a list of all configuration tokens and their values. This list is read only. To know more about the Configuration Manager, refer to The Configuration Manager.
The first section of the toolbar offers direct access to the scenario handling options (see Fig. 1) that you can find in the menu ‘File’.
A second section comprises two toolbuttons:
The first is a toggle button, allowing for displaying and hiding the window manager. This tool is displayed in a popup window when the button is pressed. It takes care of arranging visualisation boxes in a layout. Such boxes (if any in the current scenario) initially appear under the ‘Unaffected display plugins’ node of the tree view in the upper left corner. A window containing one tab is also created by default and displayed on the right.
The next toolbar button displays the log levels dialog. It may be used to configure which log messages should be displayed in the console. It contains 8 levels as shown in the following figure :
Two buttons allow the user to customize the scenario with useful comments. One button adds a dedicated comment box to the scenario. These boxes have of course no input and outputs. Double click on them to edit the comment they display. The syntax of the comments uses pango font style.
The other button allows to edit some information that will be saved with the scenario (authors, date, description, etc.).
The following section contains two buttons and a numerical field which allow the user to modify the scenario scale and allow him to zoom in or out. Value of zoom are bounded between 10% and 300%.
The following section is dedicated to scenario playing. It comprises the following buttons :
- Stop – F5
go back to scenario edition mode
- Step – F6
play scenario one step of simulation at a time
- Play/Pause – F7
- Fast Forward – F8
play scenario as fast as possible
if the replay button is pressed, the scenario restarts automatically each time it ends
Once a scenario is being played, it is not possible to modify it. Press ‘Stop’ to go back in edition mode. Shortcuts from F5 to F8 can be used only if the focus is on the Designer main window (not on visualisation windows for example).
Finally, the toolbar contains a time counter which displays the simulation time as a scenario is being run. It is reset to 0 as a scenario is stopped.
Box algorithms tree view
The right-hand part of the Designer window displays a list of existing box algorithms, which are the building blocks of OpenViBE scenarios.
Under the ‘Box algorithms’ tab lies a tree view listing available box algorithms, along with a short description of their respective roles. Box algorithms are the smallest granular elements that may be manipulated by a Designer user. They act as black boxes which can be connected together by their inputs and outputs. In order to facilitate their selection, they are grouped into categories, which make up the top level nodes of the tree view. Some categories are related to signal processing, others to scenario serialization or visualisation purposes.
The default treeview shows only stable and fully supported boxes. If you want to use old ‘deprecated‘ boxes please set the configuration token
TRUE. To use ‘unstable‘ boxes set
TRUE. As stated in their documentation pages, you are using these boxes at your own risk.
The status of a box varies with the context, and is reflected by the color of the font used in the tree view. The box name and description will use a green font if the box is deprecated, and a light grey font if it is unstable. To know more about box status, go to Edition Area.
Optional : Algorithms treeview
While box algorithms can be arranged together by the user to make up a scenario, algorithms lie at a lower level in the OpenViBE object diagram and aren’t meant to be directly manipulated by the user. Instead, they can be seen as reusable components which box algorithms relie on. A tree of existing algorithms can be found next to the box algorithms tree if the configuration token
Designer_ShowAlgorithms is set to
TRUE. It is similarly sorted by category, only this time, it is merely a reminder of what algorithms are available in the current state of the platform. They can’t be added to a scenario.
The status bar that lies at the bottom of the Designer window provides performance information. When a scenario is being run, OpenViBE keeps track of the time used by each box and of the overall execution time.
Overall performance is displayed in a green gauge overlaid with the same information in percent. A system load 100 percent means the system is barely able to handle the computation load induced by the scenario to run in real-time.
To identify the bottlenecks in a scenario, one can press the button to the right of the gauge as a scenario is being run. This will highlight boxes from green to red, depending on how much time is spent in each box relative to the others.
The Designer console can be expanded/hidden by a simple click. You can choose the log levels you want to see in this particular window (does not modify the active application log levels).
The Designer console has been developed in order to be sure to see any warning or error messages, that otherwise appear in the background console discretely.
The Designer console also allows the user to search a string in the logs generated since the last clear.
The last section of this overview covers the working area of the Designer, which is where OpenViBE scenarios are assembled by connecting box algorithms together.
Box algorithms are added to the active scenario by drag and dropping them from the tree view to the scenario edition window. They appear as rounded rectangles with their name inside the box, inputs (if any) on top and outputs (if any) at the bottom. These connectors are displayed as color-coded triangles. Colors vary with the connector type, and help users to make sure they connect boxes properly. See Connector Types for an overview of the different connector types and hierarchy.
By default, the status of a box is ‘normal’, and the box is drawn with a white background. However, some boxes may have a different status depending on the situation. Here are the other possible status of a box :
- Unstable: a box which is under development should be flagged as ‘unstable’, meaning it has probably not been tested enough to guarantee correct behaviour. Such a box is drawn with a dark grey background in the Designer, and the ‘unstable’ label appears below the box name.
- Update : when a box is not up to date with the latest version used in a given distribution of OpenViBE, it is drawn with a light grey background and the mention ‘update’ appears below the box name. This situation arises when the prototype of a box has changed between the time the scenario it is stored in is saved and the time it is loaded again. Since scenario files contain information about box prototypes, such as the number of connectors, they may need to be updated when the OpenViBE distribution used to manipulate scenarios changes. To update such a box, simply delete the box from the scenario then add it again. The new box will use the latest version. Tip : after such an update, one should make sure to reconfigure the box settings if needed!
- Deprecated : as OpenViBE evolves with time, some boxes are added to the platform and others are deleted. It can also happen that a box is replaced with another one (maybe for performance reasons). However, the ‘old’ box is not necessarily deleted from the platform, but may be kept for backward compatibility with older versions (ensuring older scenarios may still be run, for example). In that case, the documentation should mention that from that time on, the new box should be preferred over the deprecated one (which may be removed from the platform at any time, and in any case which probably won’t be maintained anymore). Such boxes are displayed with a dark green background and the ‘deprecated’ label below the box name.
- Muted : if a box is muted, its color is pink and will not process its input or generate output. Message inputs will be processed if messages are supported by the box. Additionally, muted visualization boxes will not display anything unless their widget were assigned to a window in the visualization manager. In this case, the widget will stay empty and mention ‘muted’ next to the name of the box. Be aware that the initialize function of the box is called, even if the box is muted.
Note : when a box is deprecated and also needs to be updated to the newest version, both ‘deprecated’ and ‘update’ labels will appear below its name in the Designer. As to its color, it will appear as dark green, reflecting its deprecated state.
Box editing functionalities
All box algorithms may be configured in the Designer. However, not all boxes offer the same configuration options. In this overview, we’ll focus on functionalities that are common to all boxes. More advanced possibilities are detailed in another tutorial (Designer Tutorial 4: Advanced box configuration).
To illustrate box editing functionalities, let’s start by creating a new scenario, and drop a couple of boxes from the box algorithms tab. Simple boxes such as ‘Clock’ and ‘Nothing’ (found under the ‘Samples’ category) will do for this tutorial. Drag and drop these boxes in the scenario working area, then right-click on the ‘Nothing’ box. A context menu should appear, listing different editing functionalities.
Box editing functionalities appear in the lower part of the menu :
- ‘Rename box (F2)’ allows to rename the box. Click this option and enter a new name such as ‘Dummy Box’ to test this functionality.
- ‘Delete box (Del)’ removes this box from the scenario. Note that a box may also be deleted by selecting it, then pressing the ‘Delete’ key.
- ‘About box’ displays a dialog containing a summary of the box details, such as its author, version, class name, as well as a short and long description of its purpose. Note that the ‘short description’ field also appears in the second column of the box algorithms tab.
- ‘Mute toggle’ A muted box will do no process at all except from handling received messages if the box is equipped to do so. This can be used if you need certain boxes in a scenario for debugging purposes but not in its normal use. You may deactivate these boxes and reactivate them only when needed instead of having to add and remove them or having two almost identical scenarios.
Another option only gets listed for those boxes that offer configurable settings, such as the Clock box (this may be guessed from its name displayed in bold case). Right click on this box and select :
- ‘Configure box’, which displays the Box Settings dialog. Note that this dialog may also be displayed by double clicking on the box itself.
Scenario editing functionalities
Standard cut/copy/paste functionalities are supported in Designer. Select a box and right click on it to display a menu from which to select these options.
Groups of boxes may be edited in the same way. Select several boxes at once by maintaining the Ctrl key pressed then clicking on the boxes you want to cut or copy. You may also draw a selection area by left clicking in the scenario editing area then drawing a selection rectangle while keeping the button pressed. Ctrl+a selects everything in the scenario.
Paste your selection by right clicking anywhere in the edition area, or pressing Ctrl+V. Note that you may also paste selections from one scenario to another.
Delete your selection by selecting ‘Delete boxes’ in the contextual menu, or pressing the ‘Delete‘ key.
Finally, the origin of the scenario editing area may be changed by pressing and holding the Shift key and left click then moving the mouse as desired. This allows you to explore your scenario window without using the scrolling bars.