Technical Reference:Visualization Properties

From BCI2000 Wiki
Jump to navigation Jump to search

Visualization properties are properties bound to visualization windows.

They may be set using the SET VISPROPERTY or SET VISPROPERTIES scripting commands.

When in doubt about the data format expected by a certain property, you may look it up in the Operator program's human-readable Operator.ini file in the prog directory.

Currently, the following visualization properties are defined:

Window Properties

Top, Left, Width, Height (number)

Position and size of the visualization window on the virtual desktop.

WindowTitle (string)

The visualization window's title.

WindowFrame (boolean)

Whether to display the visualization window with a title bar, and a resizable window frame. If the window is embedded in a parent window (see PlacementVis), this property defines whether the window title is displayed above the window's content inside the container window.

FontSize (number)

The font size used within the visualization window.

Visible (boolean)

Whether the window is visible or not.

Memo Options

NumLines (number)

The number of lines in a visualization window of type "memo".

Inserting visualizations into a container window

PlacementVis (string)

Put visualization into a container window with given visualization ID of the desired container window. This is a property of the visualization to be placed.

To display a visualization again as an independent window after it has been placed into a container, send PlacementVis with an empty string.

PlacementRow, PlacementCol (number)

1-based indices of row and column within the container window.

PlacementHeight, PlacementWidth (number)

Number of rows/columns to extend within the container window.

PlacementMargin (number)

In the container window, the margin between matrix entries. NOTE: This is a property of the container window, not the visualization to be placed.

PlacementColor (string)

Color of the visible margin between matrix entries in the container window, in the form 0xRRGGBB. NOTE: This is a property of the container window, not the visualization to be placed.

WindowFrame (boolean)

For a visualization placed into a container window, this property determines whether the subwindow's title is displayed above its contents.

Graph Options

MinValue, MaxValue (number)

The minimum and maximum expected signal value in raw units (microvolts for signal windows). This value is used to determine the signal's default scaling.

MinValues, MaxValues (list of numbers)

May be used to specify MinValue and MaxValue settings individually for channels. The list is separated by white space, and enclosed in curly braces.

UserScaling

The binary logarithm of a scaling factor that is applied after min and max values. E.g., specify 1 to double the size of the displayed signal, and -1 to halve it. Defaults to 0.

The UserScaling value corresponds to the number of times the "Enlarge signal" menu entry is selected from the visualization's context menu. Reducing it by 1 corresponds to selecting the "Reduce signal" menu entry once.

If the ChannelUserScaling setting is used, UserScaling and ChannelUserScaling values will add up, e.g. if both are set to 1, final signal size will be 4 times as large as if both are set to 0.

NumSamples (number)

The number of samples displayed in the visualization window.

ChannelGroupSize (number)

The number of subsequent channels that share a common signal baseline.

GraphType (number)

Polyline (9) or Field2d (12). Polyline stands for the standard multi-channel signal view, while Field2d defines a two-dimensional field with color-encoded values.

ShowBaselines (boolean)

For a Polyline display, switches baselines on or off.

ShowNumericValues (boolean)

Whether to display the current value as a number in front of the graphic representation.

ShowStatusBar (boolean)

For a Polyline graph, whether to show a status bar at the bottom of the window. The status bar displays information about filtering (high pass, low pass, and notch filters).

ChannelColors (list of hex values)

For a Polyline display, defines the list of colors to be used for drawing signals. The list is enclosed in curly braces as in { 0xff0000, 0x00ff00, 0x0000ff }.

ChannelStyles (string)

For a Polyline display, a string containing characters to plot at sample points, '-' for line, '°' for empty dot, '*' for asterisk, etc. If the string contains fewer characters than there are channels to display, '-' is assumed for the remaining channels.

ValueColors (list of {number, string} pairs)

For a Field2d display, defines the colors used to plot signal values. The string has the form { [ <val1> 0xRRGGBB ] [ <val2> 0xRRGGBB ] ... } with rgb values ranging from 00 to FF.

AutoScale (boolean)

Select/deselect auto scale option.

FixedScale (boolean)

If true, user cannot adjust value scaling.

HPFilter, LPFilter, NotchFilter (string)

Apply a high pass, low pass, or notch filter to the displayed signal. This does not affect signal processing within the pipeline. To disable a filter, specify "off", to set the filter corner to a certain value, specify the the frequency with unit, e.g. "30Hz".

Units

SampleUnit (string)

The difference between two subsequent sample positions, given as a number followed by a unit, such as 1.4ms. This is used to display units on the x axis of the visualization window.

ChannelUnit (string)

