Tutorial : Using Python with OpenViBE

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

Introduction

We provide with OpenViBE a box capable of executing Python code. The Python Scripting box is available under the category “Scripting“. This box can have as many inputs, outputs or settings as needed. By implementing 3 scripts for initialization, process and uninitialization, user is able to process or produce any kind of data from/to OpenViBE.

The design of this box is strongly related to the OpenViBE design (box structure, stream structure, etc.). Interested reader should look at the developer documentation for more details about the OpenViBe architecture. It may come useful if you want to understand the architecture of the Python box.

One Python Interpreter is created for all the boxes in the same scenario.

This box relies on Python 2.7, however we do not provide Python directly with the OpenViBE packages. To compile and use the Python Scripting box you will have to download and install Python 2.7 on your own before. Note that Python is now a major package for many Linux distributions and thus will be directly included in such system. Please note that if you uninstall Python not correctly on Windows (or you move it somewhere), the box may find Python but then it would crash as Python won’t have a complete, accessible installation.

The Python Scripting box has been successfully tested in the following conditions:

Windows :

• Python 2.7.3 32bits on Windows 7 32 bits
• Python 2.7.3 32bits on Windows 7 64 bits

Please note that OpenViBE is compiled in 32 bits on windows, thus for proper link you must use a 32 bits version of Python on Windows.

You can install Python 2.7 wherever you want on your computer, OpenViBE should find it automatically.

Linux :

• Python 2.7.3 32bits (native package) on Ubuntu (latest LTS and latest version) 32bits
• Python 2.7.3 64bits (native package) on Ubuntu (latest LTS and latest version) 64bits
• Python 2.7.3 32bits (native package) on Fedora (17 & 16) 32bits
• Python 2.7.3 64bits (native package) on Fedora (17 & 16) 64bits

Note that on Fedora 17 and Ubuntu 12.04, the Python development libraries are not included with the operating system. The OpenViBE dependency installer (linux-install_dependencies) installs the package python-dev for you.

On Windows, if you ever uninstall or move Python manually (i.e. just by removing, renaming or moving the Python folder) some incorrect registry keys will be still available, and OpenViBE will find a ghost Python. This may cause the Designer to fail loading. If this case happens to you, please uninstall properly Python. You may also delete the python project DLL in the bin folder of OpenViBE (OpenViBE -plugins-python-dynamic.dll).

Compiling the ‘openvibe-plugins/python’ project

To compile the box in the python project, you must have a valid installation of Python 2.7 on your computer. CMake tries to find automatically the installation path by calling the script cmake-modules/FindthirdPartyPython.cmake.

When building the software, the process should find Python and all its libraries, as showed in the following build log example:

If the build process does not find a valid Python installation, the box won’t 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] File [../bin/OpenViBE-plugins-python-dynamic.dll] is not a plugin module (error: XXXXXXX)

Where the error message is related to a missing module (this message may vary from on distribution to another).

The Python Scripting box

The Python Scripting box is available in the Designer in the category Scripting.

Here is the different settings and how to set it correctly :

• 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.
• Script : The Python script file.

You can add as many input and output as you need. So far, 3 stream types are available : Streamed Matrix, Signal and Stimulations. You can also add new settings in the box, they will be available in the Python box object as well.

OpenViBE constructs an OVBox class object in Python with different attributes (inputs, outputs and settings fro example). This class has different predefined methods:

• initialize(self) : called once, when starting the scenario
• process(self) : called on each box clock tick
• uninitialize(self) : called once, when stopping the scenario

These 3 functions do nothing by default. The user script has to construct a new box class that inherits from OVBox, and rewrite these 3 functions so they actually do something. The Python box instance manipulated by OpenViBE during the execution is named ‘box’. This variable should be created by the user in his script (e.g. box = MyOVBox())

NB : other functions are defined, used internally by the Python Scripting box. Interested user may refer to the base Python file openvibe.py in share/openvibe-plugins/python for further details.

