2.4. TaurusQePlot - Taurus-Integrated 1D Plot Widget

2.4.1. Overview

TaurusQePlot is a 1D plot widget that bridges the QePlot canvas with the Taurus SCADA system. It connects to Taurus devices and attributes, receives live data through Taurus events, and plots 1D vector values as curves using the underlying QePlot infrastructure.

The widget uses multiple inheritance from both QePlot (the C++/Qt plot canvas) and TaurusBaseWidget (the Taurus data-binding base class). When a Taurus attribute fires an event, the internal controller extracts the numeric magnitude from the event value and calls QePlot.setNumpyNdArray() to update the plot curve.

The toolbar is shown automatically on construction. The widget is read-only: it displays data from Taurus but does not support writing values back.

TaurusQePlot widget (visually identical to QePlot)

2.4.1.1. Constructor

The constructor signature is

TaurusQePlot(parent: QWidget = None, designMode: bool = False)

Parameters:

• parent (QWidget, optional) – Parent widget.

• designMode (bool, default False) – Indicates whether the widget is instantiated within Qt Designer.

Example:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqeplot import TaurusQePlot

app = TaurusApplication()
plot = TaurusQePlot()
plot.model = "cii.oldb:/cut/demoservice/instance1/double-vector-sin"
plot.show()
app.exec_()

2.4.1.2. Inheritance Hierarchy

TaurusQePlot uses multiple inheritance, combining the QePlot canvas path with the Taurus data-binding path:

2.4.2. Qt Properties

TaurusQePlot defines four Qt properties with associated getter, setter, and resetter methods.

2.4.2.1. model

cut.wdglib.taurus.plot.taurusqeplot.model

The unique URI string (or comma-separated list of URIs) representing the Taurus model(s) the widget will read data from. Accepts a single Taurus string or a list of strings. When a string is passed it is split on commas and stripped automatically.

Setting model forces the widget to rebuild its internal controller.

Access functions:

• TaurusBaseWidget.getModel()

• setModel()

• TaurusBaseWidget.resetModel()

Example:

plot.model = "cii.oldb:/cut/demoservice/instance1/double-vector-sin"
plot.model = ["cii.oldb:/cut/demoservice/instance1/double-vector-sin", "cii.oldb:/cut/demoservice/instance1/double-vector-cos"]
plot.model = "cii.oldb:/cut/demoservice/instance1/double-vector-sin, cii.oldb:/cut/demoservice/instance1/double-vector-cos"

cut.wdglib.taurus.plot.taurusqeplot.setModel(m, key=MLIST) → None

Setter for the model property. Accepts a string, a list of strings, or a single Taurus model object. Resets the internal controller so the new model type is handled correctly.

Parameters:

• m – Model URI string, comma-separated string, or list of URIs.

• key – Model key (defaults to MLIST).

2.4.2.2. modelIndex

cut.wdglib.taurus.plot.taurusqeplot.modelIndex

The index expression inside the model value that should be displayed. Stored as a string; internally evaluated and converted to a tuple for array indexing.

Access functions:

• getModelIndex()

• setModelIndex()

• resetModelIndex()

Example:

plot.modelIndex = "(0,)"    # Index into a 2D array's first column
plot.modelIndex = ""        # Reset to None (display full vector)

cut.wdglib.taurus.plot.taurusqeplot.getModelIndex() → str

Return the string representation of the current model index.

Returns:

The model index expression as a string.

cut.wdglib.taurus.plot.taurusqeplot.setModelIndex(modelIndex: str) → None

Parse and apply a model index expression. The value is evaluated via Python’s eval() and must resolve to a sequence (list or tuple). A single integer is automatically wrapped in a tuple. Triggers controller update.

Parameters:

modelIndex – String expression, e.g. "(0,)" or "[1, 2]".

Note

The source code references Sequence from collections.abc without importing it. Calling setModelIndex() with a non-empty value may raise a NameError at runtime.

cut.wdglib.taurus.plot.taurusqeplot.resetModelIndex() → None

Reset the model index to the default value of None.

cut.wdglib.taurus.plot.taurusqeplot.getModelIndexValue() → tuple

Return the internal parsed model index value as a tuple, or None.

2.4.2.3. fgRole

cut.wdglib.taurus.plot.taurusqeplot.fgRole

The foreground role, controlling what value text is displayed on the widget. Valid values are:

• "value" – display the read value

• "w_value" – display the write value

• None – display no value text

