12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

Downloads

Features

Documentation

Forum

FAQ

Contact

Search...

Tutorial : Using Matlab with OpenViBE

Posted on June 11, 2012 by lbonnet

NB: last update for OpenViBE 0.17.0

Note from the author : the Matlab plugins for OpenViBE have been developed for the researchers more experienced with Matlab scripting
than C++ programming. These plugins now need to be extensively tested to be considered as stable, especially by experienced Matlab
users. Please send us your feedback and suggestion of improvement: bug reports, usability feedback, documentation requests, etc.

BrowseBurst

Related Searches

Note: V0.16.x has a bug that Matlab working directory path can not contain spaces, preventing running Matlab
tutorial scenarios from their default install location on Windows in Program Files (x86). To use the scenarios,
please move them to a folder with no spaces in the path. (This issue has been fixed in the git version.)

Note: On V0.17.0 and Linux, the presence of matlab plugin .so can cause crashes in seemingly unrelated Simple
?

Interface Design
3D Virtual World

DSP box as the two may use different versions of boost which are then wrongly exposed to the other party due to
the dlopen() flag RTLD_GLOBAL. Unfortunately this flag is needed or we get other issues with third-party libraries,
for example that the imports done inside Python plugin scripts no longer work. The compromise solution is that
Matlab plugin compilation is currently by default DISABLED in the main CMakeLists.txt. You may enable the Matlab

Brain Control
Cognitive

plugin compilation and possibly set the flag to RTLD_LOCAL to avoid issues in ovCKernelLoader.cpp, but be aware
of the consequences.

Neuroscience
Neurofeedback
Training
Biofeedback Therapy
EEG Neurofeedback
Biofeedback Therapist

Introduction
OpenViBE is currently compatible with MATLAB through a box:
Matlab Scripting: a general-purpose box with unlimited inputs, outputs and settings. User writes the Matlab functions that will be
called by the box.
This box is developed and supported by the Inria team. It relies on the Matlab Engine, and requires a valid installation of Matlab to be
compiled and to run. To be precise, the Matlab documentation states :

Brain Function
Virtual Reality World

The MATLAB engine library contains routines that allow you to call MATLAB software from your own programs, thereby
employing MATLAB as a computation engine. You must use an installed version of MATLAB; you cannot run the MATLAB
engine on a machine that only has the MATLAB Compiler Runtime (MCR).
The Matlab Scripting box is included in the official release packages, and thus can be used directly in any scenario, as long as you have
a valid Matlab installation on your computer.

Requirements
The Matlab box has been tested on Windows 7 32 bits + MATLAB R2011a 32 bits. Unfortunately Matlab R2011a is not compatible with
Ubuntu 11.04 and superior versions. The official ubuntu support page says : MATLAB R2011a was released on April 8, 2011. Please
note that this is prior to the release of Ubuntu 11.04. Consequently Ubuntu 11.04 is not a supported operating system for MATLAB
R2011a. MATLAB R2011a users are strongly encouraged to install R2011a on Ubuntu 10.04 LTS or Ubuntu 10.10 for best results..

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

1/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

For your information, the latest Matlab Release (R2012a) is currently compatible with Ubuntu 10.04 LTS, 11.04, 11.10, as stated in the
Matlab support page.
The boxes are not compatible with MATLAB 64 bits on Windows.
Please contact us to inform us of any compatibility issue. We will update this section with your feedback !

Compiling the plugins/processing/matlab project

A valid installation of MATLAB includes all the libraries and exe required to compile and use the boxes.
To be precise, CMake looks for the following libraries when compiling OpenViBE:
On Windows : libmex.lib, libmx.lib, libeng.lib under ${Matlab_ROOT}/extern/lib/win32/microsoft/
On Linux : mex, mx, eng, under ${Matlab_ROOT}/bin/glnx86 or ${Matlab_ROOT}/bin/glnxa64
When building the software, the process should find all these libraries, as showed in the following build log example:
A successful build log on Windows

