2.6. TaurusQeImage - Taurus-Integrated 2D Image Display Widget

2.6.1. Overview

TaurusQeImage is a 2D image display widget that bridges the QeImage canvas with the Taurus SCADA system. It connects to Taurus devices and attributes, receives live data through Taurus events, and renders 2D array values as images using the underlying QeImage infrastructure (built on the Data Display Tool library).

The widget uses multiple inheritance from both QeImage (the C++/Qt image canvas) and TaurusBaseWidget (the Taurus data-binding base class). When a Taurus attribute fires an event, the internal controller extracts the 2D data magnitude and calls QeImage.setNumpyNdArray() to update the displayed image.

Key difference from TaurusQePlot and TaurusQeTrend: TaurusQeImage handles 2D array (DataFormat._2D) Taurus attributes and supports a single model only. Unlike the plot and trend widgets, it does not provide modelKeys, getModelObj, or getModelObjDict methods, and its setModel() accepts only a single model string (no comma-separated lists or multi-model support). The toolbar is not automatically shown on construction.

TaurusQeImage widget (visually identical to QeImage)

2.6.1.1. Constructor

The constructor signature is

TaurusQeImage(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.

Unlike TaurusQeTrend, the constructor does not accept additional parameters for toolbar visibility, buffer size, or Taurus-specific configuration.

Example:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqeimage import TaurusQeImage

app = TaurusApplication()
image = TaurusQeImage()
image.model = "cii.oldb:/cut/demoservice/instance1/double-matrix-sin-cos"
image.show()
app.exec_()

2.6.1.2. Inheritance Hierarchy

TaurusQeImage uses multiple inheritance, combining the QeImage canvas path with the Taurus data-binding path:

2.6.2. Qt Properties

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

2.6.2.1. model

cut.wdglib.taurus.plot.taurusqeimage.model

The unique URI string representing the Taurus model the widget will read data from. Unlike TaurusQePlot and TaurusQeTrend, this property accepts only a single model string – not comma-separated lists or lists of URIs.

Setting model forces the widget to rebuild its internal controller.

Access functions:

• TaurusBaseWidget.getModel()

• setModel()

• TaurusBaseWidget.resetModel()

Example:

image.model = "cii.oldb:/cut/demoservice/instance1/double-matrix-sin-cos"

cut.wdglib.taurus.plot.taurusqeimage.setModel(m: str) → None

Setter for the model property. Accepts a single model URI string. Resets the internal controller so the new model type is handled correctly.

Note

Unlike TaurusQePlot and TaurusQeTrend, this method does not accept lists, comma-separated strings, or the key parameter.

Parameters:

m – Model URI string.

2.6.2.2. modelIndex

cut.wdglib.taurus.plot.taurusqeimage.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:

image.modelIndex = "(0, 0)"    # Index into the 2D array
image.modelIndex = ""          # Reset to None

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

Return the string representation of the current model index.

Returns:

The model index expression as a string.

cut.wdglib.taurus.plot.taurusqeimage.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, 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.taurusqeimage.resetModelIndex() → None

Reset the model index to the default value of None.

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

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

2.6.2.3. fgRole

cut.wdglib.taurus.plot.taurusqeimage.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.taurusqeimage.getFgRole() → str

Returns:

The current foreground role string.

cut.wdglib.taurus.plot.taurusqeimage.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.taurusqeimage.resetFgRole() → None

Reset the foreground role to "value".

2.6.2.4. bgRole

cut.wdglib.taurus.plot.taurusqeimage.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.taurusqeimage.getBgRole() → str

Returns:

The current background role string.

cut.wdglib.taurus.plot.taurusqeimage.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.taurusqeimage.resetBgRole() → None

Reset the background role to "quality".

2.6.3. Methods

2.6.3.1. Taurus Integration

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

Receives a Taurus event and delegates it to the internal controller. The controller extracts 2D image data and calls setNumpyNdArray() to update the displayed image.

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

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

• TaurusModelType.Attribute -> _TaurusQeImageControllerAttribute

• TaurusModelType.Configuration -> _TaurusQeImageControllerConfiguration

• Other/unknown -> _TaurusQeImageController

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

Returns:

The active TaurusBaseController instance.

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

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

Returns:

Always True.

2.6.3.2. Inherited from QeImage

TaurusQeImage inherits the full QeImage display API. See QeImage - 2D Image Display Widget for the complete reference. The inherited methods include:

• Data loading: setNumpyNdArray()

• Image transformation: FlipHorizontally(), FlipVertically(), Rotate()

• Colormap: SetColormap(), InvertColormap(), SwitchToAutoColormapScaling(), SwitchToManualColormapScaling()

• Cut levels: SetMincutvalue(), SetMaxcutvalue()

• Auto scale: set_auto_scale()

• Mouse coordinates: Access to lastMouseCoordinates property

Additionally, QeImage exposes several Qt Designer properties inherited from the DDT (Data Display Tool) library:

• filename – currently loaded image file path

• colourmap – current colormap name

• colormapscaling – colormap scaling mode

• colormapinvert – colormap inversion state

• fliphorizontal – horizontal flip state

• flipvertical – vertical flip state

• mincutvalue – lower cut level for colormap contrast

• maxcutvalue – upper cut level for colormap contrast

• rotation – image rotation angle

• availablecolourmaps – list of available colormap names

• lastMouseCoordinates – last mouse hover coordinates on the image

2.6.4. Controller Architecture

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

• ``_TaurusQeImageController`` – Base controller. Overrides only _updateForeground(). Checks data format: only DataFormat._2D is rendered. Calls widget.setNumpyNdArray(value.magnitude). Does not override handleEvent() or update(), relying entirely on the TaurusBaseController base implementation. This means it does not support multi-model event routing.

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

• ``_TaurusQeImageControllerConfiguration`` – Specialized for TaurusModelType.Configuration. Extends the base controller with TaurusConfigurationControllerHelper. Minimal – delegates everything to parents.

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

2.6.4.1. Data Flow

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

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

2. The base TaurusBaseController.handleEvent() processes the event and calls controller.update().

3. TaurusBaseController.update() calls _updateForeground(widget).

4. _updateForeground() checks data format: only DataFormat._2D is rendered. Scalar (_0D) and vector (_1D) data are ignored.

5. widget.setNumpyNdArray(value.magnitude) renders the 2D image, replacing any previously displayed image.

2.6.5. Standalone Launcher

The taurus image command launches a standalone image viewer application. With the cut.wdglib.taurus.plot package installed, cutimage is registered as an alternative implementation for the taurus image subcommand.

Single image:

taurus image cii.oldb:/cut/demoservice/instance1/double-matrix-sin-cos

Multiple images:

taurus image \
    cii.oldb:/cut/demoservice/instance1/double-matrix-sin \
    cii.oldb:/cut/demoservice/instance1/double-matrix-cos

Demo mode:

taurus image --demo

2.6.6. Example Usage

Connecting to a 2D Taurus attribute:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqeimage import TaurusQeImage

app = TaurusApplication()
image = TaurusQeImage()
image.model = "cii.oldb:/cut/demoservice/instance1/double-matrix-sin-cos"
image.fgRole = "value"
image.bgRole = "quality"
image.show()
app.exec_()

Configuring colormap and cut levels:

from taurus.qt.qtgui.application import TaurusApplication
from cut.wdglib.taurus.plot.taurusqeimage import TaurusQeImage

app = TaurusApplication()
image = TaurusQeImage()
image.model = "cii.oldb:/cut/demoservice/instance1/double-matrix-sin-cos"
image.set_auto_scale(False)
image.SetMincutvalue(0.0)
image.SetMaxcutvalue(255.0)
image.InvertColormap(True)
image.show()
app.exec_()

Using the taurus image command:

taurus image cii.oldb:/cut/demoservice/instance1/double-matrix-sin-cos

2.6.7. Notes

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

• Only 2D array data (DataFormat._2D) is rendered. Scalar attributes (DataFormat._0D) and vector attributes (DataFormat._1D) are silently ignored by the controller’s _updateForeground().

• TaurusQeImage supports a single model only. Unlike TaurusQePlot and TaurusQeTrend, it does not define modelKeys, getModelObj, getModelObjDict, or getModelType. The setModel() method accepts only a single string parameter (no comma-separated lists or key argument).

• Dead code in _TaurusQeImageController._updateForeground(): The condition format == DataFormat._0D and format == DataFormat._1D can never be true (a value cannot be both 0D and 1D simultaneously). This branch is unreachable. The adjacent comment reads “Accepted 1D (vector) data” but the actual condition checks for DataFormat._2D.

• The constructor does not call ToggleToolbar() automatically, unlike TaurusQePlot and TaurusQeTrend.

• 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.

• 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.

• TaurusBaseWidget.setModel() is called directly with the string; the Taurus framework will typically wrap it into a single-element list internally.

• The controller’s __init__(self, QeImage) parameter name shadows the QeImage class import, making the code confusing. This does not cause a runtime error but is a code quality issue.

• TaurusScalarAttributeControllerHelper is imported but never used in the module.

• The widget is registered as a Qt Designer plugin in the “Taurus Display” group with the tool tip “Displays image using Data Display Tool and CUT.”

• numpy and datetime are not imported by this module (unlike TaurusQeTrend, which imports both but does not use them).

• PDF export, zoom controls, and other features from the DDT/QeImage base class are inherited and available. See QeImage - 2D Image Display Widget for details.