2.2. QePlot - 1D Plot Display Widget

2.2.1. Overview

QePlot is a full-featured 1D plot widget built on the QwtPlot library. It provides curve plotting from typed vectors and NumPy arrays, zoom/pan interaction, toolbar integration, plot style toggling (line vs scatter), Y-axis scale selection (linear, logarithmic), and PDF export. The widget inherits from QePlotBase which encapsulates the shared Qwt plotting infrastructure, and is exposed through Python bindings generated by Shiboken from the C++/Qt implementation.

Unlike QeImage (2D display), QePlot plots 1D data as curves with index values on the X axis and sample values on the Y axis. It does not define any Qt properties with signals; the public API is method and slot driven.

../_images/qeplot_01.png

QePlot widget

2.2.1.1. Constructor

The constructor signature is

QePlot(parent: QWidget = None)

Parameters:

  • parent (QWidget, optional) – Parent widget.

Example:

# Any Qt Widget needs an Application running
from PySide6.QtWidgets import QApplication
app = QApplication([])
from cut.wdglib.widgets import QePlot
plot = QePlot()
plot.show()

2.2.1.2. Inheritance Hierarchy

QePlot inherits from QePlotBase which encapsulates the shared Qwt plotting infrastructure:

hide empty members hide empty attributes class QePlot class QePlotBase class QWidget <<PySide6.QtWidgets>> class QObject <<PySide6.QtCore>> class QPaintDevice <<PySide6.QtGui>> class ShibokenObject <<Shiboken>> class object QePlot --|> QePlotBase QePlotBase --|> QWidget QWidget --|> QObject QObject --|> QPaintDevice QPaintDevice --|> ShibokenObject ShibokenObject --|> object

2.2.2. Methods

2.2.2.1. Data Loading

cut.wdglib.widgets.setNumpyNdArray(data: object) → None

Plot data from a 1-D NumPy array as a new curve, clearing any existing curves. The data is automatically internally converted to float or double (int8/int16/uint8/uint16/bool -> float, int32/int64/uint32/uint64 -> double).

The X axis is the sample index (0, 1, 2, …); the Y axis is the array values.

Supported dtypes include int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, and bool.

Passing None, an empty array, a 2-D array, or an unsupported dtype will silently clear the plot without raising an error.

Parameters:

data – A 1-D NumPy array, or None to clear the plot.

Example:

import numpy as np
from cut.wdglib.widgets import QePlot

plot = QePlot()
data = np.arange(100, dtype=np.float64)
plot.setNumpyNdArray(data)
cut.wdglib.widgets.ClearCurves() → None

Remove all curves from the plot and clear the internal curve map. After calling this method the plot canvas will be empty.

Example:

plot.ClearCurves()

2.2.2.2. Toolbar Management

cut.wdglib.widgets.ToggleToolbar() → None

Toggle the visibility of the plot toolbar. The toolbar contains buttons for zoom in/out, reset, line/scatter plot, axis scale selection, and PDF export.

Example:

plot.ToggleToolbar()
cut.wdglib.widgets.SetMainWindowForToolbar(window: PySide6.QtWidgets.QMainWindow) → None

Assign the owning QMainWindow so the toolbar can be docked into it. When the widget is shown, its internal toolbar is attached to this window. If not set, the widget auto-detects the nearest QMainWindow ancestor.

Parameters:

window – The QMainWindow that will host the plot toolbar.

Example:

from PySide6.QtWidgets import QMainWindow
main_window = QMainWindow()
plot.SetMainWindowForToolbar(main_window)

2.2.2.3. Plot Style

cut.wdglib.widgets.on_actionLine_Plot_triggered(checked: bool) → None

Toggle line plot mode (connect points with lines). When checked is True, all curves are rendered as continuous lines. When False, curves revert to scatter mode.

Note: This is a protected slot that is connected to the toolbar toggle buttons. It is also callable directly to change the display style.

Parameters:

checked – True to switch to line mode, False for scatter mode.

cut.wdglib.widgets.on_actionScatter_Plot_triggered(checked: bool) → None

Toggle scatter plot mode (show points without connecting lines). When checked is True, all curves are rendered as point markers only. When False, curves revert to line mode.

Parameters:

checked – True to switch to scatter mode, False for line mode.

2.2.2.4. Zoom Controls

cut.wdglib.widgets.on_actionQePlotZoom_In_triggered() → None

Zoom in on the plot canvas by a factor of 0.75.

cut.wdglib.widgets.on_actionQePlotZoom_Out_triggered() → None

Zoom out on the plot canvas by a factor of 1/0.75.

cut.wdglib.widgets.on_actionQePlotZoom_Reset_triggered() → None

Reset zoom level and re-enable auto-scaling on both axes.

2.2.2.5. Y-Axis Scale

cut.wdglib.widgets.on_actionYAxis_Linear_triggered(checked: bool) → None

Switch the Y-axis to linear scale (QwtLinearScaleEngine). Re-enables the line plot toggle. The checked parameter is unused but required by the Qt slot signature.

Parameters:

checked – Unused (always provided by Qt when triggered from toolbar).

cut.wdglib.widgets.on_actionYAxis_Log_triggered(checked: bool) → None

Switch the Y-axis to logarithmic scale (QwtLogScaleEngine). This automatically forces scatter mode and disables the line plot toggle, because Qwt has a bug rendering line plots with logarithmic scale.

Parameters:

checked – Unused.

cut.wdglib.widgets.on_actionYAxis_Square_Root_triggered(checked: bool) → None

Stub slot for switching the Y-axis to square-root scale. Not yet implemented – this method currently does nothing.

Parameters:

checked – Unused.

2.2.2.6. PDF Export

cut.wdglib.widgets.on_actionExport_triggered() → None