(click here to show content)

If the build process does not find a valid MATLAB installation, the boxes wont be built with the project. An empty dynamic library will be
produced, which will result in the following message in the console when executing the OpenViBE Designer :
[WARNING] No 'plugin object descriptor' found from [../bin/openvibe-plugins-matlab.dll]
even if it looked like a plugin module

When building OpenViBE with an invalid MATLAB installation (i.e. MATLAB 64 bits on Windows) the build process will find MATLAB but
not the libs resulting in the following build log :
Build fails on Windows with MATLAB 64 bits

(click here to show content)

The Matlab Scripting box

The Matlab Scripting box is available in the Designer in the category Scripting.
Here is the different settings and how to set it correctly :
Box clock frequency (in Hertz) : defines the frequency on which the box will be called by OpenViBE, from 1 to 128 Hz. Default
value is 64Hz, you can lower it if you experience bad performance when executing the box.
Path to Matlab executables (Windows) / Matlab launch command (Linux): tells OpenViBE how to execute the Matlab engine.
Set it the directory where is matlab.exe on windows or type the command you use to launch Matlab on Linux.
Matlab working directory : the directory where are located all your function files. This path must be Matlab compliant (i.e. some
special characters are not recognized)
Initialize function : the name of the Matlab function called by the box when pressing play in the scenario.
Process function : the name of the Matlab function called by the box on every box clock tick.
Uninitialize function : the name of the Matlab function called by the box when pressing stop in the scenario.
You can add as many input and output as you need. All the stream types are compatible. You can also add new settings in the box, they
will be available in the Matlab structure as well.
You can use more than one Matlab Scripting box in the same scenario. Each box has its own matlab workspace defined in the box
setting.
http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

2/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

If you are using the same workspace for several boxes, they will share this workspace. For example a global variable could be modified
by all the boxes of the same workspace.

The OpenViBE toolbox for the Matlab Scripting box

The Matlab Scripting box relies on a set of Matlab functions to work. This toolbox is installed with openvibe in
share/openvibe/plugins/matlab.
It contains 2 types of functions: those called by the box itself internally, and those who are meant to be called by the user in his script. In
this section we describe these functions and the structures manipulated by Matlab and OpenViBE.

Setting up the environment

The box automatically sets up the Matlab environment to work properly. For your information, here is the procedure:
The box first creates a representation of the openvibe box in matlab:
box = OV_createBoxInstance(input_count, output_count) :
out STRUCT box : a structure representing the box in Matlab:
in DOUBLE input_count : the number of input of the box, to create the structures accordingly.
in DOUBLE output_count : the number of output of the box, to create the structures accordingly.

Then it calls a function that will create several global variables for all the OpenViBE stimulation codes:
OV_defines()

The name of the variables and their values are strictly the same as in OpenViBE. For example:
global OVTK_StimulationId_Label_00;
OVTK_StimulationId_Label_00 = uint64(hex2dec('00008100')); // 33024

Thus you can directly compare a stimulation identifier received on an input to these global variables.

Matlab structures and functions description

One instance of the Matlab Scripting box creates its own box in Matlab. This box is passed as an argument of every functions. For the
functions that outputs a new box instance, the same variable is used and thus is updated.
The box structure is defined as follow:
STRUCT box:
> box.clock

: DOUBLE the current openvibe time, updated at every clock tick.

> box.clock_frequency : DOUBLE the box clock frequency.

> box.settings

: an array of setting structure(s).

> box.inputs

: a cell array of input structure(s).

> box.outputs

: a cell array of output structure(s).

> box.user_data

: empty user-space structure.

The box clock and clock frequency are very useful when your script needs to generate an output, but lacks an input to synchronize with.
The setting structures are filled according to the openvibe box settings defined in the scenario. Default settings are not stored in the
structure.
STRUCT setting :
> setting.name : STRING (name of the setting in the openvibe box).
> setting.type : UINT64 openvibe code of the setting type.

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