You can use more than one Python Scripting box in the same scenario, they will share the same Python interpreter but not the same box instance.

The OpenViBE-Python framework

The Python Scripting box relies on a set of Python classes to work. All these classes are defined in share/openvibe-plugins/python/openvibe.py.

This complete framework allows the user to manipulate streamed matrix, signal or stimulations streams, to process input and produce output.

Box

The OpenViBE box in Python is defined in the class OVBox. Here is the information you need to know about this class (for more information, please look at the implementation in openvibe.py) :

class OVBox(object) : the default box class
> .input   : list - the list of input buffers in which chunks will be added by openViBE during the execution.
> .output  : list -  the list of output buffers in which chunks will be added by the user script during execution.
> .setting : dict - The dictionary of settings (dict-key is the setting name, dict-value is the setting value)
> .var     : dict - A personal dictionary available for the user. Default is empty.

Methods 
> getClock()       : return the box clock frequency as defined by the user in the box settings.
> getCurrentTime() : returns the current OpenViBE time in seconds.
                     This value is automatically updated by the OpenViBE box every time is is called.
> initialize()     : dummy method 
> process()        : dummy method
> uninitialize()   : dummy method

You must define a new Box class that inherits from OVBox, and implement in it your version of the 3 functions initialize, process and uninitialize.

Chunk

Every block of data received or send by this box (headers, buffers and end), inherits from the basic class OVChunk:

class OVChunk(object) : a generic chunk, a dummy container for any kind of data.
 > .startTime : float - Start time of this data block
 > .endTime   : float - End time of this data block

Methods
> OVChunk(startTime, endTime) : constructor

Streamed Matrix

We specialize the OVChunk class to handle Streamed Matrix stream : we need a header, with the matrix structure information, a buffer containing the matrix values, and an end to notify end-of-stream.

class OVStreamedMatrixHeader(OVChunk) : the header chunk for the streamed matrix stream
 > .dimensionSizes : list - Sizes of the dimensions in the matrix
 > .dimensionLabel : list - Names of the dimensions in the matrix

Methods
> OVStreamedMatrixHeader(startTime, endTime, dimensionSizes, dimensionLabels) : constructor
> int getDimensionCount()     : returns the number of dimensions of the matrix
> int getBufferElementCount() : returns the number of elements in the matrix (i.e. product of every dimension sizes)

class OVStreamedMatrixBuffer(OVChunk, list) : the buffer chunk for the streamed matrix stream

Methods
> OVStreamedMatrixBuffer(startTime, endTime, bufferElements) : constructor.

class OVStreamedMatrixEnd(OVChunk) : the end chunk for the streamed matrix stream
> this class has no specific behavior, as the end buffer is only a simple notification

Signal

The signal stream is a specialization of the streamed matrix stream. It adds the sampling rate information.

class OVSignalHeader(OVStreamedMatrixHeader) : the header chyunk for the signal stream
> .samplingRate : int - Signal sampling frequency

Methods
OVSignalHeader(startTime, endTime, dimensionSizes, dimensionLabels, samplingRate) : constructor

class OVSignalBuffer(OVStreamedMatrixBuffer) : the buffer chunk of a signal stream
> this class has no specific behavior. Signal buffers are regular Streamed Matrix buffers.

class OVSignalEnd(OVChunk) : the end chunk of a signal stream
> this class has no specific behavior, as the end buffer is only a simple notification

Stimulation

Stimulation stream needs again a header and an end to notify start and end-of-stream. In this case the buffers are Stimulation Sets which contain Stimulation objects.

class OVStimulation(object) : a stimulation object
> .identifier : int   - Stimulation identifier, as in OpenViBE
> .date       : float - Stimulation date in seconds
> .duration   : float - Stimulation duration in seconds

Methods
OVStimulation(identifier, date, duration) : constructor

class OVStimulationHeader(OVChunk) : the header chunk for the stimulation stream
> this class has no specific behavior, as the stimulation header has no particular information.

