fix(image): custom colorbar histogram with custom right click menu for better UX

Author: wyzula-jan

bec_widgets/widgets/plots/image/bec_histogram_lut_item.py

@@ -0,0 +1,330 @@
+"""HistogramLUTItem with a BEC-specific right-click context menu.
+
+pyqtgraph's :class:`~pyqtgraph.HistogramLUTItem` renders the colorbar histogram
+as an ordinary plot, so right-clicking it shows the generic plot context menu
+(``View All``, ``X/Y Axis``, ``Mouse Mode`` …). That is confusing for a colorbar,
+where the only ranges that matter are the image color levels and the histogram
+display range. :class:`BECHistogramLUTItem` replaces that menu on the histogram
+view with a focused one and leaves the gradient (colormap) menu untouched.
+"""
+
+from __future__ import annotations
+
+import pyqtgraph as pg
+from pyqtgraph.widgets.ColorMapMenu import ColorMapMenu
+from qtpy.QtCore import Signal
+from qtpy.QtWidgets import (
+    QDialog,
+    QDialogButtonBox,
+    QFormLayout,
+    QLabel,
+    QLayout,
+    QMenu,
+    QVBoxLayout,
+    QWidget,
+)
+
+from bec_widgets.widgets.utility.spinbox.decimal_spinbox import BECSpinBox
+
+
+class RangeDialog(QDialog):
+    """
+    Modal dialog to enter a ``(min, max)`` floating point range.
+    """
+
+    def __init__(
+        self,
+        parent: QWidget | None = None,
+        *,
+        title: str,
+        label: str,
+        vmin: float,
+        vmax: float,
+        decimals: int = 4,
+    ) -> None:
+        """
+        Initialize the range dialog.
+
+        Args:
+            parent (QWidget | None): The parent widget the dialog is modal to.
+            title (str): The window title of the dialog.
+            label (str): A description shown above the inputs. If empty, no label is shown.
+            vmin (float): The initial value of the minimum spin box.
+            vmax (float): The initial value of the maximum spin box.
+            decimals (int): The number of decimals shown in both spin boxes.
+        """
+        super().__init__(parent=parent)
+        self.setWindowTitle(title)
+        self.setModal(True)
+
+        layout = QVBoxLayout(self)
+        # Fixed-size, non-resizable dialog that hugs its contents.
+        layout.setSizeConstraint(QLayout.SizeConstraint.SetFixedSize)
+        if label:
+            layout.addWidget(QLabel(label))
+
+        form = QFormLayout()
+        self.min_spinbox = BECSpinBox(parent=self)
+        self.max_spinbox = BECSpinBox(parent=self)
+        for spinbox, value in ((self.min_spinbox, vmin), (self.max_spinbox, vmax)):
+            spinbox.setDecimals(decimals)
+            spinbox.setValue(float(value))
+        form.addRow("Minimum:", self.min_spinbox)
+        form.addRow("Maximum:", self.max_spinbox)
+        layout.addLayout(form)
+
+        self.button_box = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel, parent=self
+        )
+        self.button_box.accepted.connect(self.accept)
+        self.button_box.rejected.connect(self.reject)
+        layout.addWidget(self.button_box)
+
+    def get_range(self) -> tuple[float, float]:
+        """
+        Return the entered range, ordered so that ``min <= max``.
+
+        Returns:
+            tuple[float, float]: The (minimum, maximum) values entered by the user.
+        """
+        low, high = self.min_spinbox.value(), self.max_spinbox.value()
+        return (low, high) if low <= high else (high, low)
+
+    @classmethod
+    def get_new_range(
+        cls,
+        parent: QWidget | None,
+        *,
+        title: str,
+        label: str,
+        vmin: float,
+        vmax: float,
+        decimals: int = 4,
+    ) -> tuple[float, float] | None:
+        """
+        Show the dialog modally and return the new range.
+
+        Args:
+            parent (QWidget | None): The parent widget the dialog is modal to.
+            title (str): The window title of the dialog.
+            label (str): A description shown above the inputs.
+            vmin (float): The initial value of the minimum spin box.
+            vmax (float): The initial value of the maximum spin box.
+            decimals (int): The number of decimals shown in both spin boxes.
+
+        Returns:
+            tuple[float, float] | None: The new (min, max) range, or None if cancelled.
+        """
+        dialog = cls(parent, title=title, label=label, vmin=vmin, vmax=vmax, decimals=decimals)
+        try:
+            if dialog.exec() == QDialog.DialogCode.Accepted:
+                return dialog.get_range()
+            return None
+        finally:
+            dialog.deleteLater()
+
+
+class BECHistogramLUTItem(pg.HistogramLUTItem):
+    """
+    :class:`~pyqtgraph.HistogramLUTItem` with a BEC-specific context menu.
+
+    The default pyqtgraph context menu on the histogram view is replaced with one
+    exposing the controls that matter for a colorbar:
+
+    * **Colormap** -- a submenu (pyqtgraph's :class:`~pyqtgraph.widgets.ColorMapMenu.ColorMapMenu`)
+      to pick the image colormap. The choice is emitted through
+      :attr:`sigColorMapChangeRequested` so the owning image widget applies it through
+      its usual colormap handling (config + multi-layer sync + colorbar).
+    * **Image scaling (levels)** -- the ``LinearRegionItem`` mapping data values to
+      colors. Changes are emitted through :attr:`sigColorLevelsChangeRequested` and
+      :attr:`sigAutoLevelsRequested` so the owning image widget keeps autorange and
+      multi-layer state consistent (rather than mutating levels here directly).
+    * **Histogram display range** -- the visible range of the histogram plot, applied
+      directly via :meth:`~pyqtgraph.HistogramLUTItem.setHistogramRange` /
+      :meth:`~pyqtgraph.HistogramLUTItem.autoHistogramRange`.
+
+    The gradient (colormap) context menu on the right edge is left untouched.
+    """
+
+    #: Emitted with the chosen colormap name when the user picks one from the menu.
+    sigColorMapChangeRequested = Signal(str)
+    #: Emitted with ``(vmin, vmax)`` when the user sets explicit color levels.
+    sigColorLevelsChangeRequested = Signal(tuple)
+    #: Emitted when the user requests autoscaling of the color levels.
+    sigAutoLevelsRequested = Signal()
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._bec_menu: QMenu | None = None
+        self._colormap_menu: ColorMapMenu | None = None
+        self._cleaned_up = False
+        self._install_bec_context_menu()
+
+    ################################################################################
+    # Context menu
+
+    def _install_bec_context_menu(self) -> None:
+        """
+        Build the BEC menu and route the histogram view right-clicks to it.
+        """
+        menu = QMenu()
+
+        menu.addSection("Colormap")
+        self._colormap_menu = ColorMapMenu(showColorMapSubMenus=True)
+        self._colormap_menu.setTitle("Select colormap")
+        self._colormap_menu.sigColorMapTriggered.connect(self._on_colormap_triggered)
+        menu.addMenu(self._colormap_menu)
+
+        menu.addSection("Image scaling (levels)")
+        set_levels = menu.addAction("Set levels…")
+        set_levels.setToolTip("Set the data range mapped to the colormap (image scaling).")
+        set_levels.triggered.connect(self._open_levels_dialog)
+        auto_levels = menu.addAction("Autoscale levels")
+        auto_levels.triggered.connect(self.sigAutoLevelsRequested)
+
+        menu.addSection("Histogram display range")
+        set_hist = menu.addAction("Set histogram range…")
+        set_hist.setToolTip("Set the visible range of the histogram plot.")
+        set_hist.triggered.connect(self._open_histogram_range_dialog)
+        reset_hist = menu.addAction("Reset histogram range")
+        reset_hist.triggered.connect(self.autoHistogramRange)
+
+        self._bec_menu = menu
+
+        # Route right-clicks on the histogram ViewBox to the BEC menu only. The
+        # original ViewBoxMenu (self.vb.menu) is left in place but never shown, so
+        # internal pyqtgraph calls such as updateViewLists() keep working.
+        vb = self.vb
+        vb.getMenu = self._vb_get_menu
+        vb.getContextMenus = self._vb_get_context_menus
+        vb.raiseContextMenu = self._vb_raise_context_menu
+
+    def _vb_get_menu(self, ev):
+        """
+        Return the BEC menu instead of the ViewBox's default menu.
+
+        Args:
+            ev: The mouse event that requested the menu (unused).
+
+        Returns:
+            QMenu | None: The BEC context menu.
+        """
+        return self._bec_menu
+
+    def _vb_get_context_menus(self, event):
+        """
+        Return the BEC menu actions for aggregation into child-item menus.
+
+        Args:
+            event: The mouse event that requested the menu (unused).
+
+        Returns:
+            list: The actions of the BEC context menu, or an empty list.
+        """
+        return self._bec_menu.actions() if self._bec_menu is not None else []
+
+    def _vb_raise_context_menu(self, ev):
+        """
+        Pop up the BEC menu at the event position.
+
+        Args:
+            ev: The mouse event that triggered the context menu.
+        """
+        if self._bec_menu is not None:
+            self._bec_menu.popup(ev.screenPos().toPoint())
+
+    def _on_colormap_triggered(self, cmap) -> None:
+        """
+        Forward a colormap chosen in the submenu as a name on the BEC signal.
+
+        Args:
+            cmap (pyqtgraph.ColorMap): The colormap selected in the submenu.
+        """
+        name = getattr(cmap, "name", None)
+        if name:
+            self.sigColorMapChangeRequested.emit(name)
+
+    ################################################################################
+    # Actions
+
+    def _dialog_parent(self) -> QWidget | None:
+        """
+        Return a QWidget to parent modal dialogs to (the host graphics view).
+
+        Returns:
+            QWidget | None: The graphics view hosting the item, or None if unavailable.
+        """
+        scene = self.scene()
+        if scene is not None:
+            views = scene.views()
+            if views:
+                return views[0]
+        return None
+
+    def _open_levels_dialog(self) -> None:
+        """
+        Open the dialog to set the image color levels (image scaling).
+        """
+        vmin, vmax = (float(x) for x in self.getLevels())
+        new_range = RangeDialog.get_new_range(
+            self._dialog_parent(),
+            title="Set color levels",
+            label="Data values mapped to the colormap (image scaling).",
+            vmin=vmin,
+            vmax=vmax,
+        )
+        if new_range is not None:
+            self.sigColorLevelsChangeRequested.emit(new_range)
+
+    def _open_histogram_range_dialog(self) -> None:
+        """
+        Open the dialog to set the histogram's display range.
+        """
+        vmin, vmax = (float(x) for x in self.getHistogramRange())
+        new_range = RangeDialog.get_new_range(
+            self._dialog_parent(),
+            title="Set histogram range",
+            label="Visible range of the histogram plot.",
+            vmin=vmin,
+            vmax=vmax,
+        )
+        if new_range is not None:
+            self.setHistogramRange(*new_range)
+
+    ################################################################################
+    # Cleanup
+
+    def cleanup(self) -> None:
+        """
+        Tear down the BEC menu and the inherited pyqtgraph menus/dialogs.
+
+        ``HistogramLUTItem`` owns several parentless top-level widgets (the ViewBox
+        menu, the gradient ColorMapMenu and its QColorDialog). They must be closed
+        explicitly, otherwise they linger as leaked top-level widgets.
+        """
+        if self._cleaned_up:
+            return
+        self._cleaned_up = True
+
+        # Restore the patched ViewBox context-menu methods.
+        vb_dict = self.vb.__dict__
+        for name in ("getMenu", "getContextMenus", "raiseContextMenu"):
+            vb_dict.pop(name, None)
+
+        # Tear down the BEC context menu and its colormap submenu.
+        if self._colormap_menu is not None:
+            self._colormap_menu.close()
+            self._colormap_menu.deleteLater()
+            self._colormap_menu = None
+        if self._bec_menu is not None:
+            self._bec_menu.close()
+            self._bec_menu.deleteLater()
+            self._bec_menu = None
+
+        # Tear down the inherited pyqtgraph menus and dialogs.
+        self.vb.menu.close()
+        self.vb.menu.deleteLater()
+        self.gradient.menu.close()
+        self.gradient.menu.deleteLater()
+        self.gradient.colorDialog.close()
+        self.gradient.colorDialog.deleteLater()