3/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

> setting.value : the value of the setting. Its type can be DOUBLE (for the openvibe types integer and float),
LOGICAL (boolean), UINT64 (stimulation code) or STRING (anything else).

The input and output structures are defined by particular headers, and are meant to be filled at run time. When the Matlab Scripting box
receives the headers on its inputs it forwards the information to Matlab, and modify the box representation accordingly.
The output headers structure must be set by the user in the Matlab script. Once the header is set, the Matlab Scripting box is able to get
this information from the matlab structure and construct the corresponding OpenViBE header.
The IO structures also contains a buffer for the incoming chunk of data.
STRUCT input/output :
> io.header : STRUCT containing the stream description (e.g. for a signal: channel names, sampling rate, etc).
> io.buffer : CELL ARRAY of chunk structure(s).

The different header structures are listed below, along with the corresponding functions to set it in a convenient way (i.e. you wont miss a
field). Manually setting the header structures of your output is of course also possible (e.g. if your output stream has the same structure as
an input, input.header = output.header is the simplest way to set it).
NB: A corresponding Getter function also exists for each header type. These functions are called by the Matlab Scripting box to get all the
information in one call to the Matlab engine.
STRUCT header : STREAMED MATRIX
> header.type

: STRING = 'Streamed Matrix Stream'

> header.nb_dimensions

: DOUBLE number of dimensions of the matrix (N)

> header.dimension_sizes : 1xN DOUBLE ARRAY of dimension sizes (one size per dimension)
> header.dimension_labels : 1xN CELL ARRAY of STRING

Setter Function (optional):

[box_out] = OV_setStreamedMatrixOutputHeader(box_in, output_index, nb_dim, dim_sizes, dim_labels)

STRUCT header : SIGNAL

> header.type

: STRING = 'Signal Stream'

> header.nb_channels

: DOUBLE number of channels

> header.nb_samples_per_buffer : DOUBLE number of samples per buffer block

> header.channel_names

: CELL ARRAY of STRING

> header.sampling_rate

: DOUBLE sampling frequency

Setter Function (optional):

[box_out] = OV_setSignalOutputHeader(box_in, output_index, nb_channel, nb_samples_per_buffer, channel_names, sampling_rate)

STRUCT header : FEATURE VECTOR

> header.type

: STRING = 'Feature Vector Stream'

> header.nb_features : DOUBLE number of feature in the vector

> header.labels

: CELL ARRAY of STRING

Setter Function (optional):

[box_out] = OV_setFeatureVectorOutputHeader(box_in, output_index, nb_features, labels)

STRUCT header : SPECTRUM

> header.type

: STRING = 'Spectrum Stream'

> header.nb_channels

: DOUBLE number of channels

> header.channel_names : CELL ARRAY of STRING

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

4/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

> header.nb_bands

: DOUBLE number of frequency bands in the spectrum

> header.band_names

: CELL ARRAY of STRING the name of the bands (e.g. '10-15Hz')

> header.bands

: [nb_bands x 2 DOUBLE] the pairs of frequencies (band start and stop)

Setter Function (optional):

[box_out] = OV_setSpectrumOutputHeader(box_in, output_index, nb_channels, channel_names, nb_bands, band_names, bands)

STRUCT header : CHANNEL LOCALISATION

> header.type

: STRING = 'Channel Localisation Stream'

> header.nb_channels

: DOUBLE number of channels

> header.channel_names : CELL ARRAY of STRING

> header.dynamic

: LOGICAL tells if coordinates are dynamic

Setter Function (optional):

[box_out] = OV_setChannelLocalisationOutputHeader(box_in, output_index, nb_channels, channel_names, dynamic)

STRUCT header : STIMULATIONS

> header.type

: STRING = 'Stimulation Stream'

Setter Function (optional):

[box_out] = OV_setStimulationsOutputHeader(box_in)