Default: "value".

Access functions:

• getFgRole()

• setFgRole()

• resetFgRole()

cut.wdglib.taurus.plot.taurusqeplot.getFgRole() → str

Returns:

The current foreground role string.

cut.wdglib.taurus.plot.taurusqeplot.setFgRole(fgRole: str) → None

Set the foreground role. The value is lowercased and the controller is updated.

Parameters:

fgRole – One of "value", "w_value", or None.

cut.wdglib.taurus.plot.taurusqeplot.resetFgRole() → None

Reset the foreground role to "value".

2.4.2.4. bgRole

cut.wdglib.taurus.plot.taurusqeplot.bgRole

The background role, controlling the widget’s background color based on model state. Valid values are:

• "quality" – color based on Taurus attribute quality

• "state" – color based on Taurus device state

• None – no automatic background update

Default: "quality".

Access functions:

• getBgRole()

• setBgRole()

• resetBgRole()

cut.wdglib.taurus.plot.taurusqeplot.getBgRole() → str

Returns:

The current background role string.

cut.wdglib.taurus.plot.taurusqeplot.setBgRole(bgRole: str) → None

Set the background role. The value is lowercased and the controller is updated.

Parameters:

bgRole – One of "quality", "state", or None.

cut.wdglib.taurus.plot.taurusqeplot.resetBgRole() → None

Reset the background role to "quality".

2.4.3. Methods

2.4.3.1. Taurus Integration

cut.wdglib.taurus.plot.taurusqeplot.handleEvent(evt_src, evt_type, evt_value) → None

Receives a Taurus event and delegates it to the internal controller. The controller identifies which model triggered the event, extracts 1D data, and calls setNumpyNdArray() to update the plot.

cut.wdglib.taurus.plot.taurusqeplot.controller() → TaurusBaseController

Return the internal controller object, creating it lazily on first access. The controller type depends on the model type:

• TaurusModelType.Attribute -> _TaurusQePlotControllerAttribute

• TaurusModelType.Configuration -> _TaurusQePlotControllerConfiguration

• Other/unknown -> _TaurusQePlotController

The controller handles event routing, data extraction, and foreground/ background updates.

Returns:

The active TaurusBaseController instance.

cut.wdglib.taurus.plot.taurusqeplot.isReadOnly() → bool

Returns True. TaurusQePlot is a display-only widget and does not support writing data back to Taurus models.

Returns:

Always True.

cut.wdglib.taurus.plot.taurusqeplot.getModelObj(key=MLIST) → object

Return the Taurus model object associated with the given key, or None if no model is associated.

Parameters:

key – Model key (defaults to MLIST).

Returns:

The Taurus model object.

cut.wdglib.taurus.plot.taurusqeplot.getModelObjDict() → dict

Return the dictionary of all currently handled Taurus models, mapping keys to their model objects.

Returns:

Dictionary of key-to-model-object mappings.

cut.wdglib.taurus.plot.taurusqeplot.getModelType(key=MLIST) → TaurusElementType

Return the type of the current Taurus model (e.g., Attribute, Configuration, Command, Unknown). Delegates to the base class with the MLIST key.

2.4.3.2. Inherited from QePlot

TaurusQePlot inherits the full QePlot plotting API. See QePlot - 1D Plot Display Widget for the complete reference. The inherited methods include:

• Data loading: setNumpyNdArray(), ClearCurves()

• Toolbar: ToggleToolbar(), SetMainWindowForToolbar()

• Plot style: on_actionLine_Plot_triggered(), on_actionScatter_Plot_triggered()

• Zoom: on_actionQePlotZoom_In_triggered(), on_actionQePlotZoom_Out_triggered(), on_actionQePlotZoom_Reset_triggered()

• Y-axis scale: on_actionYAxis_Linear_triggered(), on_actionYAxis_Log_triggered(), on_actionYAxis_Square_Root_triggered()

• Export: on_actionExport_triggered()

2.4.3.3. Stub Methods

cut.wdglib.taurus.plot.taurusqeplot.setXAxisMode(mode: str) → None

Stub method with no implementation. Intended for future X-axis mode configuration. Currently does nothing.

Parameters:

mode – Unused.

2.4.4. Controller Architecture

The module defines several internal controller classes that mediate between Taurus events and the QePlot canvas:

• ``_TaurusQePlotController`` – Base controller. Routes events by model source key, calls setNumpyNdArray(value.magnitude) for 1D attribute data. Ignores scalar (0D) and None values.

