Programming Reference:ComplexVisualizationDemo Signal Processing

From BCI2000 Wiki
Revision as of 16:21, 8 February 2019 by Mellinger (talk | contribs) (VisualizationObject::asyncUpdate())
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search




The ComplexVisualizationDemo signal processing module demonstrates how to send a large number of visualizations with arbitrary pixel content to the operator module. Two rendering methods are provided: Native Qt QPainter-based rendering, and BCI2000's own GraphDisplay based rendering.


The ComplexVisualizationDemoFilter signal processing filter derives from GenericFilter.


The ComplexVisualizationDemoFilter computes pairwise determination coefficients (squared correlation, r^2 values) between its input channels. Determination coefficients are visualized in form of pie charts, and pie charts are sent to the operator module as bitmap visualization data.

Operator visualization windows have no frames or title bars, and are arranged in form of a lower triangular matrix, with each window appearing at the place of its associated correlation matrix element: ComplexVisualizationDemo.PNG


Each visualization window is implemented as a VisualizationObject that contains a BitmapVisualization object, a WorkerThread object, and a Computation object. Whenever a new block of data arrives, computation is done for the individual window's pair of channels in the main thread. Then, visualization bitmap data are produced and sent to the operator module inside the worker thread, to avoid blocking the main thread. Inside the worker thread, the BitmapVisualization's SendDifferenceFrame() function is called to update the visualization display in the operator module.

Declaration of internal variables

The code example uses a pointer to an internal private struct to hide implementation details from the outer header file of the filter class (PIMPL idiom).

A VisualizationObject class is declared that contains all members necessary to draw to an individual visualization window, and a WorkerThread instance that runs code to send visualization data to the operator in a separate thread in order to avoid interference with the timing of the main BCI2000 thread.

struct ComplexVisualizationDemoFilter::Private
  RGBColor mBackground;
  int mHeight, mWidth, mDecimation;
  int mDecimationCounter;

  class VisualizationObject;
  std::vector<VisualizationObject*> mVisualizations;

  ~Private() { destroyVisualizations(); }
  // Creates visualization objects for pairs of channels.
  void createVisualizations(const SignalProperties&, int maxWindows);
  // Destroys all visualization objects.
  void destroyVisualizations();
  // Asynchronously sets visualizations to their initial state.
  void resetVisualizations();
  // Computes data values, and asynchronously updates visualization bitmaps.
  void updateVisualizations(const GenericSignal&);
  // Waits for asynchronous activity in all visualizations to terminate.
  void waitForVisualizations();

  class VisualizationObject
    VisualizationObject(const Private*, const std::string& visID);
    void setTitle(const std::string&, const std::string& info = "");
    void setPosition(const GUI::Rect&);
    void reset();
    void update(const GenericSignal&);
    void wait();

    struct Computation
      int inputCh1, inputCh2;
      double result;
      // run() is called whenever a new signal arrives.
      void run(const GenericSignal&);
    } mComputation;

    void asyncReset();
    void asyncUpdate();

    MemberCall<void(VisualizationObject*)> mCallAsyncReset;
    MemberCall<void(VisualizationObject*)> mCallAsyncUpdate;

    const Private* p;
    WorkerThread mWorker;
    BitmapVisualization mVis;
    std::string mTitle, mInfo;
    GUI::Rect mPosition;
    GUI::GraphDisplay mImage;
    PieShape* mpShape;
    TextField* mpValueField, *mpInfoField;

VisualizationObject::reset() and VisualizationObject::update()

These functions run VisualizationObject::asyncReset() and VisualizationObject::asyncUpdate() inside the object's worker thread in order to avoid interference with timing of the main BCI2000 thread.

    throw bcierr << "cannot initialize: worker is busy or dead";

ComplexVisualizationDemoFilter::Private::VisualizationObject::update(const GenericSignal& Input)
  mWorker.Run(mCallAsyncUpdate); // will fail if worker still busy


This function resets the visualization window's position and size before sending an empty reference frame to the operator.

  // reset position and size
  mVis.Send(CfgID::Left, mPosition.left);
  mVis.Send(CfgID::Width, mPosition.Width());
  mVis.Send(CfgID::Height, mPosition.Height());
  mVis.Send(CfgID::WindowTitle, mTitle);
  // setting CfgID::WindowFrame to false will hide the window's title bar and frame
  mVis.Send(CfgID::WindowFrame, false);
  mVis.Send(CfgID::Visible, true);

  // paint an empty image


The asyncUpdate() function gets the computation result from the computation object, and draws a pie shape with an angle that corresponds to the result. It then sends the resulting image to the operator module as a difference frame.

  double value = mComputation.result;

  std::ostringstream oss;
  oss << std::setprecision(2) << std::fixed << value;

  // Draw a pie shape that is full angle when value == 1, and that reduces to a line when value == 1.
  float angle = 270;
  if(value == value) // not NaN
    angle = 360 * value;
  mpShape->SetStartAngle(180 - angle/2).SetEndAngle(180 + angle/2);
  // render the image
  // send bitmap data to operator

Process() function

The Process() function handles the test of the decimation counter, and calls updateVisualizations() if necessary. updateVisualizations(), in turn, calls VisualizationObject::update() for each visualization object contained in mVisualizations.

void ComplexVisualizationDemoFilter::Process(
  const GenericSignal& Input,
        GenericSignal& Output)
  Output = Input;
  if(p->mDecimationCounter == 0)
  ++p->mDecimationCounter %= p->mDecimation;

StartRun() and StopRun()

These reset the decimation counter, and indirectly call VisualizationObject::reset(). The waitForVisualizations() function in StartRun() waits for all WorkerThread tasks to complete before actually re-starting visualization activity.

void ComplexVisualizationDemoFilter::StartRun()
  p->mDecimationCounter = 0;

void ComplexVisualizationDemoFilter::StopRun()

BCI2000 GraphDisplay vs. QPainter rendering

The code presented here is using the BCI2000 GraphDisplay class.

GraphDisplay is a layer of abstraction that allows to render shapes and text objects into a normalized coordinate system. Code that uses GraphDisplay is most likely to survive breaking changes in the drawing backend (currently Qt) and BCI2000 dependencies.

In contrast, QPainter-based rendering provides access to more complex drawing functions but suffers from a limitation in Qt which makes text rendering impossible outside the main GUI thread.

In the ComplexVisualizationDemo source code, QPainter-based rendering is available through a compiler switch.



Native image width in pixels.


Native image height in pixels.


The images' background color, in hexadecimal notation.


A positive integer that indicates how often images are refreshed. 1 means every refresh on every signal packet.


The maximum number of visualization windows created, or 0 for any number of windows.

See also

Programming Reference:GraphDisplay Class, Programming Reference:GenericVisualization Class, Programming Reference:VisualizationDemo Signal Processing