User Reference:MatlabFilter: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
(moved text over from matlab to matlabfilter)
 
(11 intermediate revisions by 3 users not shown)
Line 6: Line 6:


The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the [[User_Reference:Operator_Module|Operator]] and can be modified there.
The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the [[User_Reference:Operator_Module|Operator]] and can be modified there.
The Matlab filter recognizes <tt>--MatlabWD</tt> command line option, which allows to set Matlab's working directory at startup, as in
MatlabSignalProcessing --MatlabWD="C:\Documents and Settings\bill\bcimatlab"


==States==
==States==
Line 11: Line 14:
The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.  
The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.  


==Detailled explanation==
==Detailed explanation==


The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.
The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.


Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has openend. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do
Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has opened. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do


   % show the variables
   % show the variables
Line 26: Line 29:
   while(1); plot(bci_InSignal(1,:)); pause(0.01); end
   while(1); plot(bci_InSignal(1,:)); pause(0.01); end


If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being openend by Matlab, the engine is blocked , which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.  
If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being opened by Matlab, the engine is blocked, which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.  


To get the above example to run correctly, you will have to open the figure /prior/ to starting BCI2000 by typing <tt>figure</tt> (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.  
To get the above example to run correctly, you will have to open the figure ''prior'' to starting BCI2000 by typing <tt>figure</tt> (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.  


However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:  
However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:  
Line 34: Line 37:
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]
* [[Programming_Tutorial:Implementing_another_Matlab-based_Filter|adaptive spatial filtering using a beamformer, power computation and normalization]]


A detailled description of how to implement your own signal processing functions in Matlab can be found in the [[Programming_Reference:Matlab|Programming reference for the Matlab filter]].
A detailed description of how to implement your own signal processing functions in Matlab can be found in the [[Programming_Reference:MatlabFilter|Programming reference for the Matlab filter]].


==Troubleshooting:==
==Troubleshooting:==
Line 44: Line 47:
Generally, the first option is recommended over the second one.
Generally, the first option is recommended over the second one.


===There is no Matlab engine started up===
===Problems with starting up the MatlabEngine===
Execute<br /><code>matlab /regserver</code><br />from the command line when logged in with administrative privileges.
For using the MatlabEngine on Windows systems, you need to make sure that
*the processor architecture (32 or 64 bit) of the installed version of Matlab matches that of the BCI2000 module,
*Matlab can be executed from the command line by running "matlab.exe".
In case of multiple concurrently installed versions of Matlab, the MatlabFilter will always connect to the one that starts up when executing "matlab" from a command prompt.
Also, it may help to execute<br /><code>matlab /regserver</code><br />from the command line under the account that is going to use the MatlabFilter.


==See also==
==See also==
[[Programming_Reference:MatlabFilter]],
[[Contributions:FieldTripBuffer]]
[[Contributions:FieldTripBuffer]]


[[Category:Filters]][[Category:Signal Processing]][[Category:Matlab]][[Category:Development]]
[[Category:Filters]][[Category:Signal Processing]][[Category:Matlab]][[Category:Development]]

Revision as of 14:35, 27 April 2018

Synopsis

The Matlab filter implements an interface between BCI2000 and a standalone Matlab engine. It allows you to implement and/or use Matlab functions for filtering data within the BCI2000 pipeline.

Parameters

The Matlab filter does not have a set of default parameters that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the parameters. After initialization, these parameters are displayed in the Operator and can be modified there.

The Matlab filter recognizes --MatlabWD command line option, which allows to set Matlab's working directory at startup, as in

MatlabSignalProcessing --MatlabWD="C:\Documents and Settings\bill\bcimatlab"

States

The Matlab filter does not have a set of default states that it uses. Instead, the user-supplied Matlab functions that are executed by the Matlab filter specify the states.

Detailed explanation

The Matlab filter does not implement any algorithms itself, but instead allows you to implement the algorithms of your choice in Matlab.

Once BCI2000 is running with the Matlab filter, you will see that a very simple Matlab command line window has opened. In that command line window you can type commands that show you the variables that BCI2000 communicates to the Matlab engine. For example, you can do

 % show the variables
 whos
 
 % plot the first channel of the data (see below)
 plot(bci_InSignal(1,:))
 
 % plot the first channel of the data and continuously update the plot (see below)
 while(1); plot(bci_InSignal(1,:)); pause(0.01); end

If you try these examples above like this, you will notice that Matlab takes quite a considerable amount of time to open a new figure. While the figure is being opened by Matlab, the engine is blocked, which causes the MatlabFilter to fail writing new data to the engine. Hence the MatlabFilter will return an error and you will have to restart BCI2000. The reason is that the Matlab engine gives you access through the command window, but that the Matlab engine is not capable of executing the commands that it receives from BCI2000 and the commands that it receives from you through the command window simultaneously.

To get the above example to run correctly, you will have to open the figure prior to starting BCI2000 by typing figure (this will open an empty figure). Subsequently, once BCI2000 is running, the content of the figure can be updated.

However, the above example already shows that the Matlab engine is not intended to be used concurrently from the BCI2000 MatlabFilter and from the command window. Instead of typing your own commands in the command window, you will have to give full control of command execution to the MatlabFilter to ensure that timing is controlled. The way that BCI2000 and Matlab interact is that each of the components of a standard filter is mapped onto a corresponding Matlab function. If the Matlab filter is running within BCI2000, it will call the Matlab engine and execute the required Matlab function. The easiest way of getting started with the Matlab filter is by using one of the provided programming tutorials:

A detailed description of how to implement your own signal processing functions in Matlab can be found in the Programming reference for the Matlab filter.

Troubleshooting:

Matlab doesn't find your functions

Make sure to

  • either set Matlab's working directory to the directory containing your functions, using the --MatlabWD command line option described above,
  • or add the respective directory to your Matlab path.

Generally, the first option is recommended over the second one.

Problems with starting up the MatlabEngine

For using the MatlabEngine on Windows systems, you need to make sure that

  • the processor architecture (32 or 64 bit) of the installed version of Matlab matches that of the BCI2000 module,
  • Matlab can be executed from the command line by running "matlab.exe".

In case of multiple concurrently installed versions of Matlab, the MatlabFilter will always connect to the one that starts up when executing "matlab" from a command prompt. Also, it may help to execute
matlab /regserver
from the command line under the account that is going to use the MatlabFilter.

See also

Programming_Reference:MatlabFilter, Contributions:FieldTripBuffer