class OVStimulationSet(OVChunk, list) : the buffer chunk of the stimulation stream

Methods
> OVStimulationSet(startTime, endTime) : constructor (empty set)
> append(stimulation) : append the stimulation in the list.
                        If the item is not an OVStimulation, this method will raise an exception.

class OVStimulationEnd(OVChunk) : the end chunk of a stimulation stream
> this class has no specific behavior, as the end buffer is only a simple notification

Tutorial 1 : Signal average

In this tutorial we will simply filter a signal stream to output one channel : the average of every channel. Please make sure you have installed the numpy package for Python as we will use numpy functions to simplify the scripts.

This box will have one input (signal) and one output (signal).

Open the folder share/openvibe-scenarios/box-tutorials/python/scripts. Open file python-signal-average.py.

See below for comments.

 # we use numpy to compute the mean of an array of values
 import numpy

 # let's define a new box class that inherits from OVBox
 class MyOVBox(OVBox):
    def __init__(self):
    OVBox.__init__(self)
    # we add a new member to save the signal header information we will receive
    self.signalHeader = None

    # The process method will be called by openvibe on every clock tick
    def process(self):
       # we iterate over all the input chunks in the input buffer
       for chunkIndex in range( len(self.input[0]) ):
          # if it's a header we save it and send the output header (same as input, except it has only one channel named 'Mean'
          if(type(self.input[0][chunkIndex]) == OVSignalHeader):
             self.signalHeader = self.input[0].pop()
             outputHeader = OVSignalHeader(
             self.signalHeader.startTime,
             self.signalHeader.endTime,
             [1, self.signalHeader.dimensionSizes[1]],
             ['Mean']+self.signalHeader.dimensionSizes[1]*[''],
             self.signalHeader.samplingRate)
             self.output[0].append(outputHeader)

          # if it's a buffer we pop it and put it in a numpy array at the right dimensions
          # We compute the mean and add the buffer in the box output buffer
          elif(type(self.input[0][chunkIndex]) == OVSignalBuffer):
             chunk = self.input[0].pop()
             numpyBuffer = numpy.array(chunk).reshape(tuple(self.signalHeader.dimensionSizes))
             numpyBuffer = numpyBuffer.mean(axis=0)
             chunk = OVSignalBuffer(chunk.startTime, chunk.endTime, numpyBuffer.tolist())
             self.output[0].append(chunk)
          # if it's a end-of-stream we just forward that information to the output
          elif(type(self.input[0][chunkIndex]) == OVSignalEnd):
             self.output[0].append(self.input[0].pop())

 # Finally, we notify openvibe that the box instance 'box' is now an instance of MyOVBox.
 # Don't forget that step !!
 box = MyOVBox()

As you can see, this class defines only the process function. We don’t need to add a specific behavior when initializing or uninitializing the box.

Tutorial 2 : Sinus Oscillator

In this tutorial we use Python to produce a sinusoidal signal. This script will use Numpy.

The Python box must be configured with 1 output (signal) and 3 new settings (integers).

User can set the number of channel, the sampling frequency and the sample count per epoch.

Open file python-sinus-oscillator.py.

import numpy