• ``_TaurusQePlotControllerAttribute`` – Specialized for TaurusModelType.Attribute. Extends the base controller with TaurusVectorAttributeControllerHelper to properly display and extract vector magnitudes from Taurus attribute value objects.

• ``_TaurusQePlotControllerConfiguration`` – Specialized for TaurusModelType.Configuration. Extends the base controller with TaurusConfigurationControllerHelper.

The Controller() factory function selects the appropriate controller class based on the model type via the _CONTROLLER_MAP dictionary.

2.4.4.1. Data Flow

When a Taurus attribute fires an event, the following sequence occurs:

1. TaurusQePlot.handleEvent() receives the event and delegates to the controller.

2. The controller’s handleEvent() identifies the triggering model by key.

3. controller.update(key) is called, which invokes _updateForeground().

4. _updateForeground() checks data format: only DataFormat._1D is plotted.

5. widget.setNumpyNdArray(value.magnitude) plots the numeric data, clearing any previous curve.

2.4.5. Standalone Launcher

The taurus plot command launches a standalone plot application window. With the cut.wdglib.taurus.plot package installed, cutplot is registered as an alternative implementation for the taurus plot subcommand. Each model is displayed in its own widget stacked vertically.

Single attribute:

taurus plot cii.oldb:/cut/demoservice/instance1/double-vector-sin

Multiple attributes:

taurus plot \
    cii.oldb:/cut/demoservice/instance1/double-vector-sin \
    cii.oldb:/cut/demoservice/instance1/double-vector-cos

Demo mode:

taurus plot --demo

2.4.6. Example Usage

Connecting to a Taurus attribute:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqeplot import TaurusQePlot

app = TaurusApplication()
plot = TaurusQePlot()
plot.model = "cii.oldb:/cut/demoservice/instance1/double-vector-sin"
plot.fgRole = "value"
plot.bgRole = "quality"
plot.show()
app.exec_()

Multiple plots with Taurus models:

from taurus.qt.qtgui.application import TaurusApplication
from taurus.external.qt.QtWidgets import QWidget, QVBoxLayout
from cut.wdglib.taurus.plot.taurusqeplot import TaurusQePlot

app = TaurusApplication()
container = QWidget()
layout = QVBoxLayout()
container.setLayout(layout)

attrs = [
    "cii.oldb:/cut/demoservice/instance1/double-vector-sin",
    "cii.oldb:/cut/demoservice/instance1/double-vector-cos",
]
for attr in attrs:
    plot = TaurusQePlot()
    plot.model = attr
    plot.fgRole = "value"
    layout.addWidget(plot)

container.show()
app.exec_()

Using the taurus plot command:

taurus plot cii.oldb:/cut/demoservice/instance1/double-vector-sin

Programmatically controlling plot appearance:

from cut.wdglib.taurus.plot.taurusqeplot import TaurusQePlot

plot = TaurusQePlot()
plot.model = "eval:rand(100)"
plot.fgRole = "value"
plot.bgRole = "state"

# Switch to scatter mode
plot.on_actionScatter_Plot_triggered(True)

# Export to PDF
plot.on_actionExport_triggered()

2.4.7. Notes

• TaurusQePlot is read-only. It displays data from Taurus models but does not support writing values back to devices.

• Only 1D vector data (DataFormat._1D) is plotted. Scalar attributes (DataFormat._0D) and None values are silently ignored.

• Each incoming event clears the previous curve and plots a single new curve. Multi-curve plotting from multiple models within the same widget is not currently supported.

• The toolbar is shown automatically on construction via ToggleToolbar().

• setModelIndex() has a bug: it references Sequence from collections.abc without importing it, which causes a NameError when called with a non-empty index expression.

• setXAxisMode() is a stub with no implementation.

• Several source docstrings have copy-paste errors (e.g., setModelIndex says “Getter” in the docstring, and resetModelIndex references bgRole instead of modelIndex).

• The bgRole and fgRole values are lowercased automatically on set.

• When the model is set from a UI source as a comma-separated string, it is automatically split into a list.

• The widget is registered as a Qt Designer plugin in the “Taurus Display” group with the tool tip “Plotting tool based on QePlot.”

• PDF export writes to ~/qeplot-<timestamp>.pdf. There is no way to override the output path from Python.

• Mouse interaction is built-in from QePlot: left-click drag for panning, mouse wheel for zooming, with a tracker tooltip on the canvas.