Designer Tutorial 5: Metaboxes

  • NB: last update for OpenViBE 2.0 (sep-2017).

Introduction

In Designer you can create new boxes by assembling them from parts of other boxes, they are called metaboxes. This feature becomes interesting in two cases:

  • when a scenario contains duplicated set of boxes, metabox can really simplify the schema building and understanding,
  • if you want to create a specific reusable box as a combination of other boxes.

For example, the following picture shows the classification-0-training.xml scenario located in the box-tutorial folder. We can see that the set of boxes {Spatial Filter, Signal Average, Feature Agregator} is repeated 3 times in order to simulate 3 classes of features given to the input of a Classifier Trainer.

classification-0-training.xml

A metabox can be built with the three repeated boxes as follows, one setting associated to Spatial Filter Coefficients setting of the Spatial Filter box, one Signal input and two outputs (Signal and Feature Vector) connected as followed:

FeatureClass i metabox

This metabox can be used in the original scenario by replacing the repeated set of boxes by three instances of it, connected to the corresponding inputs and outputs. The setting defined in the metabox can be set for each instance as it was done in the original scenario.

Original scenario with metabox instances

Metabox characteristics

A metabox behaves just like a normal box, that is:

  • It has an arbitrary number of inputs and outputs using the same types as other boxes.
  • It can have an arbitrary number of settings.
  • It can be inserted into a scenario.

For the moment, visualizations are not available in metaboxes. Metaboxes are loaded on start-up of the Designer. They are loaded from the configuration directory: "${Path_Data}/metaboxes/;${Path_UserData}/metaboxes/". Designer can only write under the “.mxb” (text) extension but can load files with both “.mxb” or “.mbb” (binary) extensions.

Creating metaboxes

In order to create a metabox you first have to create a scenario. We decide to make a metabox that will apply a notch filter for 48-52Hz and then apply an arbitrary band-pass filter on the signal.
Thus our metabox consists of:

  • One Signal input
  • One Signal output
  • Two temporal filter boxes
  • Two settings
    • Lower frequency bound
    • Upper frequency bound

Creating a metabox – step 1: adding boxes and settings

We create a new empty scenario and add two settings to it by selecting the Scenario Configuration panel on the right, Configure Setting,Add Setting two times and set the default values. These settings will be used inside the scenario using the $var{NameOfTheParameter} keyword ($var{LowCutFrequency} and $var{HighCutFrequency} in our example).
We also drag two temporal filter boxes inside and set them up like so:

 

Scenario settings

First Temporal filter box is renamed Notch filter (right-click + rename box: Notch Filter), the second one is renamed Band Pass.

Band Pass filter settings

Of course we set the notch filter to a band stop filter with cut off frequencies at 48 and 52Hz whereas the band pass filter will be set to the values LowCutFrequency and HighCutFrequency declared in the scenario settings.

Creating a metabox – step 2: adding inputs and outputs

For the moment, we have created a simple scenario which is not considered as a metabox. In order to “expose” inputs and outputs of our scenario and consequently make the scenario be considered as a metabox, we need to add some inputs and outputs to it using the Scenario I/O tab. To add an input or output simply click the appropriate add button. A setting has only a name and a type. By default the created type is Streamed Matrix.
- Add one input to the scenario, change its type to Signal and rename it to Input Signal
- Add one output to the scenario, change its type to Signal and rename it to Filtered Signal

 

Adding Input and Output

In order to associate a scenario input with a box input, right click on the box you wish to send the input to. A new context menu item will be available: Connect scenario inputs. In this context menu item will be a list of all box inputs which will again open a list of all scenario inputs. Clicking on the scenario input will link the box input to the scenario input.

Right click on the Notch filter box. In the connect scenario inputs submenu you will see the single input of the box. Incidentally it is also called “Input Signal”, under this item there will be another item call “Input Signal” – this is our scenario’s input.

 

Linking a scenario input

Now do the same for the output. A circular indicator will be displayed to represent the link between the scenario input and the box input.

 

Linked Input and Output

Adding metadata

The metabox reads its metadata from the scenario information. You can edit it by clicking on the star button in the toolbar.

The most important attributes are Name and Category. This is how your box will be identified inside the box-algorithm list.

Save your box inside the ${Path_Data}/metaboxes/ or ${Path_UserData}/metaboxes/ folders. The file name can be different from the metabox one and can be renamed as well.

Restart Designer in order to reload the box list.

 

Change about scenario

Using the metabox within a scenario

Metaboxes will appear in the sidebar just like the other boxes, except they are highlighted in a green colour.

You can drag a metabox into the scenario as you would do for any other box.

 

Metabox in scenario

The metabox can be configured as any other box : double clicking on the metabox will reveal all of the settings of the scenario that represents the metabox.

Right clicking on the metabox and selecting open this metabox in editor will open the metabox in a new scenario sheet. You can edit the metabox again but do not forget to restart Designer before reusing it!

Enjoy this new feature and please don’t hesitate to share your creations on the forum !

This entry was posted in Designer documentation. Bookmark the permalink.