Mentions légales du service

Skip to content
Snippets Groups Projects

Resolve "Bug: Fix Documentation"

Merged Resolve "Bug: Fix Documentation"
113-bug-fix-documentation into development
Merged Thomas PRAMPART requested to merge 113-bug-fix-documentation into development
Compare
and
4 files
+ 127
− 149
Compare changes
  • Side-by-side
  • Inline
Files
4
contrib/applications/developer-tools/pybox-manager/README.md
+ 71
− 89
# OpenViBE Python
# OpenViBE PyBox
This Project aims to bring modifications to OpenVibe and to widen its data-oriented functionnalities. OpenVibe is a signal processing software allowing the use of machine learning algorithms, however their number is reduced. Thus, we woud like to benefit from the Openvibe Python scripting box (which allows the use of python scripts in OV) in order to allow users to use Scikit-learn Machine Learning algorithms.
This Project aims to bring modifications to OpenViBE and to widen its data-oriented functionnalities. OpenViBE is a signal processing software allowing the use of machine learning algorithms, however their number is reduced. Thus, we woud like to benefit from the OpenViBE Python scripting box (which allows the use of python scripts in OV) in order to allow users to use Scikit-learn Machine Learning algorithms.
## Dependancies
@@ -8,56 +8,38 @@ This Project aims to bring modifications to OpenVibe and to widen its data-orien
## What OpenViBE Python allows
- The use of components already implemented in OpenVibe that will allow you to :
- The use of components already implemented in OpenViBE that will allow you to :
- The use of ML algorithms from Scikit-learn and Pyriemann (Library centered on the use of Riemannian geometry) that will allow you to train and store models.
- Visualization of your data in 2D/3D via a PCA or LDA.
- Easily create datasets compatible with OpenVibe's operation
- Easily create datasets compatible with OpenViBE's operation
- The use of a manager that allows you to simply :
- Create new boxes in OpenVibe
- Create new types of openvibe settings that can be used in your new boxes.
- Create new boxes in OpenViBE
- Create new types of OpenViBE settings that can be used in your new boxes.
- The reuse of our scripts in order to simply implement your own python data management
1. The new boxes
TrainerML / ML Class Boxes
Box ProcessML
Box DataViz
DatasetCreator Box
2. The Pybox Manager
Box Manager
Stimulations / Labels Manager
Custom Settings Manager
3. Internal functioning and details
Our box model: PolyBox
Input management with PolyBox, two modes possible
Duplicating the Python Scripting Box
PolyBox: Automatic data storage
Managing Custom Settings
Translated with www.DeepL.com/Translator (free version)
## Table des matières
- [OpenViBE Python](#openvibe-python)
- [Dependancies](#dependancies)
- [What OpenViBE Python allows](#what-openvibe-python-allows)
- [Table des matières](#table-des-mati%c3%a8res)
- [1. The new boxes](#1-the-new-boxes)
- [TrainerML Class / ML Boxes](#trainerml-class--ml-boxes)
- [Scikit-learn](#scikit-learn)
- [Pyriemann](#pyriemann)
- [Box ProcessML](#box-processml)
- [Box DataViz](#box-dataviz)
- [Box DatasetCreator](#box-datasetcreator)
- [2. The Pybox Manager](#2-the-pybox-manager)
- [Box Manager](#box-manager)
- [Stimulations / Labels Manager](#stimulations--labels-manager)
- [Custom Settings Manager](#custom-settings-manager)
- [3. Internal Functioning and Details](#3-internal-functioning-and-details)
- [Our Box model : PolyBox](#our-box-model--polybox)
- [Input management with PolyBox, two possible modes](#input-management-with-polybox-two-possible-modes)
- [Duplicating the Python Scripting Box](#duplicating-the-python-scripting-box)
- [Automatic data storage](#automatic-data-storage)
- [Managing Custom Settings](#managing-custom-settings)
- [Dependancies](#dependancies)
- [What OpenViBE Python allows](#what-openvibe-python-allows)
- [Table des matières](#table-des-mati%c3%a8res)
- [1. The new boxes](#1-the-new-boxes)
- [TrainerML Class / ML Boxes](#trainerml-class--ml-boxes)
- [Scikit-learn](#scikit-learn)
- [Pyriemann](#pyriemann)
- [Box ProcessML](#box-processml)
- [Box DataViz](#box-dataviz)
- [Box DatasetCreator](#box-datasetcreator)
- [2. The Pybox Manager](#2-the-pybox-manager)
- [Box Manager](#box-manager)
- [Stimulations / Labels Manager](#stimulations--labels-manager)
- [Custom Settings Manager](#custom-settings-manager)
- [3. Internal Functioning and Details](#3-internal-functioning-and-details)
- [Our Box model : PolyBox](#our-box-model--polybox)
- [Input management with PolyBox, two possible modes](#input-management-with-polybox-two-possible-modes)
- [Duplicating the Python Scripting Box](#duplicating-the-python-scripting-box)
- [Automatic data storage](#automatic-data-storage)
- [Managing Custom Settings](#managing-custom-settings)
## 1. The new boxes
@@ -79,39 +61,39 @@ Here are the new algorithms / boxes implemented in OV :
<https://scikit-learn.org/stable/>
> | Box Name | Algorithm |
> | :-: | :-: |
> | Nearest Centroid | NearestCentroid |
> | Nearest Neighbors Classifier | KNeighborsClassifier |
> | Gaussian Naive Bayes | GaussianNB |
> | Stochastic Gradient Descent | SGDClassifier |
> | Logistic Regression | LogisticRegression |
> | Decision Tree Classifier | DecisionTreeClassifier |
> | Extra Trees | ExtraTreesClassifier |
> | Bagging | BaggingClassifier |
> | Random Forest | RandomForestClassifier |
> | Support Vector Machine | LinearSVC |
> | Linear Discriminant Analysis | LinearDiscriminantAnalysis |
> | AdaBoost | AdaBoostClassifier |
> | Multi Layer Perceptron | MLPClassifier |
> | Linear SVC | LinearSVC |
| Box Name | Algorithm |
| :-: | :-: |
| Nearest Centroid | NearestCentroid |
| Nearest Neighbors Classifier | KNeighborsClassifier |
| Gaussian Naive Bayes | GaussianNB |
| Stochastic Gradient Descent | SGDClassifier |
| Logistic Regression | LogisticRegression |
| Decision Tree Classifier | DecisionTreeClassifier |
| Extra Trees | ExtraTreesClassifier |
| Bagging | BaggingClassifier |
| Random Forest | RandomForestClassifier |
| Support Vector Machine | LinearSVC |
| Linear Discriminant Analysis | LinearDiscriminantAnalysis |
| AdaBoost | AdaBoostClassifier |
| Multi Layer Perceptron | MLPClassifier |
| Linear SVC | LinearSVC |
#### Pyriemann
<https://pyriemann.readthedocs.io/en/latest/index.html>
> | String | Algorithm |
> | :-: | :-: |
> | Riemann Minimum Distance to Mean | MDM |
> | Riemann Tangent Space | TangentSpace |
| String | Algorithm |
| :-: | :-: |
| Riemann Minimum Distance to Mean | MDM |
| Riemann Tangent Space | TangentSpace |
You can easily find information on each of these methods in the docs of their library.
For each of these classifiers, an Openvibe box using TrainerML with the appropriate parameters has been created. So, if you want to train with the Random Forest algorithm of Scikit-learn for example, you just have to look for the associated box in Openvibe and you will be able to use it directly, and modify the parameters related to the algorithm. You will find the information concerning all these parameters on the respective pages of the algorithms, ex: <https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html.>
For each of these classifiers, an OpenViBE box using TrainerML with the appropriate parameters has been created. So, if you want to train with the Random Forest algorithm of Scikit-learn for example, you just have to look for the associated box in OpenViBE and you will be able to use it directly, and modify the parameters related to the algorithm. You will find the information concerning all these parameters on the respective pages of the algorithms, ex: <https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html.>
![random-forest.PNG](Assets/Doc/random-forest.PNG)
> ![random-forest.PNG](Assets/Doc/random-forest.PNG)
>
> Example of parameterization of a box implementing Random Forest
Example of parameterization of a box implementing Random Forest
### Box ProcessML
@@ -156,7 +138,7 @@ It can be configured by indicating :
## 2. The Pybox Manager
The Pybox Manager allows you to simply create and incorporate new boxes running a Python script of your choice, new labels/stimulations and new Custom Settings for your python boxes into OpenVibe.
The Pybox Manager allows you to simply create and incorporate new boxes running a Python script of your choice, new labels/stimulations and new Custom Settings for your python boxes into OpenViBE.
To run it: `python pybox_manager.py`.
@@ -169,16 +151,16 @@ To do this, run the manager with the `-mode=developer` option.
The Box Manager looks like this:
> ![box_manager.png](Assets/Doc/box_manager.png)
>
> PyBox Manager.
![box_manager.png](Assets/Doc/box_manager.png)
PyBox Manager.
- New: Create a new box
- Duplicate: duplicates the currently selected box.
- Reset Box: resets the selected box, cancels all changes made since the last compilation.
- Category : category in which the box will be stored in OV.
- Author : add the author's name in the box's references.
- Settings: Allows you to manage all the settings necessary to use the box. These can be types from Openvibe (String, Float etc.) or types created by yourself with the [Custom settings Manager](#custom-settings-manager)
- Settings: Allows you to manage all the settings necessary to use the box. These can be types from OpenViBE (String, Float etc.) or types created by yourself with the [Custom settings Manager](#custom-settings-manager)
- Inputs: Used to fill in the different inputs that your box will receive.
- Outputs : Used to fill in the different outputs that your box will send.
- Enable settings / inputs / outputs modifications : Allows you to prevent the users of your box from modifying these elements later on.
@@ -198,27 +180,27 @@ The DatasetCreator box we have created allows you to monitor the creation of a l
We allow the user to add labels (stimulations) via the `Stimulations/Labels Manager` interface present in the manager.
To do this, the manager must provide the name of the label, and a corresponding `.mp3` file, which will be played by the DatasetCreator.
> ![add_label.jpeg](Assets/Doc/add_label.jpeg)
>
> Add a label/stimulation to OpenViBE.
![add_label.jpeg](Assets/Doc/add_label.jpeg)
Add a label/stimulation to OpenViBE.
### Custom Settings Manager
The `Custom Settings Manager` allows you to create or delete special types of settings, as well as possible values for these settings, according to your needs.
This is especially useful to allow easy use on OpenVibe using a drop-down list. For example, if you want to be able to choose one algorithm among several, directly in your OpenVibe box configuration, you just have to create this new type as well as the associated values via the manager as shown in the following illustration.
This is especially useful to allow easy use on OpenViBE using a drop-down list. For example, if you want to be able to choose one algorithm among several, directly in your OpenViBE box configuration, you just have to create this new type as well as the associated values via the manager as shown in the following illustration.
To be able to use them with the manager when defining the parameters of a box, you have to launch the manager with the option `mode=developer`.
> ![manage_custom_settings.png](Assets/Doc/manage_custom_settings.png)
>
> Add/Remove/Manage Custom Settings.
![manage_custom_settings.png](Assets/Doc/manage_custom_settings.png)
Result in OpenVibe :
Add/Remove/Manage Custom Settings.
> ![classifiers.png](Assets/Doc/classifiers.png)
>
> Example with a new type 'classifier'.
Result in OpenViBE :
![classifiers.png](Assets/Doc/classifiers.png)
Example with a new type 'classifier'.
## 3. Internal Functioning and Details
@@ -241,17 +223,17 @@ The first mode (`ov-mode`) corresponds to the classic OpenViBE reading mode: the
For example:
> ![ov-mode.jpeg](Assets/Doc/ov-mode.jpeg)
>
> **Figure 1** - ov-mode
![ov-mode.jpeg](Assets/Doc/ov-mode.jpeg)
**Figure 1** - ov-mode
The second mode (`poly-mode`) consists in considering as many files as there are classes, i.e. one .csv file per class. To read all these files, the box then needs to have at least as many StreamedMatrix inputs as there are different classes. To use this mode, you just have to create only StreamedMatrix inputs.
(Often, this mode requires a `label` parameter in which to fill in the labels of our different classes in the form: `my label1, my label2, my label3`).
For example:
> ![poly-mode.jpeg](Assets/Doc/poly-mode.jpeg)
> **Figure 2** - poly-mode
![poly-mode.jpeg](Assets/Doc/poly-mode.jpeg)
**Figure 2** - poly-mode
Thus, these two reading modes are transparent for the user and allow him to operate the `PolyBoxes` either with a single file containing all the actions, or with several files: one per action.
The user doesn't need to indicate anything for the box to choose the right behavior to adopt, the box chooses its behavior according to its inputs.