Programming Reference:Filter Chain

From BCI2000 Wiki
Jump to navigation Jump to search

The Filter Chain

As noted in the discussion of the GenericFilter::Process function, all GenericFilter descendants inside a BCI2000 module form a chain of filters. Each filter's output forms the input of the subsequent filter.

In recent versions of BCI2000, it is possible to split up a chain into parallel subchains, and join them together at the end. Each subchain may again be split up, allowing for complex topologies of filters. For more information about how to split up a filter chain, see Programming Reference:ParallelCombination.

For each module, the filter chain is documented in its own FilterChain parameter, which is located in the System/Configuration section.

Filter Instantiation

Creating instances of all filter classes inside a module, and building the filter chain, is handled by the framework. However, it needs a hint to determine the sequence in which filters are to be arranged. In general, this hint consists of a single statement placed inside your filter's .cpp file:

RegisterFilter( MyFilter, 2.C );

The first argument to this statement is the class name of your filter; the second argument is a string value (given without quotes) that determines the relative position of your filter in the filter chain. This is done by applying the simple rule that the filter positions in the chain match the alphanumeric sorting order of the associated postion strings of the filters. This scheme allows you to place an additional filter between existing ones without changing the position strings of the existing filters.

As a rule, use position strings beginning with

  • 1. for filters that go into source modules,
  • 2. for filters from signal processing modules,
  • 3. for filters from application modules.

Signal Processing Filter Instantiation

In principle, the above scheme allows to you add filters to a module's filter chain without modification to the existing source code, simply by adding a .cpp file with a RegisterFilter statement to the project. However for Signal Processing modules, it is more desirable to have an explicit representation of the entire filter chain centralized in one place. So, for each individual Signal Processing module there is one file PipeDefinition.cpp that defines the filter chain as a sequence of Filter statements (see Programming Tutorial:Implementing a Signal Processing Filter for an example). In other modules, filters' default position will be suitable in general. Still, you may add a PipeDefinition.cpp with a sequence of Filter statements to the module. In this case, positions defined in PipeDefinition.cpp will take precedence over the filters' default positions.

Recreating Filter Chains Offline

The BCI2000 command-line tools can be used to recreate a filter-chain offline, from a system command-line. The Matlab function bci2000chain, part of BCI2000's suite of Matlab tools, provides a convenient interface to this from within Matlab.

The BCI2000Analysis program allows graphical editing of complex filter graphs, running data through them offline, as well as exporting them as a PipeDefinition.cpp file for use in a Signal Processing module.