As you can see all the setter functions take a box structure as input, and output the modified box structure. A typical call is thus:
box = OV_setXXXXXOutputHeader(box, ...)
% ... continue using the 'box' variable ...

The chunk structure stored in the IO buffers can be either a matrix (for Stramed Matrix stream and its child streams) or a stimulation set.
STRUCT chunk : MATRIX CHUNK
> chunk.start_time : DOUBLE translation of the openvibe timestamp in seconds, precision 0.0001 sec.
> chunk.end_time

: DOUBLE

> chunk.matrix_data : DOUBLE ARRAY the matrix of data.

The structure of the matrix is the same as in OpenViBE.
For example, a signal matrix has N(channels) lines and N(samples) columns.

STRUCT chunk : SIMULATION CHUNK

> chunk.start_time : DOUBLE translation of the openvibe timestamp in seconds, precision 0.0001 sec.
> chunk.end_time

: DOUBLE

> chunk.matrix_data : DOUBLE ARRAY the stimulation set containing N stimulation(s).

N stimulations are stored in a 3xN matrix, ie. 1 stimulation per column.
Each stimulation is defined by its code, date and duration.

The buffers may contains any number of chunks. The buffers can be manipulated through convenient matlab functions:
% To get the current count of pending chunk in buffer:
nb_pending = OV_getNbPendingInputChunk(box_in, input_index)
out DOUBLE nb_pending : the number of pending chunk in the buffer.
in STRUCT box_in

: the box structure.

in DOUBLE input_index : index of the input.

% To pop the oldest chunk in a buffer (i.e. the first chunk to process)

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

5/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

% Note that the chunk is removed from the buffer after this call.
[box_out, start_time, end_time, matrix_data] = OV_popInputBuffer(box_in, input_index)
out STRUCT box_out

: the Matlab box after modification.

out DOUBLE start_time : the chunk start time in seconds.

out DOUBLE end_time

: the chunk end time in seconds.

out ARRAY matrix_data : the data, type and structure depends on the stream type.
in STRUCT box_in

: the Matlab box from which we pop a new chunk.

in DOUBLE input_index : the input index in the box.

If there is no chunk in the buffer the function returns:

> start_time = -1
> end_time

= -1

> matrix_data = []

When you need to output a new buffer, you can do so by calling the following function:
% To add a new chunk in an output buffer:
[box_out] = OV_addOutputBuffer(box_in,output_index,start_time,end_time,matrix_data);
out DOUBLE box_out

: the box after modification.

in STRUCT box_in

: the box structure.

in DOUBLE output_index : index of the input.

in DOUBLE start_time

: the chunk start time in seconds.

in DOUBLE end_time

: the chunk end time in seconds.

in ARRAY matrix_data : the data, type and structure depends on the stream type

Tutorial 1 : signal filter

Open the scenario share/openvibe/scenarios/box-tutorials/matlab/tuto1-signal-filter.xml.
This scenario is very simple : it filters a sinus signal and sets all the samples to 0 when receiving a specific stimulation. If the same
stimulation is received once again, the output signal goes back to normal.
The Matlab Scripting box takes 2 inputs : the signal and the stimulation stream. It outputs a signal which has the same structure (channel
count, etc.) as the input.
First step is to configure the Matlab Scripting box. You need to set your local Matlab directory and the working directory to match your
local installation of Matlab and OpenViBE. The working directory is [openvibe]/share/openvibe/scenarios/box-tutorials/matlab/. It must
be an absolute path. The three matlab functions are in this directory.
Finally, as you can notice we added a new setting named zero trigger of type Stimulation. This defines which stimulation is used to
switch the behavior of the box.

Configuring the Matlab Scripting Box

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

6/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

Initialization script
Open the Matlab function file tuto1_signal_filter_Initialize.m.
tuto1_signal_filter_Initialize.m

(click here to show content)

This function add a field in the user_data structure in the box : a boolean indicating the current state of the trigger. Please note that we
must output the modified box to be able to use it afterwards. This function will be called once, when pressing play in the scenario.

