Programming Reference:VisualizationContainerDemo Signal Processing

Location

src/contrib/SignalProcessing/VisualizationContainerDemo

Synopsis

The VisualizationContainerDemo signal processing module demonstrates how to maintain a number of visualization displays within a container window. It is similar to Programming Reference:ComplexVisualizationDemo Signal Processing but does not render graphics itself; rather, it maintains a group of visualization windows within a container window, and sends data to these.

Inheritance

The VisualizationContainerDemo signal processing filter derives from GenericFilter.

Function

The VisualizationContainerDemo computes pairwise determination coefficients (squared correlation, $r^{2}$ values) between its input channels. Determination coefficients are sent to a group of visualizations in the Operator module.

Operator visualizations are contained in a parent window, and arranged in form of a triangular matrix, with each window appearing at the place of its associated correlation matrix element:

Implementation

Each visualization window is implemented as a VisualizationObject that contains a Visualization 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, the result is sent to the Operator window inside a GenericSignal object. As both computation effort and the amount of data is limited, and to keep the example code simple, no multithreading is involved in this demo. (For an example that involves multithreading, see Programming Reference:ComplexVisualizationDemo Signal Processing.

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 compute an $r^{2}$ value, and to send it to a visualization window.

struct VisualizationContainerDemoFilter::Private
{


  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();
  // Resets 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
  {
  public:
    VisualizationObject(const Private*, const std::string& visID);
    ~VisualizationObject();
    void setTitle(const std::string&, const std::string& info = "");
    void setPosition(int row, int col, int rowSpan = 1, int colSpan = 1);
    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;

  private:
    void asyncUpdate();

    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::update()`

This function runs VisualizationObject::asyncUpdate() inside the object's worker thread in order to avoid interference with timing of the main BCI2000 thread (pipeline thread).

void
ComplexVisualizationDemoFilter::Private::VisualizationObject::update(const GenericSignal& Input)
{
  mComputation.run(Input);
  mWorker.Run(mCallAsyncUpdate); // will fail silently if worker still busy
}

`VisualizationObject::reset()`

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

void
ComplexVisualizationDemoFilter::Private::VisualizationObject::reset()
{
  // place window into a container window named "CPLX" (will be created implicitly)
  mVis.Send(CfgID::PlacementVis, "CPLX");
  mVis.Send(CfgID::PlacementRow, mRow);
  mVis.Send(CfgID::PlacementCol, mCol);
  mVis.Send(CfgID::WindowFrame, false); // hide title
  mVis.Send(CfgID::Visible, true);

  // paint an empty image
  mpInfoField->SetText(mInfo);
  mpInfoField->SetVisible(true);
  mpValueField->SetVisible(false);
  mpShape->SetVisible(false);
  mImage.SetColor(p->mBackground);
  mImage.Paint();
  mVis.SendReferenceFrame(mImage.BitmapData());
  mpShape->SetVisible(true);
  mpValueField->SetVisible(true);
  mpInfoField->SetVisible(false);
}

`VisualizationObject::asyncUpdate()`

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.

void
ComplexVisualizationDemoFilter::Private::VisualizationObject::asyncUpdate()
{
  double value = mComputation.result;

  std::ostringstream oss;
  oss << std::setprecision(2) << std::fixed << value;
  mpValueField->SetText(oss.str());

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

`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->updateVisualizations(Input);
  ++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;
  p->waitForVisualizations();
  p->resetVisualizations();
}

void ComplexVisualizationDemoFilter::StopRun()
{
  p->waitForVisualizations();
  p->resetVisualizations();
}

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.

Parameters

VisImageWidth

Native image width in pixels.

VisImageHeight

Native image height in pixels.

VisImageBackground

The images' background color, in hexadecimal notation.

VisImageDecimation

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

VisMaxWindows

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