Source code for gpype.frontend.widgets.time_series_scope

"""TimeSeriesScope, importable with no Qt installed.

A server constructs this node to describe the display an edge draws, and
may have no PySide6 at all, so every Qt symbol is reached from inside a
function. ``test_frontend_widgets_import_without_qt`` holds it.
"""

from __future__ import annotations

import threading
import time
import weakref
from typing import Optional

import ioiocore as ioc
import numpy as np

from ...backend.core.i_port import IPort
from ...common._private import channels
from ...common.constants import Constants
from ._validation import check_bounds
from .base.scope import Scope
from .base.widget import _weak_slot

#: Default input port identifier for time series data
PORT_IN = ioc.Constants.Defaults.PORT_IN


#: Built once, on first use. See :func:`_key_press_filter_class`.
_KEY_PRESS_FILTER: Optional[type] = None


def _key_press_filter_class() -> type:
    """Return the key-filter class, defining it on first call.

    Defined inside a function because a class statement evaluates its
    bases at **import** time, and ``QObject`` is a Qt symbol: at module
    scope that made this module unimportable without PySide6. A server
    has no screen and, since 4.0.0's layered install, may have no Qt at
    all, yet it must import this module to deserialise a document naming
    a `TimeSeriesScope`. Being nested inside the core class hid it from a
    scan of top-level definitions and made no difference to when it ran.

    Returns:
        The ``KeyPressFilter`` class, cached after the first call.
    """
    global _KEY_PRESS_FILTER
    if _KEY_PRESS_FILTER is None:
        from PySide6.QtCore import QObject

        class KeyPressFilter(QObject):
            """Event filter for keyboard shortcuts in the time series scope.

            Captures keyboard events to provide interactive functionality.
            Currently handles Alt+R for performance monitoring toggle.

            Args:
                callback: Called when the key combination is seen.
            """

            def __init__(self, callback):
                """Initialize key press filter with callback function."""
                super().__init__()
                self.callback = callback

            def eventFilter(self, obj, event):
                """Filter keyboard events and trigger callbacks for shortcuts.

                Args:
                    obj: Qt object that received the event.
                    event: Qt event to process.

                Returns:
                    False, so the event goes on to its target.
                """
                from PySide6.QtCore import QEvent, Qt

                if event.type() == QEvent.KeyPress:
                    if event.key() == Qt.Key_R:
                        if event.modifiers() & Qt.AltModifier:
                            self.callback()
                return False

        _KEY_PRESS_FILTER = KeyPressFilter
    return _KEY_PRESS_FILTER


class Markers(dict):
    """Container for event marker configuration.

    Stores marker properties including color, label, channel association,
    and trigger value for event-based visualization.

    Args:
        color: Hex color code or color name for marker visualization.
        label: Text label for marker identification.
        channel: Channel index where marker should be displayed.
        value: Trigger value that activates the marker.
    """

    def __init__(self, color: str, label: str, channel: int, value: int):
        """Initialize marker configuration with display properties."""
        super().__init__()
        self["color"] = color
        self["label"] = label
        self["channel"] = channels.as_index(channel, "channel")
        self["value"] = value


