Programming Reference:MatlabFilter: Difference between revisions

From BCI2000 Wiki
Jump to navigation Jump to search
Line 44: Line 44:
and <tt>states</tt> return values. The strings constituting these cell arrays are [[Technical Reference:Parameter Definition|parameter]] and [[Technical Reference:State Definition|state definitions]].
and <tt>states</tt> return values. The strings constituting these cell arrays are [[Technical Reference:Parameter Definition|parameter]] and [[Technical Reference:State Definition|state definitions]].


Your added parameters will appear in the [[Technical Reference:Operator Module|operator module's]] parameter configuration dialog.
Your added parameters will appear in the [[Technical Reference:Operator Module|operator module's]] parameter configuration dialog. Your parameter definition's section name will be used to direct its position in the configuration dialog's register cards:
MyFilter int MyParam= 2 0 0 2 // ...
will display the ''MyParam'' parameter on separate register card named ''MyFilter''.
Filtering:MyFilter int MyParam= 2 0 0 2 // ...
will display the parameter on the ''Filtering'' register card, inside a group called ''MyFilter''.


==Signal Format==
==Signal Format==

Revision as of 10:22, 30 November 2007

The MatlabFilter calls the Matlab engine to act upon signals, parameters, and states. It provides the full BCI2000 filter interface to a Matlab filter implementation.

Filter Interface

For each BCI2000 filter member function, there is a corresponding Matlab function as follows:

GenericFilter member      Matlab function syntax
====================      ======================
Constructor               [parameters, states] = bci_Construct
Destructor                bci_Destruct
Preflight                 out_signal_dim = bci_Preflight( in_signal_dim )
Initialize                bci_Initialize( in_signal_dim, out_signal_dim )
Process                   out_signal = bci_Process( in_signal )
StartRun                  bci_StartRun
StopRun                   bci_StopRun
Resting                   bci_Resting
Halt                      bci_Halt

Existence of the above-listed Matlab functions is not mandatory. The MatlabFilter uses the Matlab exist command to determine whether a given function is available, and will not call the Matlab engine when this is not the case. If either of the bci_Preflight, bci_Initialize, or bci_Process functions is not available, a warning will be displayed to the user.

Accessing Parameters and States

Parameters and states are accessible via global Matlab structs called bci_Parameters and bci_States. In Matlab, write

 global bci_Parameters bci_States;
 my_sampling_rate = bci_Parameters.SamplingRate;

Parameters may be changed from inside the bci_StopRun and bci_Resting scripts, and will automatically be propagated to the other modules. State values may be modified from the bci_Process function.

Declaring Parameters and States

To add parameters and states to the BCI2000 list of states, the bci_Construct function may return non-empty cell arrays of strings in its parameters and states return values. The strings constituting these cell arrays are parameter and state definitions.

Your added parameters will appear in the operator module's parameter configuration dialog. Your parameter definition's section name will be used to direct its position in the configuration dialog's register cards:

MyFilter int MyParam= 2 0 0 2 // ...

will display the MyParam parameter on separate register card named MyFilter.

Filtering:MyFilter int MyParam= 2 0 0 2 // ...

will display the parameter on the Filtering register card, inside a group called MyFilter.

Signal Format

BCI2000 signals are mapped to Matlab matrices with channel index first, and sample (element) index second. Signal dimension arguments of bci_Preflight and bci_Initialize are vectors of integers (1x2 matrices) as in [n_channels n_elements].

Error Reporting

To report errors from Matlab functions, use Matlab's error command. Your error messages will be displayed to the user from the operator module.

Combining with BCI2000 Signal Processing Filters

In the BCI2000 binary distribution, the MatlabFilter is shipped inside the MatlabSignalProcessing executable. There, the signal processing chain consists of the SpatialFilter and the MatlabFilter. However, by editing src/core/SignalProcessing/Matlab/PipeDefinition.cpp, you may add as many signal processing filters as you wish. (See Programming Reference:Filter Chain for information about defining a filter chain.)

This modification requires access to the BCI2000 source code. You will need to rebuild the MatlabSignalProcessing executable.

Troubleshooting

  • Make sure your script directory is part of the Matlab search path. Example scripts are located inside prog/matlab.
  • If no Matlab instance opens up, execute
matlab /regserver

from the command line when logged in with administrative privileges.

  • If you get linker errors after editing PipeDefinition.cpp, make sure that all filters' cpp files are part of the MatlabSignalProcessing project.

See also

Technical Reference:Core Modules#Signal Processing Module, Technical Reference:Parameter Definition, Technical Reference:State Definition, Programming Reference:GenericFilter Class, Programming Reference:Filter Chain