feat(image_rois): image rois with RPC can be added to Image widget

bec_widgets/cli/client.py

@@ -504,6 +504,204 @@ class BECStatusBox(RPCBase):
         """
 
 
+class BaseROI(RPCBase):
+    """Base class for all Region of Interest (ROI) implementations."""
+
+    @property
+    @rpc_call
+    def label(self) -> "str":
+        """
+        Gets the display name of this ROI.
+
+        Returns:
+            str: The current name of the ROI.
+        """
+
+    @label.setter
+    @rpc_call
+    def label(self) -> "str":
+        """
+        Gets the display name of this ROI.
+
+        Returns:
+            str: The current name of the ROI.
+        """
+
+    @property
+    @rpc_call
+    def line_color(self) -> "str":
+        """
+        Gets the current line color of the ROI.
+
+        Returns:
+            str: The current line color as a string (e.g., hex color code).
+        """
+
+    @line_color.setter
+    @rpc_call
+    def line_color(self) -> "str":
+        """
+        Gets the current line color of the ROI.
+
+        Returns:
+            str: The current line color as a string (e.g., hex color code).
+        """
+
+    @property
+    @rpc_call
+    def line_width(self) -> "int":
+        """
+        Gets the current line width of the ROI.
+
+        Returns:
+            int: The current line width in pixels.
+        """
+
+    @line_width.setter
+    @rpc_call
+    def line_width(self) -> "int":
+        """
+        Gets the current line width of the ROI.
+
+        Returns:
+            int: The current line width in pixels.
+        """
+
+    @rpc_call
+    def get_coordinates(self):
+        """
+        Gets the coordinates that define this ROI's position and shape.
+
+        This is an abstract method that must be implemented by subclasses.
+        Implementations should return either a dictionary with descriptive keys
+        or a tuple of coordinates, depending on the value of self.description.
+
+        Returns:
+            dict or tuple: The coordinates defining the ROI's position and shape.
+
+        Raises:
+            NotImplementedError: This method must be implemented by subclasses.
+        """
+
+    @rpc_call
+    def get_data_from_image(
+        self, image_item: "pg.ImageItem | None" = None, returnMappedCoords: "bool" = False, **kwargs
+    ):
+        """
+        Wrapper around `pyqtgraph.ROI.getArrayRegion`.
+
+        Args:
+            image_item (pg.ImageItem or None): The ImageItem to sample. If None, auto-detects
+                the first `ImageItem` in the same GraphicsScene as this ROI.
+            returnMappedCoords (bool): If True, also returns the coordinate array generated by
+                *getArrayRegion*.
+            **kwargs: Additional keyword arguments passed to *getArrayRegion* or *affineSlice*,
+                such as `axes`, `order`, `shape`, etc.
+
+        Returns:
+            ndarray: Pixel data inside the ROI, or (data, coords) if *returnMappedCoords* is True.
+        """
+
+
+class CircularROI(RPCBase):
+    """Circular Region of Interest with center/diameter tracking and auto-labeling."""
+
+    @property
+    @rpc_call
+    def label(self) -> "str":
+        """
+        Gets the display name of this ROI.
+
+        Returns:
+            str: The current name of the ROI.
+        """
+
+    @label.setter
+    @rpc_call
+    def label(self) -> "str":
+        """
+        Gets the display name of this ROI.
+
+        Returns:
+            str: The current name of the ROI.
+        """
+
+    @property
+    @rpc_call
+    def line_color(self) -> "str":
+        """
+        Gets the current line color of the ROI.
+
+        Returns:
+            str: The current line color as a string (e.g., hex color code).
+        """
+
+    @line_color.setter
+    @rpc_call
+    def line_color(self) -> "str":
+        """
+        Gets the current line color of the ROI.
+
+        Returns:
+            str: The current line color as a string (e.g., hex color code).
+        """
+
+    @property
+    @rpc_call
+    def line_width(self) -> "int":
+        """
+        Gets the current line width of the ROI.
+
+        Returns:
+            int: The current line width in pixels.
+        """
+
+    @line_width.setter
+    @rpc_call
+    def line_width(self) -> "int":
+        """
+        Gets the current line width of the ROI.
+
+        Returns:
+            int: The current line width in pixels.
+        """
+
+    @rpc_call
+    def get_coordinates(self, typed: "bool | None" = None) -> "dict | tuple":
+        """
+        Calculates and returns the coordinates and size of an object, either as a
+        typed dictionary or as a tuple.
+
+        Args:
+            typed (bool | None): If True, returns coordinates as a dictionary. Defaults
+                to None, which utilizes the object's description value.
+
+        Returns:
+            dict: A dictionary with keys 'center_x', 'center_y', 'diameter', and 'radius'
+                if `typed` is True.
+            tuple: A tuple containing (center_x, center_y, diameter, radius) if `typed` is False.
+        """
+
+    @rpc_call
+    def get_data_from_image(
+        self, image_item: "pg.ImageItem | None" = None, returnMappedCoords: "bool" = False, **kwargs
+    ):
+        """
+        Wrapper around `pyqtgraph.ROI.getArrayRegion`.
+
+        Args:
+            image_item (pg.ImageItem or None): The ImageItem to sample. If None, auto-detects
+                the first `ImageItem` in the same GraphicsScene as this ROI.
+            returnMappedCoords (bool): If True, also returns the coordinate array generated by
+                *getArrayRegion*.
+            **kwargs: Additional keyword arguments passed to *getArrayRegion* or *affineSlice*,
+                such as `axes`, `order`, `shape`, etc.
+
+        Returns:
+            ndarray: Pixel data inside the ROI, or (data, coords) if *returnMappedCoords* is True.
+        """
+
+
 class Curve(RPCBase):
     @rpc_call
     def remove(self):
@@ -1215,6 +1413,44 @@ class Image(RPCBase):
         Access the main image item.
         """
 