class MyOVBox(OVBox):
   def __init__(self):
      OVBox.__init__(self)
      self.channelCount = 0
      self.samplingFrequency = 0
      self.epochSampleCount = 0
      self.startTime = 0.
      self.endTime = 0.
      self.dimensionSizes = list()
      self.dimensionLabels = list()
      self.timeBuffer = list()
      self.signalBuffer = None
      self.signalHeader = None

   # this time we also re-define the initialize method to directly prepare the header and the first data chunk
   def initialize(self):
      # settings are retrieved in the dictionary
      self.channelCount = int(self.setting['Channel count'])
      self.samplingFrequency = int(self.setting['Sampling frequency'])
      self.epochSampleCount = int(self.setting['Generated epoch sample count'])

      #creation of the signal header
      for i in range(self.channelCount):
         self.dimensionLabels.append( 'Sinus'+str(i) )
      self.dimensionLabels += self.epochSampleCount*['']
      self.dimensionSizes = [self.channelCount, self.epochSampleCount]
      self.signalHeader = OVSignalHeader(0., 0., self.dimensionSizes, self.dimensionLabels, self.samplingFrequency)
      self.output[0].append(self.signalHeader)

      #creation of the first signal chunk
      self.endTime = 1.*self.epochSampleCount/self.samplingFrequency
      self.signalBuffer = numpy.zeros((self.channelCount, self.epochSampleCount))
      self.updateTimeBuffer()
      self.updateSignalBuffer()

   def updateStartTime(self):
      self.startTime += 1.*self.epochSampleCount/self.samplingFrequency

   def updateEndTime(self):
      self.endTime = float(self.startTime + 1.*self.epochSampleCount/self.samplingFrequency)

   def updateTimeBuffer(self):
      self.timeBuffer = numpy.arange(self.startTime, self.endTime, 1./self.samplingFrequency)

   def updateSignalBuffer(self):
      for rowIndex, row in enumerate(self.signalBuffer):
         self.signalBuffer[rowIndex,:] = 100.*numpy.sin( 2.*numpy.pi*(rowIndex+1.)*self.timeBuffer )

   def sendSignalBufferToOpenvibe(self):
      start = self.timeBuffer[0]
      end = self.timeBuffer[-1] + 1./self.samplingFrequency
      bufferElements = self.signalBuffer.reshape(self.channelCount*self.epochSampleCount).tolist()
      self.output[0].append( OVSignalBuffer(start, end, bufferElements) )

   # the process is straightforward
   def process(self):
      start = self.timeBuffer[0]
      end = self.timeBuffer[-1]
      if self.getCurrentTime() >= end:
         self.sendSignalBufferToOpenvibe()
         self.updateStartTime()
         self.updateEndTime()
         self.updateTimeBuffer()
         self.updateSignalBuffer()

   # this time we also re-define the uninitialize method to output the end chunk.
   def uninitialize(self):
      end = self.timeBuffer[-1]
      self.output[0].append(OVSignalEnd(end, end))            

box = MyOVBox()

Tutorial 3 : Clock Stimulator

In this last example we produce a stimulation on every clock tick.

The box uses one output (stimulation) and one setting (the stimulation identifier to send).

Open file python-clock-stimulator.py.

# We construct a box instance that inherits from the basic OVBox class
class MyOVBox(OVBox):
    # the constructor creates the box and initializes object variables
   def __init__(self):
      OVBox.__init__(self)
      self.stimLabel = None
      self.stimCode = None

   # the initialize method reads settings and outputs the first header
   def initialize(self):
                # the stim label is taken from the box setting
      self.stimLabel = self.setting['Stimulation']
      # we get the corresponding code using the OpenViBE_stimulation dictionnary
      self.stimCode = OpenViBE_stimulation[self.stimLabel]
      # we append to the box output a stimulation header. This is just a header, dates are 0.
      self.output[0].append(OVStimulationHeader(0., 0.))

   def process(self):
                # During each process call we produce a stimulation
                # A stimulation set is a chunk which starts at current time and end time is the time step between two calls
      stimSet = OVStimulationSet(self.getCurrentTime(), self.getCurrentTime()+1./self.getClock())
                # the date of the stimulation is simply the current openvibe time when calling the box process
      stimSet.append(OVStimulation(self.stimCode, self.getCurrentTime(), 0.))
      self.output[0].append(stimSet)

   def uninitialize(self):
                # we send a stream end.
      end = self.getCurrentTime()
      self.output[0].append(OVStimulationEnd(end, end))            

box = MyOVBox()

Execution

The three scripts are used in the example scenario python-sinus-oscillator in share/openvibe-scenarios/box-tutorials/python/scenarios.

The “sinus oscillator” generates a 4 channel sinusoid signal, which is filtered by the “mean” script. The clock stimulator outputs the stimulation Label_00 every second.