- NB: last update for OpenViBE 2.0.0 (oct-2017). OpenViBE 1.3.0 compliant version
This section describes the software architecture of the platform. Since 2.0.0 release, OpenViBE is based on the OpenViBE SDK (kernel, specific modules and plugins) that has been developped in the context of the CertiViBE project. In consisted in refactoring and simplifying the openViBE kernel with the objective to improve robustness, quality assurance, predictable behavior and error handling of the software. Consequently, the architecture has been split in three parts: sdk, designer and extras.
The design relies on the concept of box algorithm which ensures maximum flexibility and reusability. The platform is composed of a kernel and several plug-ins dedicated to specific tasks.
Architecture and design documentation provided during the CertiViBE project is available here:
The kernel (see OpenViBE::Kernel::IKernelContext) provides global services to applications through several managers, each of them providing a set of specialized services. Virtually any manager can be added to the kernel in order to extend its services. The most significant managers of the platform are:
The configuration manager (see OpenViBE::Kernel::IConfigurationManager) provides an API for late-binding configuration through the configuration manager. It can reads configuration tokens from a file and initialize configurable items accordingly.
The scenario manager (see OpenViBE::Kernel::IScenarioManager) helps creating and configuring scenarios. After a scenario is created, it can instantiate new box algorithms, change their settings and connect boxes together using communication links. The scenario manager is designed to edit any number of scenarios at once, allowing an application to handle multiple scenarios simultaneously. The designer authoring tool takes advantage of this.
The metabox manager (see OpenViBE::Kernel::IMetaboxManager) is in charge of loading/unloading metaboxes modules (defined in OV_ScenarioImportContext_OnLoadMetaboxImport import context) containing OpenViBE metaboxes. It also provides functions in order to list metabox descriptors, create or release metabox objects.
The player manager (see OpenViBE::Kernel::IPlayerManager) provides an easy to use interface in order to build and configure a runtime session. For this, the manager handles a collection of players, each one managing several boxes, as described in the scenario it has to run. Each of these box rely on a plug-in box algorithm to perform its tasks.
The type manager (see OpenViBE::Kernel::ITypeManager) ensures coherency of all data types. Two kinds of data are manipulated in the platform: simple parameters used to configure boxes, and streams used to connect boxes together and send buffers between boxes. The manager provides a list of registered types, handles conversions and provides information about type compatibility. Simple parameters include integer values, floating point values, strings and filenames. The manager also supports enumerations or bit masks. The stream type tells the scenario editor which box output can be connected to which box input. Stream types are organized hierarchically, allowing to easily downcast some of the streams. For example, an n-electrode raw record will most probably use the signal stream type. This stream type is a specialization of the basic matrix stream type. Thus, each box algorithm working on basic matrix streams will be able to work on raw signal streams.
The log manager (see OpenViBE::Kernel::ILogManager) is responsible for keeping a trace of all the messages the application could send as debug output. Such information is not useful most of the cases but could become crucial in some cases. Thus there are different levels of activation for the log manager to work. The log manager forwards each log request to its registered log listeners that effectively do the log the way they want (be it a status window, a console, a file, whatever). See ILogListener for more details.
The plug-in manager (see OpenViBE::Kernel::IPluginManager) makes the platform extensible. This manager is able to dynamically load plug-in modules (e.g., .DLL files under Windows, or .so files under Linux) and collect plug-in object descriptors from them. Then, using these plug-in object descriptors, it provides the service of building new specialized plug-in objects, acting as an object factory for the whole platform. Specialized plug-in objects include scenario serializers, algorithms and box algorithms (see section The plug-ins).
The plug-in module (see OpenViBE::Kernel::IPluginModule)(CPluginModule) is the platform-specific plugins loader at runtime.
The plug-in system allows to quickly and efficiently expand functionalities. The communication interface between plug-in objects and the platform is defined so that these external objects can be shared, integrated to the platform and replaced when needed.
Our platform includes three different plug-in families:
The algorithm plug-ins (see OpenViBE::Plugins::IAlgorithm and OpenViBE::Plugins::IAlgorithmDesc) are a generic abstraction for any extension that could be added to the platform (e.g., add a new feature extraction or signal processing methods). Only developers can work with this kind of object. Algorithms are the developer’s atomic objects. The developer may compose several algorithms in order to achieve a complex task. This kind of plugin allows to massively share and reuse software components, even in an offline context where time is managed differently (e.g., EEG file reading or signal visualisation widgets).
The box-algorithm plug-ins (see OpenViBE::Plugins::IBoxAlgorithm and OpenViBE::Plugins::IBoxAlgorithmDesc) are the software components each box relies on.
Box algorithm is a key component of the platform. It consists of a “black box” in charge of a fraction of the whole processing pipeline, which exposes inputs and outputs to other box algorithms. Boxes are notified on clock ticks and upon input data and message arrival. The behavior of a box can be adapted to the needs of each algorithm (for instance, acquisition algorithms typically react to clock signals whereas processing algorithms typically react to input arrival). The characteristics and constraints that are common to all box algorithms include reasonable granularity to allow quick software components rearrangement. Newly developed box algorithms are immediately available to the user thanks to the plugin system (see section The plug-ins).
Box algorithm are the atomic objects for the user who designs signal processing scenario. The developer describes them in a simple structure that notably contains the box prototype (its name, input/output connectors and settings). The box algorithm itself is responsible for the actual processing, i.e., it reads from inputs, computes data to produce a result and writes to outputs. However, the box algorithm can combine several algorithm plug-ins together to perform this processing. This ensures fast development thanks to the re-usability of components (e.g., most box algorithms use a specific algorithm in order to easily read from inputs and write to outputs). Thus, the box algorithm can be seen as a set of callbacks called periodically by the player. The most important callbacks are the three notification callbacks (clock tick, input arrival and message arrival) and the actual processing function which produces output data. Each phase of the processing callback can rely on one or more algorithms in order to reuse code.
It should be noted that the box algorithm has a restricted access to kernel functionalities, and can not directly communicate with other box algorithms. A kernel accessor is provided at runtime whenever a callback is triggered, allowing for better flexibility in programming bridges to kernel objects and to other box algorithms.
The scenario loading and saving plug-ins allow to keep and reuse created and configured scenarios in files. In addition to loading and saving scenarios, this plug-in can also be used to import scenarios from closely related softwares or to export scenarios to such softwares. The scenario saver basically writes each scenario component into a file. The scenario loader works the opposite way: it reads from a file and creates each box in turn, configuring and connecting boxes together as needed.
Modules are portable utility components that provide some low-level services:
- Socket: Client-server network connection services
- Date: Date formatting and parsing services
- XML: XML data parsing and serializing services (based on Expat)
- System: System utility services related to memory consumption, timing etc.
- EBML: EBML data parsing and serializing services (see EBML Specifications)
- CSV: utility library used to load/save CSV data
This is a helper module. Some services provided by other modules within OpenViBE are not easy to access or use. This module takes care of wrapping some of these complex services into a much more easy-to-use interface. It is a service usability facilitator.
Actually, algorithm, box algorithm and box listener implementations should not inherit directly from IAlgorithm and IBoxAlgorithm. The openvibe-toolkit component provides wrappers classes (TAlgorithm, TBoxAlgorithm and TBoxListener) that implement IAlgorithm, IBoxAlgorithm and IBoxListener context related calls and provides to subclasses a controlled access to context features. They act as guards to prevent misuse of the context at the algorithm implementation level.
Currently, the player does not take advantage of distributed computing. However, the box algorithm concept makes such distribution possible and easier because the communication is done thanks to input and output connectors and because box algorithms do not share information directly.
The scenario player
openvibe-scenario-player application can be launched in command line to play a scenario. It uses the player manager (see OpenViBE::Kernel::IPlayerManager and OpenViBE::Kernel::IPlayer ) which is responsible for creating and destroying instances of players, each payer being responsible for the execution of a single scenario.
The visualization manager (see OpenViBE::Kernel::IVisualisationManager) is responsible for displaying 2D or 3D graphical information and dispatching it in the correct place. Indeed, multiple visualization windows may be used. The windows arrangement in space is done by the visualization manager at editing time, thanks to the designer application, and saved to a file. Basic signal display windows are provided with a 2D rendering context (see Figure fig-display-widgets), while more advanced rendering is performed thanks to the 3D library encapsulated in the player module (see section openvibe-vr).
Simple visualization plugin
2D topograpic map and Matrix display visualization boxes are included in the Designer package.
Advanced visualization plugin
The Mensia Advanced Visualization Toolset is a collection of boxes dedicated to the visualization of the result of electrophysiological signal analysis, and are especially suitable for the real-time analysis of EEG signals , from raw signal display to 3D source reconstruction.
A designer overview is available here.
Designer is directly imported from the designer package and can dynamically load all plugins available in extras. You can find some tutorial and special features documentation here.
Demos are provided in the package and are documented here.
Acquisition server is a tool designed to communicate with various hardware signal acquisition devices. A documentation is available here.
Plugin inspector is an application responsible for the generation of several documentation elements for each box algorithm. More information about the application is available in the section.
Skeleton generator is a (beta version) tool useful for those who want to implement a new driver or plugin. Documentation is available here.
VRPN simulator demonstrates how to send data to openViBE from an extrenal application. It uses vrpn server to generate signal on specific vrpn channels. Visualisation of the signal can be done with the appropriate boxes Analog VRPN Client or Button VRPN Client, using the tutorial sending-data-from-an-external-application-to-openvibe in the box-tutorial scenarios folder.
TCP Tagging is a software tagging mechanism for time-accurate placement of event markers (called stimulations in OpenViBE) in the EEG signal recordings. You can refer to this post for more information.
Contributions can be freely submitted to the contrib/ folder of the OpenViBE distribution. For more information about authors rights and contribution procedure, please refer to this post.