Process script
Open the Matlab function file tuto1_signal_filter_Process.m.
tuto1_signal_filter_Process.m

(click here to show content)

As we set the box clock frequency to 64 Hz, this function will be called 64 time per second. It works in two steps. First we check the
stimulation input for new triggers, and switch the box field accordingly. Note that every time we pop a new input chunk, we use the current
box instance as output, to continue the processing on an updated box structure. In this case, the pop functions remove the last input
chunk from the buffer.
As we only modify the samples values of the input signal, we set the output header as a copy of the input header. This will be done with
every process but it is only needed once (prior to the first buffer ever sent).

Uninitialization script
Open the Matlab function file tuto1_signal_filter_Uninitialize.m.
tuto1_signal_filter_Uninitialize.m

(click here to show content)

We dont need to do anything when stopping the scenario, we just display a message.

Execution
The result can be found below. The signal is set to 0 when the stimulation OVTK_StimulationId_Label_01 (33024) is received.

In the console, you can see the corresponding output :

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

7/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

Console output

(click here to show content)

Tutorial 2 : FFT and Matlab plot

Open the scenario share/openvibe/scenarios/box-tutorials/matlab/tuto2-FFT-filter.xml.
In this scenario we add some noise in the upcoming signal, and plot the spectrum amplitude (FFT) in Matlab to check if this noise
appears in the signal.
Please note that we only do this process on the first channel of the signal, thus the output signal has only one channel. At the end, we will
plot the mean spectrum before stopping the scenario.
First step is to configure the Matlab Scripting box. You need to set your local Matlab directory and the working directory to match your
local installation of Matlab and OpenViBE. The working directory is [openvibe]/share/openvibe/scenarios/box-tutorials/matlab/. It must
be an absolute path. The three matlab functions are in this directory.
We added 4 FLOAT settings : the noise frequency and amplitude, that will be added in the signal, and the frequency range used for
plotting the spectrum.

Initialization script
Open the Matlab function file tuto2_FFT_filter_Initialize.m.
tuto2_FFT_filter_Initialize.m

(click here to show content)

This function prints the box settings and add fields in the user_data structure in the box : a boolean indicating if we need to set the output
header, and the variables we need to compute the mean spectrum. Please note that we must output the modified box to be able to use it
afterwards. This function will be called once, when pressing play in the scenario.

Process script
Open the Matlab function file tuto2_FFT_filter_Process.m.
tuto2_FFT_filter_Process.m

(click here to show content)

The header is set once, and hes just the input header with one constraint : one channel only.
The FFT is plotted on every input chunk. If your input stream has a high frequency, you wont be able to see something. In our scenario, we
compute a 2 second window before passing it to Matlab, using Time Based Epoching. Therefore you will have one figure updated every
2 seconds of signal.

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

8/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

The figure plotted has 3 subfigures : the pure noise signal, the signal corrupted with this noise, and the amplitude spectrum.

Uninitialization script
Open the Matlab function file tuto2_FFT_filter_Uninitialize.m.
tuto2_FFT_filter_Uninitialize.m

(click here to show content)

The Uninitialize function plots the mean spectrum amplitude matrix and pauses the execution for 10 seconds. After the pause, the
scenario is stopped and the Matlab engine closed (so it closes any figure automatically).

Execution

Signal display in OpenViBE

Plotting the results in Matlab

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

9/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

Mean spectrum amplitudes

In the console, you can see the corresponding output :
Console output

(click here to show content)

Tutorial 3 : Signal and Stimulation generator

Open the scenario share/openvibe/scenarios/box-tutorials/matlab/tuto3-sinus-generator.xml.
The Matlab Scripting box is configured to produce a sinusoidal signal and stimulations.