bec_widgets/widgets/plots/image/image_base.py

@@ -14,6 +14,7 @@
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 from bec_widgets.utils.side_panel import SidePanel
 from bec_widgets.utils.toolbars.actions import MaterialIconAction, SwitchableToolBarAction
+from bec_widgets.widgets.plots.image.bec_histogram_lut_item import BECHistogramLUTItem
 from bec_widgets.widgets.plots.image.image_item import ImageItem
 from bec_widgets.widgets.plots.image.image_roi_plot import ImageROIPlot
 from bec_widgets.widgets.plots.image.setting_widgets.image_roi_tree import ROIPropertyTree
@@ -471,11 +472,15 @@ def disable_autorange():
                 self.config.color_bar = "simple"
 
             elif style == "full":
-                self._color_bar = pg.HistogramLUTItem()
+                self._color_bar = BECHistogramLUTItem()
                 self._color_bar.setImageItem(self.layer_manager["main"].image)
                 self.config.color_bar = "full"
                 self._apply_colormap_to_colorbar(self.config.color_map)
                 self._color_bar.sigLevelsChanged.connect(disable_autorange)
+                # Custom colorbar context menu (replaces pyqtgraph's default plot menu).
+                self._color_bar.sigColorMapChangeRequested.connect(self._set_colormap_from_menu)
+                self._color_bar.sigColorLevelsChangeRequested.connect(self._set_vrange_from_menu)
+                self._color_bar.sigAutoLevelsRequested.connect(self._autorange_from_menu)
 
             self.plot_widget.addItem(self._color_bar, row=0, col=1)
         else:
@@ -837,6 +842,21 @@ def _set_vrange(self, value: tuple | list | QPointF, disable_autorange: bool = T
 
         # self.toolbar.components.get_action("image_autorange").set_state_all(False)
 
+    @SafeSlot(str)
+    def _set_colormap_from_menu(self, color_map: str):
+        """Apply a colormap chosen from the colorbar context menu."""
+        self.color_map = color_map
+
+    @SafeSlot(object)
+    def _set_vrange_from_menu(self, vrange: tuple[float, float]):
+        """Apply explicit color levels requested from the colorbar context menu."""
+        self._set_vrange(vrange, disable_autorange=True)
+
+    @SafeSlot()
+    def _autorange_from_menu(self):
+        """Enable autorange (current mode) from the colorbar context menu."""
+        self.autorange = True
+
     @property
     def v_min(self) -> float:
         """
@@ -1032,6 +1052,10 @@ def cleanup_histogram_lut_item(histogram_lut_item: pg.HistogramLUTItem):
         Args:
             histogram_lut_item(pg.HistogramLUTItem): The HistogramLUTItem to clean up.
         """
+        if isinstance(histogram_lut_item, BECHistogramLUTItem):
+            histogram_lut_item.cleanup()
+            return
+
         histogram_lut_item.vb.menu.close()
         histogram_lut_item.vb.menu.deleteLater()