If the channel dimension is a continuous variable, then this property gives the difference between two subsequent channels, as a number followed by unit, such as 2Hz. This is used to display units on the y axis of the visualization window, and currently only used with Field2d type graphs.

ValueUnit (string)

The value of one unit for the values displayed in a visualization window, such as 2muV. This property is used to display value units in Polyline type graphs.

ValueUnits (list of strings)

This property may be used to set different value units for channels. The list is of the form { 1muV 2mA 10mV }.

Label Lists

ChannelLabels (list of strings)

A list of strings specifying channel labels. Channel labels are displayed to the left of channel traces in Polyline graphs.

GroupLabels (list of strings)

A list of strings specifying a label for each channel group. Channel groups consist of a number of channels displayed on a single baseline.

Marker Lists

XAxisMarkers (list of {number,string} pairs)

A list of {position, label} pairs that define markers on the X axis.

The number specifies the marker's location in raw units; use the associated signal's ElementUnit property in order to convert from physical units to raw units.

The string may specify up to 4 marker properties, separated by a pipe character (|):

  • A textual label displayed at the marker's position below its axis,
  • a color name, or an RGB value in hexadecimal format, preceded with a hash character (#),
  • a line style specification in ASCII format, consisting of dot and minus characters,
  • a line width factor relative to the marker's tick width at the axis.

The following table lists some examples of valid marker definition strings:

""
A white marker which will consist of a mark at the marker's axis.
"Caption"
A white marker which will consist of a mark at the marker's axis, and a caption.
"|green"
A green marker which will consist of a mark at the marker's axis.
"|#00ff00"
A green marker which will consist of a mark at the marker's axis.
"|red|-"
A red marker which will consist of a mark at the marker's axis, and a vertical red line.
"Caption|yellow|-.|0.5"
A yellow marker which will consist of a mark at the marker's axis, a caption, and a vertical dash-dotted yellow line which is 0.5 units wide.

YAxisMarkers (list of {number,string} pairs)

A list of {position, label} pairs that define markers on the Y axis.

The number specifies the marker's location in raw units; use the associated signal's ValueUnit property in order to convert from physical units to raw units.

As for XAxisMarkers, the label string may be used to specify an extended format for a marker (see above).

Channel list and per-Channel Settings

ShowChannelList (boolean)

Shows/hides a graph visualization's channel list. The channel list may be used to apply user settings for individual channels.

ChannelsVisible (list of {string, number} pairs)

A list of {channel name, visible} pairs that define which channels are visible. The "visible" property is given as a number, with 0 for invisible, and 1 for visible.

Example: SET VISPROPERTY SRCD%3A.ChannelsVisible {Ch1 0 Ch2 1 Ch3 0}

ValueUnitsVisible (list of {string, number} pairs)

A list of {channel name, visible} pairs that define which channels have visible value units. The "visible" property is given as a number, with 0 for invisible, and 1 for visible.

ChannelUserScaling (list of {string, number} pairs)

A list of {channel name, scaling} pairs that define a channel's scaling as it may be adjusted by the user through the channel list's context menu. Scaling ranges from -4 to 4 and multiplies by a factor of 2 at each step, i.e. a scaling of 2 corresponds to a scaling factor of 4, and 0 corresponds to the default.

Each step in a ChannelUserScaling value corresponds to selecting the "Enlarge signal" or "Reduce signal" menu item from the channel's context menu once.

ChannelUserScaling and UserScaling values are additive, i.e. if both are set to 1, the final resize factor will be 4.

Miscellaneous

ShowXTicks (boolean)

Whether to display ticks on the x axis, and associated labels.

ShowYTicks (boolean)

Whether to display ticks on the y axis, and associated labels.

ShowSampleUnit (boolean)

Switches sample unit display on or off for graphs.

ShowChannelUnit (boolean)

Switches channel unit display on or off for Field2d graphs.

ShowValueUnit (boolean)

Switches value unit display on or off for Polyline graphs. If MinValue coincides with the baseline, the unit display is a labelled mark relative to the baseline, with the label describing the the distance to the baseline. If not, the unit display consists of a top an a bottom line, with a label in between that describes the distance between the two lines.

SampleOffset (number)

An offset, in raw units (i.e., samples), which to add to the displayed values on the X axis.

InvertedDisplay (boolean)

Switches between white-on-black and black-on-white display for Polyline graphs.

CustomColors (list of hex values)

The so-called "custom colors" (predefined or user-selected) colors in the color selector dialog that appears when selecting a channel's color. The list is enclosed in curly braces as in { 0xff0000, 0x00ff00, 0x0000ff }. Note that this setting has no effect on the display of channels, it merely exists to allow the user to have easy access to preferred colors in the color selector dialog.

See also

User Reference:Operator Module Scripting