We added 4 new settings in the box : the channel count (integer), the samples per buffer count (integer), the amplitude of signal (float),
and the stimulation sent every second.
In the current configuration, the box clock frequency is set to 32Hz. With 16 samples per buffer, we thus have a sampling frequency of
32*16 = 512Hz.
The signal is simply a different sinusoid for each channel, the frequency being a multiple of 10Hz (10Hz for first channel, 20Hz for second,
etc.).

Initialization script

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

10/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

Open the Matlab function file tuto3_sinus_generator_Initialize.m.

tuto3_sinus_generator_Initialize.m

(click here to show content)

This function prints the box settings and add fields in the user_data structure in the box : the end time of the last data chunk sent, a
sample and a chunk counters. As we produce ourselves the signal and stimulation streams, we can set the headers in the initialization
phase. For this purpose we use the functions of the openvibe toolbox.
Please note that we use the same variable box_in as output of these functions so we keep working on an updated box structure.

Process script
Open the Matlab function file tuto3_sinus_generator_Process.m.
tuto3_sinus_generator_Process.m

(click here to show content)

We produce a N-by-M signal matrix. One channel per line, samples_per_buffer columns. Along with each chunk of signal, we also
produce a stimulation set. Most of the time its an empty set, but its still important as the other box after our generator may need to know
if there is no stimulation is the last time range. As you notice, a stimulation set is made of N columns, one stimulation per column (stim
identifier, date then duration). This matrix structure allows the box to parse all the stimulations in a set directly, as the matrix is indexed
column after column.

Uninitialization script
Open the Matlab function file tuto3_sinus_generator_Uninitialize.m.
tuto3_sinus_generator_Uninitialize.m

(click here to show content)

As you can see the Uninitialize function does nothing.

Execution
The box generates some sinusoidal signal automatically, along with stimulations (one every second see the red lines):

Sinus Generator
In the console, you can see the corresponding output :
Console output

(click here to show content)

Few words about the Matlab Filter box

The Matlab project in the OpenViBE software platform contains a previous prototype for scripting with Matlab in OpenViBE : the Matlab
Filter Box.

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

11/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

This box is still flagged as deprecated, is not displayed in the Designer and is not recommended for use.
The Matlab Filter box has fixed inputs (1 streamed Matrix and 1 stimulation inputs), and fixed outputs (same). The box has to be
configured with the path or command to launch Matlab on your computer, the working directory in which you created the initialize
and process functions.
The Process function will be called every time a chunk is available on both inputs. It means that you absolutely need a Streamed Matrix
input (or derivated, e.g. signal) and a stimulation input. If you dont need one of them, you can use a dummy input using Clock stimulator
or Sinus Oscillator boxes on the useless input.
A simple example is provided with the Matlab Filter box documentation page.
The main difference between the 2 boxes is the data structure for the matrices: in the Matlab Filter box, the signal matrix is oriented as
N(channels)columns for N(samples)lines.

Troubleshooting
In this section, we review the most common errors and mistakes and what they can cause.
Please contact us on the regular channels if you find any unexpected behavior or bugs so we can either correct the Matlab boxes or add
new items in this section.
Failed to Load Matlab Engine at first try
With the Windows Installer version, we identified an incorrect behavior of the box : when pressing play for the first try, the scenario wont
find Matlab and the box will fail to execute correctly. When re-playing the scenario by pressing play once again, the Matlab Engine (if
everything is correctly set) should successfully run.
This bug does not happen with an OpenViBE built from sources. Investigations are in progress.
On Linux, MATLAB filter keeps saying Cant start MATLAB engine, what do I do ?
In order to get MATLAB filter to work properly on Linux, you need cshto be installed. This is not always the case, notably on Ubuntu
distributions.
On Linux, loading the Matlab plugin says error:libmx.so: cannot open shared object file: No such file or directory?
Before launching Designer, you must export LD_LIBRARY_PATH to include the path where the Matlab .so files are installed.
Matlab License
The Matlab Engine can be launched in background only if it can access a valid Matlab License.
If the Matlab License Manager cant get a valid License, it will output an error window. The OpenViBE Designer would then be still waiting
for the Matlab Engine to respond: you can expect the application to freeze for about 30 seconds. After this timeout, the call to Matlab
engine fails and the following message would be printed in the console:
[ ERROR ] At time 0.000 sec <Box algorithm::Matlab Scripting> Could not open Matlab engine
[WARNING] Box algorithm <Matlab Scripting> has been deactivated because initialization phase returned bad status