[docs] class TimeSeriesScope(Scope): """Real-time oscilloscope widget for multi-channel time series. Displays continuous time-series data from BCI pipelines with configurable time windows, amplitude scaling, channel hiding, and event markers. """ #: Default display window duration in seconds DEFAULT_TIME_WINDOW: int = 10 #: Default amplitude scale limit in microvolts DEFAULT_AMPLITUDE_LIMIT: float = 50.0 #: Repaints per second when the author does not choose one. #: #: This display's own, deliberately higher than #: Widget.DEFAULT_REFRESH_RATE. A sweep moves continuously, so its #: frame rate is what the motion looks like; the other widgets only #: redraw when something arrives and 10 Hz is enough for them. #: #: 20 rather than 30 for two measured reasons. The interval is #: int(round(1000/rate)) ms, so 20 Hz is exactly 50 ms while 30 Hz #: is 33 ms and delivers 30.3. And the redraw is not the whole cost: #: _update() itself is 0.415 ms at 8 channels, but a full frame #: including Qt's rasterisation costs 8.85 ms at 8 channels, 20.0 ms #: at 32 and 32.8 ms at 64 -- so at 64 channels a 30 Hz frame would #: not fit inside its own interval. 20 Hz costs roughly 17% of one #: core at 8 channels and 63% at 64. DEFAULT_REFRESH_RATE: float = 20.0 #: Caption when the author names the scope nothing. CAPTION = "Time Series Scope" #: Accepted range for ``amplitude_limit``, in microvolts. Named so #: that a form can offer a slider with the right bounds. MIN_AMPLITUDE_LIMIT: float = 1.0 MAX_AMPLITUDE_LIMIT: float = 5_000.0 #: Accepted range for ``time_window``, in seconds, exclusive at both #: ends. The docstring said "(1-120)" for a long time while the code #: accepted 1 < x < 240, which is why the numbers live here now and #: the prose does not restate them. MIN_TIME_WINDOW: int = 1 MAX_TIME_WINDOW: int = 240 #: Amplitude scale change per button press, in microvolts. An int, so #: that an authored int limit stays an int and the axis label does not #: gain a ".0" the moment the viewer touches it. AMPLITUDE_STEP: int = 5 #: Time-window change per button press, in seconds. TIME_WINDOW_STEP: int = 5 #: Marker styling helper, reachable as gp.TimeSeriesScope.Markers. Markers = Markers
[docs] class Configuration(Scope.Configuration): """Configuration keys for TimeSeriesScope widget settings. Extends the base Scope configuration with time series specific parameters for display window, amplitude scaling, event markers, and channel visibility management. """
[docs] class Keys(Scope.Configuration.Keys): """Required configuration parameter keys.""" #: Configuration key for display duration in seconds TIME_WINDOW = "time_window" #: Configuration key for Y-axis scale in microvolts AMPLITUDE_LIMIT = "amplitude_limit"
[docs] class EmptyableKeys: """Optional keys that may also be *empty*. Deliberately not ``OptionalKeys``. That name means one specific thing to ioiocore -- may be absent, but must not be empty when present (``Configuration.__init__``) -- and an empty list is a legitimate value for every key declared here: no markers, no hidden channels. Declaring them under the name the validator reads makes ``markers=[]`` raise. Measured, so that nobody has to rediscover it:: OptionalKeys markers=[] -> ValueError, must not be empty EmptyableKeys markers=[] -> accepted The name is still the declaration a reader and a catalog generator look for; it is only kept out of the validator's emptiness rule. The underlying gap is ioiocore's: there is no way to say "optional, and empty is fine". """ #: Configuration key for event marker configurations MARKERS = "markers" #: Configuration key for channels to hide from display HIDDEN_CHANNELS = "hidden_channels"
[docs] def __init__( self, time_window: int = None, amplitude_limit: float = None, markers: list = None, hidden_channels: list = None, refresh_rate: float = None, show_amplitude_control: bool = True, show_time_window_control: bool = True, name: str = None, edge_id: Optional[str] = None, **kwargs, ): """Initialize the time series oscilloscope widget. Args: time_window: Display window duration in seconds; longer than 1 and shorter than 240. Uses DEFAULT_TIME_WINDOW if None. amplitude_limit: Y-axis scale limit in microvolts (1-5000). Uses DEFAULT_AMPLITUDE_LIMIT if None. markers: List of marker configurations for event visualization. Empty list if None. hidden_channels: List of channel indices to hide from display. Empty list if None. refresh_rate: Repaints per second. Defaults to DEFAULT_REFRESH_RATE. show_amplitude_control: Whether the display offers the viewer buttons for the amplitude scale. What they change is the display; the configured value is what a document round-trips. show_time_window_control: Whether the display offers the viewer buttons for the time window. Changing it re-cuts the sweep buffer, so the sweep restarts. name: Optional name for this node. Shown as the widget's group box caption, and used to refer to the node from a document's connections. edge_id: Which edge runs this node, matched against the edge process's --edge-id. None, the default, is every edge; ignored when the pipeline is not distributed. **kwargs: Additional arguments passed to parent Scope class. Raises: ValueError: If time_window is not longer than 1 second and shorter than 240. ValueError: If amplitude_limit is outside reasonable range. """ # Set default values if not provided if time_window is None: time_window = self.DEFAULT_TIME_WINDOW if amplitude_limit is None: amplitude_limit = self.DEFAULT_AMPLITUDE_LIMIT check_bounds( "time_window", time_window, self.MIN_TIME_WINDOW, self.MAX_TIME_WINDOW, unit="s", inclusive=False, ) time_window = round(time_window) check_bounds( "amplitude_limit", amplitude_limit, self.MIN_AMPLITUDE_LIMIT, self.MAX_AMPLITUDE_LIMIT, unit="uV", ) # Initialize marker and hidden channel lists if markers is None: markers = [] hidden_channels = channels.as_selection( [] if hidden_channels is None else hidden_channels, "hidden_channels", ) # Configure input ports for data reception ip_key = self.Configuration.Keys.INPUT_PORTS input_ports: list[IPort.Configuration] = kwargs.pop( ip_key, [IPort.Configuration(name=PORT_IN)] ) # Initialize parent Scope class with configuration Scope.__init__( self, input_ports=input_ports, time_window=time_window, amplitude_limit=amplitude_limit, name=name, refresh_rate=refresh_rate, markers=markers, hidden_channels=hidden_channels, show_amplitude_control=show_amplitude_control, show_time_window_control=show_time_window_control, edge_id=edge_id, **kwargs, ) # What the viewer is currently looking at, as opposed to what # the document asked for. An ioiocore Configuration is read-only # by construction -- "Configuration object is read-only. To store # user data, use contexts." -- and that is the right split: a # document should round-trip the pipeline that was authored, not # a scale somebody nudged mid-recording. Everything that draws # reads these two, so there is still one source per value. #: Amplitude scale currently drawn, in microvolts. self._amplitude_limit = amplitude_limit #: Time window currently drawn, in seconds. self._time_window = time_window # Interactive controls #: Whether to build the amplitude buttons. self._show_amplitude_control = show_amplitude_control #: Whether to build the time-window buttons. self._show_time_window_control = show_time_window_control #: Readout beside the amplitude buttons, built with them. self._amplitude_label = None #: Readout beside the time-window buttons, built with them. self._time_window_label = None # Continuity across a time-window change #: Samples written before the current buffer, banked whenever the #: window changes so that the time axis keeps counting up instead #: of restarting at zero. self._elapsed_samples = 0 #: Whether tick labels need a decimal. A resize moves the sweep #: origin off whole seconds, so afterwards they do. self._fractional_ticks = False # Data buffer management #: Maximum number of displayable data points self._max_points: int = None #: Raw data storage buffer for all channels self._data_buffer: np.ndarray = None #: Processed display data for visible channels only self._display_buffer: np.ndarray = None #: X range currently applied to the view, so an unchanged one is #: not re-applied on every frame. self._xlim_drawn: tuple = None #: Current position index in circular buffer self._plot_index: int = 0 #: Flag indicating circular buffer overflow status self._buffer_full: bool = False #: Global sample counter for data tracking self._sample_index: int = 0 # Performance monitoring #: Widget initialization timestamp for rate calculations self._start_time = time.time() #: Counter for display update operations self._update_counts = 0 #: Counter for data processing steps self._step_counts = 0 #: Calculated data processing rate in Hz self._step_rate = 0 # Thread synchronization #: Thread lock for safe data buffer access self._lock = threading.Lock() #: Flag indicating new data is available for display self._new_data = False #: Samples written since start, incremented under the lock. A #: monotone count rather than a flag, so the display can tell how #: much it has missed and a burst cannot be mistaken for silence. self._write_count = 0 # UI components #: Label widget for displaying performance statistics self._rate_label = None #: Flag controlling performance statistics visibility self._show_rates = False # Everything past here reads the Qt palette or installs an event # filter on a widget, and a SERVER has neither -- see # base/scope.py for why a scope is constructed there at all. if self.widget is None: self._foreground_color = None self._background_color = None self._key_filter = None return from PySide6.QtGui import QPalette # Theme and appearance setup p = self.widget.palette() #: Foreground color extracted from system theme self._foreground_color = p.color(QPalette.ColorRole.WindowText) #: Background color extracted from system theme self._background_color = p.color(QPalette.ColorRole.Window) # Interactive features. The filter is deleted on the GUI thread # once the scope is freed, and held until then: a filter deleted # on a pipeline thread crashed the GUI thread's event processing # (D-NODE-75). So it holds the scope weakly, or the scope would # never be freed. toggle = weakref.WeakMethod(self._toggle_show_rates) def toggle_show_rates() -> None: method = toggle() if method is not None: method() #: Keyboard event filter for interactive shortcuts self._key_filter = self._delete_with_tree( _key_press_filter_class()(toggle_show_rates) ) self.widget.installEventFilter(self._key_filter)
def _toggle_show_rates(self): """Toggle visibility of performance monitoring information. Shows or hides performance statistics including frame rates and processing rates. Triggered by the Alt+R keyboard shortcut. """ self._show_rates = not self._show_rates self._rate_label.setVisible(self._show_rates)
[docs] def setup( self, data: dict[str, np.ndarray], port_context_in: dict[str, dict] ) -> dict[str, dict]: """Initialize the widget with data stream parameters and buffers. Args: data: Input data dictionary (not used in setup phase). port_context_in: Context information for input ports containing sampling rate, channel count, and frame size. Returns: dict: Updated port context for downstream components. Raises: ValueError: If required context parameters are missing. """ c = port_context_in[PORT_IN] # Extract and validate required context parameters sampling_rate = c.get(Constants.Keys.SAMPLING_RATE) if sampling_rate is None: raise ValueError("sampling rate must be provided.") channel_count = c.get(Constants.Keys.CHANNEL_COUNT) if channel_count is None: raise ValueError("channel count must be provided.") frame_size = c.get(Constants.Keys.FRAME_SIZE) if frame_size is None: raise ValueError("frame size must be provided.") # Calculate buffer dimensions based on time window and sampling # rate. Taken from config rather than from the window currently # drawn, because the buffer geometry allocated here is cut to # it: a fresh run re-applies what the document asked for. The # amplitude scale is deliberately not treated the same way -- # it allocates nothing, so there is nothing to reconcile, and # it stays where the viewer left it. time_window = self.config[self.Configuration.Keys.TIME_WINDOW] self._time_window = time_window self._refresh_time_window_label() self._max_points = int(round(time_window * sampling_rate)) self._t_vec = np.arange(0, self._max_points) / sampling_rate # Determine visible channels (exclude hidden ones) hidden_channels = self.config[ self.Configuration.EmptyableKeys.HIDDEN_CHANNELS ] self._channel_vec = [ i for i in range(channel_count) if i not in hidden_channels ] self._channel_count = len(self._channel_vec) self._channel_labels = self._resolve_channel_labels(c) # Store processing parameters #: Number of samples per data frame from pipeline self._frame_size = frame_size #: Data acquisition sampling rate in Hz self._sampling_rate = sampling_rate #: Last displayed second for time axis tick updates self._last_second = None # Allocate data buffers # Raw data buffer holds all channels self._data_buffer = np.zeros((self._max_points, channel_count)) # Display buffer holds only visible channels self._display_buffer = np.zeros( (self._max_points, self._channel_count) ) # The x range follows the time window, which has just been # re-read, so the cached copy of it must not survive. self._xlim_drawn = None # Initialize state variables #: Flag indicating new data availability for display self._new_data = False #: Widget initialization timestamp self._start_time = time.time() #: Dictionary storing active event markers self._markers = {} # The time axis starts from zero again on a fresh run, so the # banked count and the fractional labels it forces go with it. self._elapsed_samples = 0 self._fractional_ticks = False return super().setup(data, port_context_in)
def _update(self): """Update the visual display with new data from the buffer. Called by the Qt timer to refresh the plot with latest data. Handles curve creation, data plotting, performance monitoring, and marker visualization. Only updates when new data is available. """ import pyqtgraph as pg from PySide6 import QtWidgets from PySide6.QtGui import QColor, QFont if not self._new_data: return # Set up UI elements. Note that this has to be done in the main Qt # thread (like this) ylim = (0, self._channel_count) if self._curves is None: # Create curves for each visible channel [self.add_curve() for _ in range(self._channel_count)] self._refresh_axis_labels() # Configure channel labels on Y-axis ticks = [ ( self._channel_count - i - 0.5, self._channel_label(self._channel_vec[i]), ) for i in range(self._channel_count) ] self._plot_item.getAxis("left").setTicks([ticks]) self._plot_item.setYRange(*ylim) # Translucent foreground, for the rate overlay below. # A vertical cursor line used to be drawn here too, to # mark the write head; the NaN break in the curves # shows the same seam without a second item to keep in # step with it. col = QColor(self._foreground_color) # makes a copy col.setAlpha(128) # Create performance monitoring labels x = self._time_window y = ylim[1] font_size = 7 self._rate_label = pg.TextItem( text="", color=QColor(col), anchor=(1, 1) ) self._plot_item.addItem(self._rate_label) self._rate_label.setPos(x, y) self._rate_label.setFont(QFont("Arial", font_size)) # Interactive controls, built once and on the GUI # thread, for the same reason everything else here is. self._create_controls() # Update data with decimation for performance optimization. # Decimation factor N reduces displayed points based on widget # width -- which is 0 until the widget has been laid out, in # an unselected tab or a collapsed splitter, and dividing by # it raised ZeroDivisionError on the GUI thread. width = max(1, self.widget.width()) N = max(1, int(self._max_points / width)) with self._lock: # Copy decimated data from buffer for visible channels only self._display_buffer[::N, :] = self._data_buffer[ ::N, self._channel_vec ] self._new_data = False sample_idx = self._sample_index - 1 # Where the sweep is writing, in samples and in plot points cursor_pos = sample_idx % self._max_points break_idx = cursor_pos // N # Update x-axis ticks dynamically time_window = self._time_window cur_second = int(np.floor(cursor_pos / self._sampling_rate)) if cur_second != self._last_second: # Seconds since the display started: at the cursor, then # at x=0 of the current sweep. Stated as one subtraction # rather than as modulo arithmetic over the sweep count, # which is what it replaced -- this form is checkable by # eye, and it is the one that survives a mid-run resize, # because _elapsed_samples carries what the previous # buffers held. elapsed = self._elapsed_samples + sample_idx base = (elapsed - cursor_pos) / self._sampling_rate digits = 1 if self._fractional_ticks else 0 span = int(np.floor(time_window)) + 1 if sample_idx > self._max_points: # The buffer has wrapped, so everything right of the # cursor is the previous sweep: one window older. ticks = [ ( i, ( f"{base + i:.{digits}f}" if i <= cur_second else f"{base + i - time_window:.{digits}f}" ), ) for i in range(span) ] else: # First sweep: nothing right of the cursor has been # written, so label only what it has passed. ticks = [ ( i, f"{base + i:.{digits}f}" if i <= cur_second else "", ) for i in range(span) ] self._plot_item.getAxis("bottom").setTicks([ticks]) self._last_second = cur_second # Plot channel data with amplitude scaling and vertical # offset, broken at the write head. Drawn as one run of # points the curve joins the newest sample straight back to # the oldest one, painting a full-scale vertical line across # every lane -- an artefact of the ring buffer that is # nowhere in the data. A NaN with connect="finite" leaves a # gap there instead. ch_lim = self._amplitude_limit t_plot = self._t_vec[::N] n_points = len(t_plot) gap_half = max(1, int(0.005 * time_window * self._sampling_rate / N)) for i in range(len(self._channel_vec)): # Vertical offset: each channel gets its own "lane" d = self._channel_count - i - 0.5 y_plot = self._display_buffer[::N, i] / ch_lim / 2 + d if 0 <= break_idx < n_points - 1: gap_from = max(0, break_idx - gap_half) gap_to = min(n_points - 1, break_idx + gap_half) self._curves[i].setData( np.concatenate( ( t_plot[:gap_from], [np.nan], t_plot[gap_to + 1 :], ) ), np.concatenate( ( y_plot[:gap_from], [np.nan], y_plot[gap_to + 1 :], ) ), connect="finite", antialias=False, ) else: self._curves[i].setData(t_plot, y_plot, antialias=False) # Update x-axis range with small margin. Applied only when it # has actually moved: it follows the time window alone, so # setting it unconditionally asked the view to re-range to the # value it already held on every single frame. margin = time_window * 0.0125 xlim = (-margin, time_window + margin) if xlim != self._xlim_drawn: self._plot_item.setXRange(*xlim) self._xlim_drawn = xlim # Update event markers: detect state changes in marker channels mk_key = self.Configuration.EmptyableKeys.MARKERS markers: dict = {} for m in self.config[mk_key]: ch = m["channel"] val = m["value"] # Find rising edges where marker value appears hit = ( np.where( (self._data_buffer[1:, ch] == val) & (self._data_buffer[:-1, ch] != val) )[0] + 1 ) for h in hit: id = hash(tuple([h, ch, val])) markers[id] = {"index": h, "curve": None, **m} # Add new markers to plot for k in { k: markers[k] for k in markers.keys() if k not in self._markers.keys() }: m = markers[k] idx = m["index"] # Create text label for marker text = pg.TextItem( text=m["label"], anchor=(0.5, 1), color=pg.mkColor(m["color"]) ) self._plot_item.addItem(text) text.setPos(self._t_vec[idx], self._channel_count) # Create vertical line for marker curve = self._plot_item.plot(pen=pg.mkPen(pg.mkColor(m["color"]))) curve.setData(self._t_vec[[idx, idx]], np.array([*ylim])) markers[k]["curve"] = curve markers[k]["text"] = text self._markers[k] = markers[k] # Remove outdated markers from plot for k in { k: self._markers[k] for k in self._markers.keys() if k not in markers.keys() }: m = self._markers[k] self._plot_item.removeItem(m["curve"]) self._plot_item.removeItem(m["text"]) del self._markers[k] # Update performance monitoring display self._update_counts += 1 if self._show_rates: # max(1, ...): sample_idx is 0 on the very first frame of # a frame_size=1 stream, and this divided by it. update_rate = ( self._update_counts / max(1, sample_idx) * self._sampling_rate ) self._rate_label.setText( f"data rate: {self._step_rate:.1f} Hz, " f"refresh rate: {update_rate:.1f} Hz" ) # Mark all layers dirty to force redraw. # # The rectangle is left null on purpose. Qt reads a null rect as # "the whole scene", which is exactly what sceneRect() was being # asked for -- but computing it walks every item in the scene, # and a PlotCurveItem answers by taking nanmin and nanmax over # the points it holds. So the old form scanned every sample of # every curve, twice per curve, to produce an argument whose # only effect was to mean "everything". # # Measured offscreen, 10 s at 250 Hz, 8 channels, 900 px # (2500 points, decimation 2): this one line was 0.475 s of the # 0.693 s spent in 300 repaints -- 69% of the redraw -- via 2400 # boundingRect and 4800 dataBounds calls. Dropping the # sceneRect() argument takes _update() from 1.292 ms a call to # 0.415 ms, which is what pays for the default refresh rate # going from 10 Hz to 30: three times the repaints at 1.24% of # one core, against 1.29% for the old 10 Hz display. scene = self._plot_item.scene() scene.invalidate(layers=QtWidgets.QGraphicsScene.AllLayers) def _refresh_axis_labels(self) -> None: """Restate the axis labels for the amplitude currently drawn. The y label carries the scale, so it is rewritten whenever the viewer changes it. Left alone, the axis would keep announcing the authored scale while the curves were drawn to another one -- a display that lies about its own units. """ amp_lim = self._amplitude_limit self.set_labels( x_label="Time (s)", y_label=f"EEG Amplitudes (-{amp_lim} ... +{amp_lim} µV)", ) def _refresh_amplitude_label(self) -> None: """Show the amplitude currently drawn on the control bar.""" if self._amplitude_label is not None: self._amplitude_label.setText(f"±{self._amplitude_limit:g} µV") def _refresh_time_window_label(self) -> None: """Show the time window currently drawn on the control bar.""" if self._time_window_label is not None: self._time_window_label.setText(f"{self._time_window:g} s") @staticmethod def _add_step_buttons(layout, on_decrease, on_increase) -> None: """Append a -/+ button pair to a control bar. Args: layout: Layout to append the buttons to. on_decrease: Handler for the "-" button. on_increase: Handler for the "+" button. """ from PySide6.QtWidgets import QPushButton for text, handler in (("-", on_decrease), ("+", on_increase)): button = QPushButton(text) button.setFixedSize(24, 24) # Read by the dark style sheet: at this size its side # padding would leave no room for the glyph, and the # button renders blank. See gpype.frontend.theme. button.setProperty("compact", True) button.clicked.connect(_weak_slot(handler)) layout.addWidget(button) def _create_controls(self) -> None: """Build the amplitude and time-window control bar. Inserted above the plot and inside the group box: ``self._layout`` *is* the group box's content layout -- the one the plot widget was added to -- so the bar needs no walk down the widget tree to find its place. Called from :meth:`_update`, which is the GUI thread, once. """ from PySide6.QtWidgets import QFrame, QHBoxLayout, QLabel, QWidget if not ( self._show_amplitude_control or self._show_time_window_control ): return container = QWidget() layout = QHBoxLayout(container) layout.setContentsMargins(8, 3, 8, 3) layout.setSpacing(6) if self._show_amplitude_control: layout.addWidget(QLabel("Amplitude")) self._amplitude_label = QLabel() layout.addWidget(self._amplitude_label) self._add_step_buttons( layout, self._decrease_amplitude, self._increase_amplitude ) self._refresh_amplitude_label() if self._show_amplitude_control and self._show_time_window_control: separator = QFrame() separator.setFrameShape(QFrame.Shape.VLine) separator.setFrameShadow(QFrame.Shadow.Sunken) layout.addWidget(separator) if self._show_time_window_control: layout.addWidget(QLabel("Time Window")) self._time_window_label = QLabel() layout.addWidget(self._time_window_label) self._add_step_buttons( layout, self._decrease_time_window, self._increase_time_window, ) self._refresh_time_window_label() layout.addStretch() self._layout.insertWidget(0, container) def _increase_amplitude(self) -> None: """Step the amplitude scale up, within the declared range.""" self._set_amplitude_limit(self._amplitude_limit + self.AMPLITUDE_STEP) def _decrease_amplitude(self) -> None: """Step the amplitude scale down, within the declared range.""" self._set_amplitude_limit(self._amplitude_limit - self.AMPLITUDE_STEP) def _set_amplitude_limit(self, amplitude_limit) -> None: """Draw at a new amplitude scale, clamped to the declared range. Clamped against the same MIN/MAX the constructor enforces, not against the step size. The prototype this came from stopped one step above zero and had no upper bound at all, so a few clicks took the display to a scale the constructor would have refused. Args: amplitude_limit: Requested scale, in microvolts. """ amplitude_limit = min( self.MAX_AMPLITUDE_LIMIT, max(self.MIN_AMPLITUDE_LIMIT, amplitude_limit), ) if amplitude_limit == self._amplitude_limit: return self._amplitude_limit = amplitude_limit self._refresh_amplitude_label() self._refresh_axis_labels() # Redraw even though no frame has arrived: the scale changed, so # what is on screen is now drawn to the wrong one. self._new_data = True def _increase_time_window(self) -> None: """Step the time window up, within the declared range.""" self._set_time_window(self._time_window + self.TIME_WINDOW_STEP) def _decrease_time_window(self) -> None: """Step the time window down, within the declared range.""" self._set_time_window(self._time_window - self.TIME_WINDOW_STEP) def _set_time_window(self, time_window) -> None: """Draw a new time window, re-cutting the sweep buffers. MIN_TIME_WINDOW and MAX_TIME_WINDOW are *exclusive* -- the constructor rejects a window sitting on either -- so a step is clamped to the first whole second inside them rather than to the bound itself. Args: time_window: Requested window length, in seconds. """ time_window = min( self.MAX_TIME_WINDOW - 1, max(self.MIN_TIME_WINDOW + 1, time_window), ) if time_window == self._time_window: return self._time_window = time_window self._refresh_time_window_label() # None forces the tick labels to be rebuilt on the next frame, # which they otherwise would not be until the second changed. self._last_second = None if self._rate_label is not None: self._rate_label.setPos(time_window, self._channel_count) self._resize_buffers() self._new_data = True def _resize_buffers(self) -> None: """Re-cut the sweep buffers for the time window now drawn. Nothing to do before setup: the buffers do not exist yet, and setup sizes them from the window this leaves behind. The write index restarts, so the elapsed-sample count is banked first. That is what lets the time axis keep counting up across the change instead of jumping back to zero, and it is why the labels turn fractional afterwards -- the sweep origin no longer lands on a whole second. The whole reallocation is held under the lock, because step() writes into these very attributes from the pipeline thread. """ if self._data_buffer is None: return with self._lock: self._elapsed_samples += self._sample_index max_points = int(round(self._time_window * self._sampling_rate)) channel_count = self._data_buffer.shape[1] self._data_buffer = np.zeros((max_points, channel_count)) self._display_buffer = np.zeros((max_points, self._channel_count)) self._max_points = max_points self._t_vec = np.arange(0, max_points) / self._sampling_rate self._sample_index = 0 # The x range follows the time window, which has just changed, # so the cached copy of it is stale. self._xlim_drawn = None self._fractional_ticks = True
[docs] def step(self, data: dict[str, np.ndarray]) -> dict[str, np.ndarray]: """Process incoming data frames and store them in the circular buffer. Called by the pipeline for each new data frame. Handles performance monitoring, circular buffer management, and thread-safe data storage. Args: data: Dictionary containing input data arrays from connected ports. Expected to have PORT_IN key with shape (frame_size, channels). Returns: dict: Empty dictionary (this is a sink node with no outputs). """ self._step_counts += 1 # Calculate data processing rate for performance monitoring t_el = time.time() - self._start_time + 1e-10 self._step_rate = self._step_counts / t_el # The write length comes from the frame that actually arrived, not # from the frame size declared at setup. Sync stacks whatever it # has held into one output frame, so the two differ in normal # operation, and trusting the declaration raised a shape mismatch # that became a permanent error condition naming no cause. block = data[PORT_IN] # Thread-safe data storage in circular buffer. Everything # that reads _max_points or _sample_index is inside the # lock, because a time-window change replaces both buffers # and resets the index from the GUI thread. Computing the # write offset outside it meant a resize landing in between # wrote a frame at an offset into the previous buffer's # geometry -- and, when the window shrank, made `split` # negative and raised the very shape mismatch this method # had already been taught to avoid once. with self._lock: max_points = self._max_points n = block.shape[0] if n > max_points: block = block[-max_points:, :] n = max_points start = self._sample_index % max_points end = start + n if end <= max_points: self._data_buffer[start:end, :] = block else: split = max_points - start self._data_buffer[start:, :] = block[:split] self._data_buffer[: end - max_points, :] = block[split:] self._sample_index = self._sample_index + n # Counted inside the lock so the display cannot see a count # that describes samples it has not been shown yet. self._write_count += n # Signal that new data is available for display update self._new_data = True