qplotter 1.6.0b3__py3-none-any.whl

qplot/windows/_plot1d_snap.py

@@ -0,0 +1,608 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import numpy.typing as npt
+import pyqtgraph as pg
+from PyQt6 import QtCore, QtGui
+from PyQt6 import QtWidgets as qtw
+
+from ._commands import command_spec, command_with_status, create_action
+from ._native_transforms import NativePlotDataItem
+
+if TYPE_CHECKING:
+    class _Plot1DSnapBase(qtw.QMainWindow):
+        toolbarCo_ord: qtw.QToolBar
+        snap_to_trace_action: QtGui.QAction | None
+        trace_label: qtw.QLabel | None
+        lines: dict[Any, Any]
+        pos_labels: dict[str, qtw.QLabel]
+        plot: Any
+        right_vb: Any
+        snap_marker: Any
+        _snap_marker_view: Any
+        ds: Any
+        param: Any
+
+        def initLabels(self) -> None: ...
+
+        def initMenu(self) -> None: ...
+
+        def mouseMoved(self, pos: object) -> None: ...
+
+        def register_shortcut(
+                self,
+                action: QtGui.QAction,
+                shortcut: object,
+                status_tip: str | None = None,
+                ) -> None: ...
+
+        @staticmethod
+        def formatNum(num: float, sf: int = 3) -> str: ...
+
+        def _set_cursor_index_label(self, text: str) -> None: ...
+        def _cursor_1d_x_data(self) -> Any: ...
+else:
+    class _Plot1DSnapBase:
+        pass
+
+
+SNAP_TO_TRACE_COMMAND = command_spec("plot.snap_to_trace")
+SNAP_TO_TRACE_SHORTCUT_LABEL = SNAP_TO_TRACE_COMMAND.shortcut_display_text()
+
+
+@dataclass(frozen=True)
+class _SnapTraceSample:
+    x_value: float
+    y_value: float
+    point_number: int
+    x_view_value: float = float("nan")
+    y_view_value: float = float("nan")
+
+
+@dataclass(frozen=True)
+class _LineData:
+    x_view: npt.ArrayLike
+    y_view: npt.ArrayLike
+    x_raw: npt.ArrayLike
+    y_raw: npt.ArrayLike
+
+
+@dataclass(frozen=True)
+class _NearestTracePoint:
+    label: Any
+    x_value: float
+    y_value: float
+    viewbox: Any
+    point_number: int
+    x_view_value: float
+    y_view_value: float
+
+    def __iter__(self):
+        """Retain the historical five-value private-method unpacking API."""
+
+        yield self.label
+        yield self.x_value
+        yield self.y_value
+        yield self.viewbox
+        yield self.point_number
+
+
+def _nearest_trace_sample(
+        x_data: npt.ArrayLike,
+        y_data: npt.ArrayLike,
+        cursor_x: float,
+        cursor_y: float | None = None,
+        ) -> _SnapTraceSample | None:
+    """
+    Return the finite plotted sample nearest to a cursor X coordinate.
+
+    """
+    x_data = np.asarray(x_data, dtype=float)
+    y_data = np.asarray(y_data, dtype=float)
+    count = min(x_data.size, y_data.size)
+    if count == 0:
+        return None
+
+    x_data = x_data[:count]
+    y_data = y_data[:count]
+    finite = np.isfinite(x_data) & np.isfinite(y_data)
+    if not np.any(finite):
+        return None
+
+    finite_indices = np.flatnonzero(finite)
+    x_values = x_data[finite]
+    y_values = y_data[finite]
+    if cursor_y is None:
+        distances = np.abs(x_values - cursor_x)
+    else:
+        distances = np.square(x_values - cursor_x) + np.square(y_values - cursor_y)
+    index = int(np.argmin(distances))
+
+    return _SnapTraceSample(
+        x_value=float(x_values[index]),
+        y_value=float(y_values[index]),
+        point_number=int(finite_indices[index]) + 1,
+        )
+
+
+def _line_is_snap_visible(line: object) -> bool:
+    """
+    Return whether a plotted line should participate in snap selection.
+
+    """
+    is_visible = getattr(line, "isVisible", None)
+    if callable(is_visible):
+        return bool(is_visible())
+    return True
+
+
+def _line_snap_data(line: object | None) -> _LineData | None:
+    """
+    Return full trace samples with aligned physical and view coordinates.
+
+    Downsampling, clipping and dynamic range limiting only change rendering.
+    Neither display positions nor peak/mean aggregates identify raw samples.
+    Apply native processing before log mapping, keeping the resulting arrays
+    aligned for snapping and selection statistics.
+
+    """
+    if line is None or not _line_is_snap_visible(line):
+        return None
+
+    get_data = getattr(line, "getData", None)
+    if not callable(get_data):
+        return None
+
+    view_data = get_data()
+    if view_data is None or view_data[0] is None or view_data[1] is None:
+        return None
+
+    get_original = getattr(line, "getOriginalDataset", None)
+    raw_data = get_original() if callable(get_original) else view_data
+    if raw_data is None or raw_data[0] is None or raw_data[1] is None:
+        raw_data = view_data
+    if callable(get_original):
+        opts = getattr(line, "opts", {})
+        processing = {
+            key: opts.get(key, False)
+            for key in ("subtractMeanMode", "fftMode", "derivativeMode", "phasemapMode")
+        }
+        if any(processing.values()):
+            # Share the rendering mapping, without display reduction.
+            analysis_line = NativePlotDataItem(
+                x=raw_data[0], y=raw_data[1], **processing,
+            )
+            raw_data = analysis_line.getData()
+            if raw_data[0] is None or raw_data[1] is None:
+                return None
+            # Native log-X drops DC within the FFT stage. Phase map runs later
+            # and replaces both coordinates with full input-derived samples,
+            # so that FFT slice must not remove a valid phase-map point here.
+            if (processing["fftMode"] and not processing["phasemapMode"]
+                    and opts.get("logMode", (False, False))[0]):
+                raw_data = (raw_data[0][1:], raw_data[1][1:])
+        view_data = tuple(np.asarray(values, dtype=float) for values in raw_data)
+        log_mode = opts.get("logMode", (False, False))
+        mapped = []
+        for values, logarithmic in zip(view_data, log_mode, strict=True):
+            if logarithmic:
+                with np.errstate(divide="ignore", invalid="ignore"):
+                    values = np.log10(values)
+                values[~np.isfinite(values)] = np.nan
+            mapped.append(values)
+        view_data = tuple(mapped)
+    return _LineData(
+        x_view=view_data[0],
+        y_view=view_data[1],
+        x_raw=raw_data[0],
+        y_raw=raw_data[1],
+    )
+
+
+def _scene_distance_squared(
+        first: QtCore.QPointF,
+        second: QtCore.QPointF,
+        ) -> float:
+    """
+    Return squared distance between two scene points.
+
+    """
+    return (first.x() - second.x()) ** 2 + (first.y() - second.y()) ** 2
+
+
+class Plot1DSnapMixin(_Plot1DSnapBase):
+    """Snap-to-trace cursor readout for 1D plot windows."""
+
+    def initLabels(self):
+        """
+        Sets up coordinate labels and trace snapping command for 1d plots.
+
+        """
+        super().initLabels()
+
+        self.trace_label = qtw.QLabel("")
+        self.trace_label.setMinimumWidth(0)
+        self.toolbarCo_ord.addWidget(self.trace_label)
+        self._update_coordinate_context()
+
+        self.snap_to_trace_action = create_action(
+            SNAP_TO_TRACE_COMMAND,
+            self,
+            text=f"Snap to Trace ({SNAP_TO_TRACE_SHORTCUT_LABEL})",
+            status_tip="Toggle snap-to-trace cursor readout",
+            checkable=True,
+            )
+        self.snap_to_trace_action.setToolTip(
+            "Lock the coordinate readout to the nearest plotted data point"
+            )
+        self.register_shortcut(
+            self.snap_to_trace_action,
+            command_with_status(
+                "plot.snap_to_trace",
+                "Toggle snap-to-trace cursor readout",
+                )
+            )
+        self.snap_to_trace_action.toggled.connect(self._snap_to_trace_toggled)
+
+
+    def initMenu(self):
+        """
+        Adds 1d-specific commands to the plot window menu bar.
+
+        """
+        super().initMenu()
+
+        view_menu = self._menu_by_title("&View")
+        if view_menu is None or self.snap_to_trace_action is None:
+            return
+
+        actions = view_menu.actions()
+        before = actions[0] if actions else None
+        view_menu.insertAction(before, self.snap_to_trace_action)
+        view_menu.insertSeparator(before)
+
+
+    def _menu_by_title(self, title):
+        """
+        Returns the menu matching a top-level menu title.
+
+        """
+        menu_bar = self.menuBar()
+        if menu_bar is None:
+            return None
+
+        for action in menu_bar.actions():
+            if action.text() == title:
+                return action.menu()
+        return None
+
+
+    @QtCore.pyqtSlot(bool)
+    def _snap_to_trace_toggled(self, enabled):
+        """
+        Handles the snap-to-trace toggle state.
+
+        """
+        if not enabled:
+            self._hide_snap_marker()
+            self._clear_snap_report()
+
+
+    @QtCore.pyqtSlot(object)
+    def mouseMoved(self, pos):
+        """
+        Updates the coordinate readout, optionally snapping to a 1d trace.
+
+        """
+        if not (
+            self.snap_to_trace_action is not None
+            and self.snap_to_trace_action.isChecked()
+            ):
+            super().mouseMoved(pos)
+            return
+
+        if not self.plot.sceneBoundingRect().contains(pos):
+            self._hide_snap_marker()
+            self._clear_snap_report()
+            self._set_cursor_index_label("")
+            return
+
+        nearest = self._nearest_trace_point(pos)
+        if nearest is None:
+            self._hide_snap_marker()
+            self._clear_snap_report()
+            self._set_cursor_index_label("")
+            return
+
+        self._set_cursor_index_label(f"[{nearest.point_number - 1}]")
+        self.pos_labels["x"].setText(f"x = {self.formatNum(nearest.x_value)};")
+        self.pos_labels["y"].setText(f"y = {self.formatNum(nearest.y_value)}")
+        self._show_snap_report(nearest.label, nearest.point_number)
+        self._show_snap_marker(
+            nearest.x_view_value,
+            nearest.y_view_value,
+            nearest.viewbox,
+        )
+
+
+    def _show_snap_report(self, label, point_number):
+        """
+        Shows the active run, plotted axes, and snapped point.
+
+        """
+        self._update_coordinate_context(label, point_number)
+
+
+    def _clear_snap_report(self):
+        """
+        Restores the persistent run and axis relationship message.
+
+        """
+        self._update_coordinate_context()
+
+
+    def _update_coordinate_context(self, label=None, point_number=None):
+        """Show ``Run N: measurement vs setpoint`` and optional snap detail."""
+
+        if self.trace_label is None:
+            return
+
+        run_id, vertical, horizontal, tooltip = self._coordinate_context_parts(label)
+        message = f"Run {run_id}: {vertical} vs {horizontal}"
+        if point_number is not None:
+            message += f" (snapped to point {point_number - 1})"
+        self.trace_label.setText(message)
+        self.trace_label.setToolTip(tooltip)
+        self.trace_label.adjustSize()
+        self.trace_label.updateGeometry()
+        self.toolbarCo_ord.updateGeometry()
+
+
+    def _coordinate_context_parts(self, label=None):
+        """Return run and human-readable plotted-axis names for the message."""
+
+        line = self.lines.get(label) if label is not None else self.__dict__.get("line")
+        source = getattr(line, "from_win", self)
+        try:
+            dataset = source.ds
+        except (AttributeError, RuntimeError):
+            dataset = None
+        run_id = getattr(dataset, "run_id", "?")
+
+        host_options = self.__dict__.get("_axis_selection", {})
+        if not host_options:
+            try:
+                host_options = self.axis_options
+            except RuntimeError:
+                host_options = {}
+        horizontal_source = self
+        horizontal_axis = "x"
+        source_axis = "y"
+        if source is not self:
+            axis_order = getattr(line, "choose_from", None)
+            if axis_order is not None and len(axis_order) == 2:
+                horizontal_axis = axis_order[0]
+                source_axis = axis_order[1]
+            horizontal_source = source
+        source_options = (
+            host_options
+            if source is self
+            else getattr(source, "axis_options", {})
+            )
+        horizontal_name = source_options.get(horizontal_axis)
+        if horizontal_name is None:
+            horizontal_name = host_options.get("x", "x")
+            horizontal_source = self
+            horizontal_axis = "x"
+        horizontal = self._parameter_display_name(
+            horizontal_source,
+            horizontal_name,
+            horizontal_axis,
+            )
+        vertical_name = source_options.get(source_axis)
+        if vertical_name is None:
+            try:
+                source_param = source.param
+            except (AttributeError, RuntimeError):
+                source_param = None
+            vertical_name = getattr(source_param, "name", "y")
+        vertical = self._parameter_display_name(
+            source,
+            vertical_name,
+            source_axis,
+            )
+
+        display_label = getattr(self, "_trace_display_label", None)
+        if label is not None and callable(display_label):
+            tooltip = str(display_label(label, line))
+        else:
+            tooltip = str(getattr(source, "label", ""))
+        return run_id, vertical, horizontal, tooltip
+
+
+    @staticmethod
+    def _parameter_display_name(source, name, axis):
+        """Resolve a parameter label without discarding a useful name."""
+
+        param = getattr(source, "param_dict", {}).get(name)
+        if param is None:
+            axis_param = getattr(source, "axis_param", {})
+            candidate = axis_param.get(axis) if isinstance(axis_param, dict) else None
+            if getattr(candidate, "name", name) == name:
+                param = candidate
+        if param is None:
+            candidate = getattr(source, "param", None)
+            if getattr(candidate, "name", None) == name:
+                param = candidate
+        return str(getattr(param, "label", None) or getattr(param, "name", None) or name)
+
+    def _nearest_trace_point(self, scene_pos):
+        """
+        Finds the plotted data point nearest to the mouse position.
+
+        """
+        nearest = None
+        nearest_distance = None
+
+        for label, line in self.lines.items():
+            data = _line_snap_data(line)
+            if data is None:
+                continue
+
+            viewbox = self._viewbox_for_line(line)
+            sample, distance = self._nearest_scene_trace_sample(
+                data.x_view,
+                data.y_view,
+                scene_pos,
+                viewbox,
+                data.x_raw,
+                data.y_raw,
+                )
+            if sample is None:
+                continue
+
+            if nearest_distance is None or distance < nearest_distance:
+                nearest = _NearestTracePoint(
+                    label=label,
+                    x_value=sample.x_value,
+                    y_value=sample.y_value,
+                    viewbox=viewbox,
+                    point_number=sample.point_number,
+                    x_view_value=sample.x_view_value,
+                    y_view_value=sample.y_view_value,
+                    )
+                nearest_distance = distance
+
+        return nearest
+
+
+    @staticmethod
+    def _nearest_scene_trace_sample(
+            x_data,
+            y_data,
+            scene_pos,
+            viewbox,
+            raw_x_data=None,
+            raw_y_data=None,
+            ):
+        """Return the nearest full trace sample with aligned physical values."""
+
+        x_data = np.asarray(x_data, dtype=float)
+        y_data = np.asarray(y_data, dtype=float)
+        if raw_x_data is None:
+            raw_x_data = x_data
+        if raw_y_data is None:
+            raw_y_data = y_data
+        raw_x_data = np.asarray(raw_x_data, dtype=float)
+        raw_y_data = np.asarray(raw_y_data, dtype=float)
+        count = min(
+            x_data.size,
+            y_data.size,
+            raw_x_data.size,
+            raw_y_data.size,
+        )
+        if count == 0:
+            return None, None
+
+        x_data = x_data[:count]
+        y_data = y_data[:count]
+        raw_x_data = raw_x_data[:count]
+        raw_y_data = raw_y_data[:count]
+        finite = (
+            np.isfinite(x_data)
+            & np.isfinite(y_data)
+            & np.isfinite(raw_x_data)
+            & np.isfinite(raw_y_data)
+        )
+        if not np.any(finite):
+            return None, None
+
+        finite_indices = np.flatnonzero(finite)
+        x_values = x_data[finite]
+        y_values = y_data[finite]
+        raw_x_values = raw_x_data[finite]
+        raw_y_values = raw_y_data[finite]
+        # Read the affine coefficients directly: subtracting mapped unit
+        # points loses precision when a narrow sweep is far from zero.
+        # childTransform also updates the matrix after a range/geometry change.
+        transform = viewbox.childTransform() * viewbox.sceneTransform()
+        origin = viewbox.mapSceneToView(scene_pos)
+        scene_origin = viewbox.mapViewToScene(origin)
+        x_offsets = x_values - origin.x()
+        y_offsets = y_values - origin.y()
+        # Work near the pointer so neither the large absolute data coordinates
+        # nor the transform's large translation enter the vectorized mapping.
+        scene_dx = (
+            (scene_origin.x() - scene_pos.x())
+            + x_offsets * transform.m11()
+            + y_offsets * transform.m21()
+            )
+        scene_dy = (
+            (scene_origin.y() - scene_pos.y())
+            + x_offsets * transform.m12()
+            + y_offsets * transform.m22()
+            )
+        distances = np.square(scene_dx) + np.square(scene_dy)
+        index = int(np.argmin(distances))
+        sample = _SnapTraceSample(
+            x_value=float(raw_x_values[index]),
+            y_value=float(raw_y_values[index]),
+            point_number=int(finite_indices[index]) + 1,
+            x_view_value=float(x_values[index]),
+            y_view_value=float(y_values[index]),
+            )
+        return sample, float(distances[index])
+
+
+    def _viewbox_for_line(self, line):
+        """
+        Returns the viewbox that owns a plotted line.
+
+        """
+        get_viewbox = getattr(line, "getViewBox", None)
+        if callable(get_viewbox):
+            viewbox = get_viewbox()
+            if viewbox is not None:
+                return viewbox
+        if getattr(line, "side", "left") == "right" and self.right_vb is not None:
+            return self.right_vb
+
+        return self.plot.vb
+
+
+    def _show_snap_marker(self, x_value, y_value, viewbox):
+        """
+        Places a small marker on the snapped data point.
+
+        """
+        if self.snap_marker is None:
+            self.snap_marker = pg.ScatterPlotItem(
+                symbol="s",
+                size=3,
+                pen=pg.mkPen("k", width=1),
+                brush=pg.mkBrush("w"),
+                )
+            # The marker follows the pointer and is often directly over the
+            # trace. Keep it behind plot lines so the line receives a
+            # double-click before the marker can consume it.
+            self.snap_marker.setZValue(-1)
+
+        if self._snap_marker_view is not viewbox:
+            self._hide_snap_marker()
+            viewbox.addItem(self.snap_marker, ignoreBounds=True)
+            self._snap_marker_view = viewbox
+
+        self.snap_marker.setData([x_value], [y_value])
+
+
+    def _hide_snap_marker(self):
+        """
+        Removes the snap marker from whichever viewbox currently owns it.
+
+        """
+        if self.snap_marker is None or self._snap_marker_view is None:
+            return
+
+        self._snap_marker_view.removeItem(self.snap_marker)
+        self._snap_marker_view = None