Designer Overview

Menubar

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:

• File
  • New – Ctrl+n
  • Open – Ctrl+o
  • Recent Scenarios – > list
  • Save – Ctrl+s
  • Save As
  • Close – Ctrl+w
  • Quit – Alt+F4
• Edit
  • Undo – Ctrl+z
  • Redo – Ctrl+y
  • Cut – Ctrl+x
  • Copy – Ctrl+c
  • Paste – Ctrl+v
  • Delete – Del
  • Preferences
• Help
  • About this scenario
  • About OpenViBE
  • Browse documentation
  • Report issue
  • What’s new in x.x.x version of OpenViBE Designer

The File menu handles standard scenario operations such as opening, creating, 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 Help menu give access to scenario description information, which is essential (at least Name and Category) when you are saving your scenario as a metabox. It gives you access to the OpenViBE Designer version information (and what’s new in this version), the OpenViBE documentation and the report issue platform.

Toolbar

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.

 

Fig.2 Window manager popup dialog for a scenario with 4 visualisation boxes, before and after making changes.Users may create any number of windows containing any number of tabs, and then drag and drop visualisation boxes onto such tabs in a tree-like structure. If the user chooses to not use the window manager all visualisation boxes will be given their own window, displayed when the scenario is being played. For a more in-depth review of the window manager usage, see The Window Manager.

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 :

 

Fig.3 Log levels dialog.‘Warnings’ and ‘Errors’ should always be selected. ‘Information’ displays useful messages from signal processing boxes. ‘Trace’ can be used to check step-by-step the processing in the boxes and the kernel. ‘Benchmark’ and ‘Debug’ are very verbose and should not be used with the designer console (only in log files).

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
• Replay
  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.

Box algorithms

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 Designer_ShowDeprecated to TRUE.

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. 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.

Status bar

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.

Console

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.

Edition Area

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.

Boxes

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.

 

Fig.4 A file reading box algorithm which has 3 outputs (experiment information, signal and stimulations streams)Additionally, if the box has customizable settings, they may be set by double clicking on the box (tip : when a box has such settings, its name is displayed in bold case). The settings are listed in the popup dialog that appears, along with their default values. Settings may be overriden by directly typing in their desired values, or they may be read from a file. In the latter case, one should expand the ‘Override settings with configuration file’ section to check the ‘File’ button and pick a configuration file.

 

Fig.5 Settings of a ‘GDF file reader’ box : filename text entry,number of samples to be stored per buffer and boolean flag for managing translation by physical minimum value.

Box status

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 :

• 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.

• Disabled : if a box is disabled, its color is blue and will not process its input or generate output. Additionally, disabled 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 ‘disabled’ next to the name of the box.

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 middle 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.
• ‘enable/disable box’ A disabled 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.
• ‘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.
• ‘box documentation’ shows the selected box documentation.
• ‘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.

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.

Fig.6 Example of right-clicking on a box, with disable box feature selected.

Metaboxes

In Designer you can create a specific reusable box as a combination of other boxes. It is called metabox. Metaboxes will appear in the sidebar just like the other boxes, except they are highlighted in a green colour. They will appear in a category folder provided that the Category field has been filled in the scenario description of the metabox. You can drag a metabox into a scenario as you would do for any other box.

• ‘open this metabox in editor’ appears in the right-click menu in addition to the previous described box menu features.

Fig.6 Example of right-clicking on a metabox, with open this metabox in editor feature selected.
For more information about creating and using metaboxes, please refer to the tutorial here.

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.

Fig.7 Example of right-clicking with two boxes and their links selected.Cut/copy your selection by right clicking on it then selecting the corresponding entry, or by pressing Ctrl+X/Ctrl+C.

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.