Export the current plot to a PDF file in the user’s home directory. The output filename includes a UTC timestamp in ISO format (format: qeplot-<date>.pdf). The PDF renders at 384 DPI with a canvas size of 300x200 logical units.

Example:

# Programmatically trigger export (toolbar button does this)
plot.on_actionExport_triggered()

2.2.3. Protected Event Handlers

These methods are called by Qt during widget lifecycle events. Override them for custom behaviour, but call the base implementation.

cut.wdglib.widgets.showEvent(event: PySide6.QtGui.QShowEvent) → None

Called when the widget becomes visible. Shows the toolbar and docks it into the owning QMainWindow.

cut.wdglib.widgets.hideEvent(event: PySide6.QtGui.QHideEvent) → None

Called when the widget is hidden. Hides the toolbar and removes it from the owning QMainWindow.

2.2.4. Exposed Member Variables

The following protected member variable is accessible through the Python bindings (though it is intended for internal use):

  • m_color_list (list[QColor]) – Read-only palette of seven colors assigned to curves in rotation when new curves are created. The colors are: #E58606, #5D69B1, #52BCA3, #99C945, #24796C, #CC61B0, #24796C.

2.2.5. Signals

QePlot does not define custom signals beyond those inherited from QWidget and QObject. The following standard Qt signals are available:

  • customContextMenuRequested(pos: QPoint) – Emitted when the user requests a context menu on the widget.

  • destroyed(obj: object = None) – Emitted when the widget is destroyed.

  • objectNameChanged(name: str) – Emitted when the object name changes.

  • windowTitleChanged(title: str) – Emitted when the window title changes.

  • windowIconChanged(icon: QIcon) – Emitted when the window icon changes.

  • windowIconTextChanged(text: str) – Emitted when the icon text changes.

2.2.6. QeTypes Enum

The data type of the attached curve is represented by the QeTypes enum, importable from cut.common.pyb. This is used internally for type conversion when plotting typed data through the NumPy interface.

QeTypes.Int8
QeTypes.Int16
QeTypes.Int32
QeTypes.Int64
QeTypes.UInt8
QeTypes.UInt16
QeTypes.UInt32
QeTypes.UInt64
QeTypes.Float
QeTypes.Double
QeTypes.String
QeTypes.Boolean
QeTypes.NotSet

2.2.7. Type Conversion

When data is passed through setNumpyNdArray(), the widget converts the NumPy array into a std::shared_ptr<std::vector<...>> and then internally to float (for Qwt plot samples). The conversion rules are:

  • int8, int16, uint8, uint16, bool -> converted to float (AddFloatCurve)

  • int32, int64, uint32, uint64 -> converted to double (AddDoubleCurve)

  • float32, float64 -> passed through directly

Each call to setNumpyNdArray() clears all previously plotted curves and creates a single new curve.

2.2.8. Example Usage

Basic plot from NumPy data:

import numpy as np
from cut.wdglib.widgets import QePlot
from PySide6.QtWidgets import QApplication

app = QApplication([])
plot = QePlot()

# Generate test data
x = np.linspace(0, 10, 500)
data = np.sin(x) * np.exp(-x / 10)
plot.setNumpyNdArray(data)

# Show toolbar
plot.ToggleToolbar()
plot.show()
app.exec()

Integer data with various dtypes:

import numpy as np
from cut.wdglib.widgets import QePlot
from PySide6.QtWidgets import QApplication

app = QApplication([])

# uint16 data (will be converted to float internally)
plot = QePlot()
samples = np.array([100, 150, 200, 180, 220, 250, 300, 280, 350, 400], dtype=np.uint16)
plot.setNumpyNdArray(samples)

plot.ToggleToolbar()
plot.show()
app.exec()

Clearing and re-plotting:

import numpy as np
from cut.wdglib.widgets import QePlot

plot = QePlot()

# Plot first dataset
plot.setNumpyNdArray(np.arange(50, dtype=np.float64))

# Clear everything
plot.ClearCurves()

# Repopulate
plot.setNumpyNdArray(np.arange(50, 0, -1, dtype=np.float64))

Using plot controls programmatically:

from cut.wdglib.widgets import QePlot
import numpy as np

plot = QePlot()
plot.setNumpyNdArray(np.random.randn(1000), )

# Switch to scatter mode
plot.on_actionScatter_Plot_triggered(True)

# Switch Y-axis to log scale (forces scatter mode)
plot.on_actionYAxis_Log_triggered(True)

# Zoom in
plot.on_actionQePlotZoom_In_triggered()

# Reset zoom
plot.on_actionQePlotZoom_Reset_triggered()

# Export to PDF
plot.on_actionExport_triggered()

2.2.9. Notes

  • QePlot only accepts 1D data. Passing a 2D array to setNumpyNdArray() will silently clear the plot without error.

  • setNumpyNdArray(None) clears the plot, equivalent to calling ClearCurves().

  • setNumpyNdArray() clears all existing curves before adding the new one. QePlot does not currently support multi-curve plotting from Python (the protected AddFloatCurve/AddDoubleCurve methods are not exposed in the Python bindings).

  • When the Y-axis is set to logarithmic scale, line plot mode is disabled and scatter mode is forced automatically.

  • The square-root Y-axis scale (on_actionYAxis_Square_Root_triggered) is a stub and has no effect.

  • The plot toolbar is hidden by default. Call ToggleToolbar() to show it, or ensure the widget is parented to a QMainWindow which will auto-show the toolbar on show().

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

  • The setNumpyNdArray() method supports all common NumPy numeric dtypes: int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, and bool.

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

  • Each new curve receives a color from the internal palette of 7 colors, cycling through the list. The default curve counter starts at -1, so the first curve is named “Curve 0” if no explicit name is provided.