Visualizer Plugins#

Visualizers are Processor Plugins that include a canvas for displaying data.#
Type	`Plugin::Type::PROCESSOR`
Base Classes	`GenericProcessor`, `VisualizerEditor`, `Visualizer`
Template	open-ephys-plugins/visualizer-plugin-template

Overview#

All plugins for the Open Ephys GUI have space for parameter editors and small visualizations inside of their “editor,” which lives inside the Editor Viewport along the bottom of the main GUI window. Because there is a limited amount of screen real estate inside the editor, plugin developers can choose to display additional information inside a “canvas” that lives inside the GUI’s Viewport, or optionally inside a separate window. This makes it possible to create rich visualizations of multichannel data (such as the LFP Viewer and Spike Viewer), or to provide a more comprehensive interface for adjusting parameters (such as in the Neuropixels PXI or Crossing Detector plugins).

Any Processor Plugins or Data Threads can become Visualizer plugins simply by deriving their editors from the VisualizerEditor class, rather than the GenericEditor class. A Visualizer Editor contains two buttons in the upper right that specify whether the Visualizer canvas should appear in a tab inside the GUI’s Viewport or in a separate window. The Visualizer Editor will automatically track the state of these buttons, and will ensure that the Visualizer is re-loaded in the same location each time.

Visualizer Editor methods#

The Visualizer Editor constructor has two more parameters than the standard Generic Editor constructor:

VisualizerEditor(GenericProcessor *processor, String tabText, int desiredWidth)#

Constructor for a Visualizer Editor.

Parameters:

processor – Pointer to the GenericProcessor associated with this editor.
tabText – The text that will appear in the Visualizer tab within the GUI’s Viewport (or the title of the Visualizer window).
desiredWidth – The width (in pixels) of this editor. If the editor needs to adjust its size at a later time, it simply needs to change the value of its desiredWidth member.

A Visualizer Editor must also implement the following method to specify how its Visualizer should be created:

Visualizer *createNewCanvas()#

Returns:: A pointer to a Visualizer object.

The following methods are needed to start and stop Visualizer animation callbacks. This is usually done when starting and stopping acquisition, but they can also be called at other times as needed.

void enable()#: Calls Visualizer’s beginAnimation() method, which starts the animation timer.

void disable()#: Calls Visualizer’s endAnimation() method, which stops the animation timer.

Visualizer methods#

A Visualizer is simply a Juce Component that includes an animation timer. Anything that can be done inside a Component can be done inside a Visualizer.

All Visualizers must implement three pure virtual methods:

void refresh()#: Called on each animation cycle; the Visualizer should make sure all the relevant components are re-drawn inside this method. This is used instead of Juce’s repaint() to avoid re-painting sub-components that don’t need to be updated. To modify the animation refresh rate, a Visualizer should change the value of its refreshRate member.

void refreshState()#: Called once when the Visualizer’s tab becomes visible.

void update()#: Called when the signal chain is modified, to allow the Visualizer to update its internal settings. Note that Visualizer settings will not be propagated to downstream plugins.

In addition, a Visualizer should override the following Juce Component methods to specify its background and layout:

void paint(Graphics &g)#: Draws the Visualizer background.

void resized()#: Updates boundaries of sub-components whenever the size of the Visualizer is changed.

Saving/loading settings#

If a Visualizer Editor contains parameter editors that do not inherit from the GUI’s built in ParameterEditor class, it must save and load its settings by overriding the following methods (note that these differ from what is used by the GenericEditor class):

void saveVisualizerEditorParameters(XmlElement *xml)#: Saves any custom parameters within a Visualizer Editor. Parameters should be added as attributes of the XmlElement that’s passed into this method.

void loadVisualizerEditorParameters(XmlElement *xml)#: Loads any custom parameters within a Visualizer Editor. Parameters are stored as attributes of the XmlElement that’s passed into this method.

To save and load custom parameters within the Visualizer itself, the following methods should be overridden:

void Visualizer::saveCustomParametersToXml(XmlElement *xml)#: Saves any custom parameters within a Visualizer. Parameters should be added as attributes of the XmlElement that’s passed into this method.

void Visualizer::loadCustomParametersFromXml(XmlElement *xml)#: Loads any custom parameters within a Visualizer. Parameters are stored as attributes of the XmlElement that’s passed into this method.

Interactive Plots#

Visualizers that display data can take advantage of the GUI’s InteractivePlot class to draw 2D charts.

The following methods define the behavior of an Interactive Plot:

void plot(std::vector<float> x, std::vector<float> y, Colour c = Colours::white, float width = 1.0f, float opacity = 1.0f, PlotType type = PlotType::LINE)#

Adds a plot element based on a vector of X and Y values.

Parameters:

x – A vector of locations along the X-axis.
y – A vector of locations along the Y-axis.
c – The color of the plot element.
width – The width of the line (in the case of a line plot), the width of the dots (in the case of a scatter plot), or the width of the bars (in the case of a bar plot).
opacity – The opacity of the plot element.
type – The type of plot element to draw (options are LINE, SCATTER, BAR, and FILLED)

void clear()#: Clears all elements from the plot.

void show()#: Draws all elements that have been added since the plot was cleared.

void title(String t)#

Adds a title to the plot.

Parameters:: t – The title text.

void xlabel(String label)#

Sets the x-axis label.

Parameters:: label – The x-axis label text.

void ylabel(String label)#

Parameters:: label – The y-axis label text.

void setInteractive(InteractivePlotMode mode)#

Set whether the plot can be panned and zoomed.

Parameters:: mode – Can be either ON or OFF

void showXAxis(bool state)#

Sets whether x-axis is visible.

Parameters:: state – true if the x-axis should be drawn.

void showYAxis(bool state)#

Sets whether y-axis is visible.

Parameters:: state – true if the y-axis should be drawn.

void showGrid(bool state)#

Sets whether plot grid is visible.

Parameters:: state – true if the grid should be drawn.

void setBackgroundColour(Colour c)#

Sets the background colour of the plot.

Parameters:: c – The background colour.

void setGridColour(Colour c)#

Sets the colour of the plot grid.

Parameters:: c – The grid colour.

void setAxisColour(Colour c)#

Sets the colour of the axes.

Parameters:: c – The axis colour.

void setRange(XYRange &range)#

Sets the range of both axes.

Parameters:: range – An XYRange object consisting of four values (x-min, x-max, y-min, and y-max).

void getRange(XYRange &range)#

Copies the current range values.

Parameters:: range – An XYRange object consisting of four values (x-min, x-max, y-min, and y-max).