+    @rpc_call
+    def add_roi(
+        self,
+        kind: "Literal['rect', 'circle']" = "rect",
+        name: "str | None" = None,
+        line_width: "int | None" = 10,
+        pos: "tuple[float, float] | None" = (10, 10),
+        size: "tuple[float, float] | None" = (50, 50),
+        **pg_kwargs,
+    ) -> "RectangularROI | CircularROI":
+        """
+        Add a ROI to the image.
+
+        Args:
+            kind(str): The type of ROI to add. Options are "rect" or "circle".
+            name(str): The name of the ROI.
+            line_width(int): The line width of the ROI.
+            pos(tuple): The position of the ROI.
+            size(tuple): The size of the ROI.
+            **pg_kwargs: Additional arguments for the ROI.
+
+        Returns:
+            RectangularROI | CircularROI: The created ROI object.
+        """
+
+    @rpc_call
+    def remove_roi(self, roi: "int | str"):
+        """
+        Remove an ROI by index or label via the ROIController.
+        """
+
+    @property
+    @rpc_call
+    def rois(self) -> "list[BaseROI]":
+        """
+        Get the list of ROIs.
+        """
+
 
 class ImageItem(RPCBase):
     @property
@@ -2318,6 +2554,105 @@ class PositionerGroup(RPCBase):
         """
 
 
+class RectangularROI(RPCBase):
+    """Defines a rectangular Region of Interest (ROI) with additional functionality."""
+
+    @property
+    @rpc_call
+    def label(self) -> "str":
+        """
+        Gets the display name of this ROI.
+
+        Returns:
+            str: The current name of the ROI.
+        """
+
+    @label.setter
+    @rpc_call
+    def label(self) -> "str":
+        """
+        Gets the display name of this ROI.
+
+        Returns:
+            str: The current name of the ROI.
+        """
+
+    @property
+    @rpc_call
+    def line_color(self) -> "str":
+        """
+        Gets the current line color of the ROI.
+
+        Returns:
+            str: The current line color as a string (e.g., hex color code).
+        """
+
+    @line_color.setter
+    @rpc_call
+    def line_color(self) -> "str":
+        """
+        Gets the current line color of the ROI.
+
+        Returns:
+            str: The current line color as a string (e.g., hex color code).
+        """
+
+    @property
+    @rpc_call
+    def line_width(self) -> "int":
+        """
+        Gets the current line width of the ROI.
+
+        Returns:
+            int: The current line width in pixels.
+        """
+
+    @line_width.setter
+    @rpc_call
+    def line_width(self) -> "int":
+        """
+        Gets the current line width of the ROI.
+
+        Returns:
+            int: The current line width in pixels.
+        """
+
+    @rpc_call
+    def get_coordinates(self, typed: "bool | None" = None) -> "dict | tuple":
+        """
+        Returns the coordinates of a rectangle's corners. Supports returning them
+        as either a dictionary with descriptive keys or a tuple of coordinates.
+
+        Args:
+            typed (bool | None): If True, returns coordinates as a dictionary with
+                descriptive keys. If False, returns them as a tuple. Defaults to
+                the value of `self.description`.
+
+        Returns:
+            dict | tuple: The rectangle's corner coordinates, where the format
+                depends on the `typed` parameter.
+        """
+
+    @rpc_call
+    def get_data_from_image(
+        self, image_item: "pg.ImageItem | None" = None, returnMappedCoords: "bool" = False, **kwargs
+    ):
+        """
+        Wrapper around `pyqtgraph.ROI.getArrayRegion`.
+
+        Args:
+            image_item (pg.ImageItem or None): The ImageItem to sample. If None, auto-detects
+                the first `ImageItem` in the same GraphicsScene as this ROI.
+            returnMappedCoords (bool): If True, also returns the coordinate array generated by
+                *getArrayRegion*.
+            **kwargs: Additional keyword arguments passed to *getArrayRegion* or *affineSlice*,
+                such as `axes`, `order`, `shape`, etc.
+
+        Returns:
+            ndarray: Pixel data inside the ROI, or (data, coords) if *returnMappedCoords* is True.
+        """
+
+
 class ResetButton(RPCBase):
     """A button that resets the scan queue."""