The box being deactivated, it does not process any data but the scenario would keep running without it.
Output Headers : be sure to set it right !
If you try to send a new buffer on an output and you get this message for example :
[ ERROR ] At time 0.094 sec <Box algorithm::Signal filter> Error calling [OV_getSignalOutputHeader]. Did you correctly set
the output header in the matlab structure ?

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

12/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

It means that you didnt set the header (here its a signal output) correctly. The box is not able to construct the OpenViBE output stream.
Solution : set the header before the very first buffer sent. You can either use an existing header, as it is done in tutorial 1, or the
dedicated Matlab functions as in tutorial 3.
If you construct a somehow corrupted header or a header that does not match the theoretical stream structure, the application has a
good chance of crash.
For example, if you omit a field or use a field incorrectly (e.g. header.sampling_rate = 'plop') the Designer can just randomly
crash during execution. We are aware of this problem and we will try to improve error handling in the following updates.
Be sure to save your OpenViBE scenarios often.
Manually closing the Matlab engine
The Matlab Scripting box opens the Matlab Engine on initialization (play) and closes it when uninitializing (stop). If an error occurs the
Matlab Engine may not be closed correctly. This means that when you will run a scenario with a Matlab Scripting box once again, it will
use the previous engine, still in the state you left it ! This can lead to unexpected behavior (e.g. if you have some global variables you are
using in your script, they will still be there).
The simplest way to check the state of the Matlab Engine is by looking at the matlab window running in background. When opening the
engine, Matlab launch a specific window called Matlab Command Window. This window is a basic Matlab interpreter in which you can
type Matlab commands. When closing the Engine, this window should be closed automatically. If such window is still alive when there is
no Matlab scenario running in the OpenViBE Designer, close it manually before playing such scenario.
Performance issues
Depending on the processing you implemented the Matlab scripting boxes may take some time to do the process. If a box spends too
much time its process loop, a message would be printed in the console:
[WARNING] <Player::can not reach realtime> 1 second(s) late...
[WARNING] <Player::can not reach realtime> 2 second(s) late...
[WARNING] <Player::can not reach realtime> 3 second(s) late...
[WARNING] <Player::can not reach realtime> 4 second(s) late...
[WARNING] <Player::can not reach realtime> 5 second(s) late...

Meaning that the OpenViBE Player, that schedules the process of every boxes, is not able to process the data in real-time. For example,
if you set the Matlab scripting box clock frequency to 32Hz, one process call should be less than 1/32 th second long. Otherwise, the
process loop accumulates a delay.
Try to lower the clock frequency to extend the period of time between 2 process calls. The Matlab process function may have to process
more chunk of data at a time (internal buffers are filled continuously), but you will save the interface time, between the C++ code and the
Matlab engine.

This entry was posted in Tutorials and tagged Matlab, Tutorial. Bookmark the permalink.

Quick Access

OpenViBE World

Development

Community

Downloads

Contact

How to contribute

Forum

Source Repository

Publications

Bugtracker

Contributors

License

Made With

Inria gForge

Community Website

Features

Related Projects

Build status

Documentation

Inria Homepage

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

13/14

12/30/2014

Tutorial : Using Matlab with OpenViBE | OpenViBE

IRC: #openvibe @ irc.freenode.net

Inria Rennes ( 2014)

T witter: @openvibebci

All logos and tradem arks belong to their respective copyright owners.

Hosted by

powered by WordPress

http://openvibe.inria.fr/tutorial-using-matlab-with-openvibe/

14/14