fastplotlib · lkeegan · Jul 21, 2025 · Jul 22, 2025 · Jul 23, 2025 · Jul 23, 2025
@@ -46,6 +46,9 @@ Methods
 
     ScatterGraphic.add_axes
     ScatterGraphic.add_event_handler
+    ScatterGraphic.add_linear_region_selector
+    ScatterGraphic.add_linear_selector
+    ScatterGraphic.add_rectangle_selector
     ScatterGraphic.clear_event_handlers
     ScatterGraphic.remove_event_handler
     ScatterGraphic.rotate

@@ -0,0 +1,66 @@
+"""
+LinearRegionSelectors with ScatterGraphic
+=========================================
+
+Example showing how to use a `LinearRegionSelector` with a scatter plot. We demonstrate two use cases, a horizontal
+LinearRegionSelector which selects along the x-axis and a vertical selector which moves along the y-axis.
+"""
+
+# test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import fastplotlib as fpl
+import numpy as np
+
+# names for out subplots
+names = [
+    ["scatter x", "scatter y"],
+    ["zoomed x region", "zoomed y region"]
+]
+
+# 2 rows, 2 columns
+figure = fpl.Figure(
+    (2, 2),
+    size=(700, 560),
+    names=names,
+)
+
+scatter_x_data = (100*np.random.random_sample(size=(500, 2))).astype(np.float32)
+scatter_y_data = (100*np.random.random_sample(size=(500, 2))).astype(np.float32)
+
+# plot scatter data
+scatter_x = figure[0, 0].add_scatter(scatter_x_data)
+scatter_y = figure[0, 1].add_scatter(scatter_y_data)
+
+# add linear selectors
+selector_x = scatter_x.add_linear_region_selector((0, 100))  # default axis is "x"
+selector_y = scatter_y.add_linear_region_selector(axis="y")
+
+@selector_x.add_event_handler("selection")
+def set_zoom_x(ev):
+    """sets zoomed x selector data"""
+    selected_data = ev.get_selected_data()
+    figure[1, 0].clear()
+    figure[1, 0].add_scatter(selected_data, sizes=10)
+    figure[1, 0].auto_scale()
+
+
+@selector_y.add_event_handler("selection")
+def set_zoom_y(ev):
+    """sets zoomed y selector data"""
+    selected_data = ev.get_selected_data()
+    figure[1, 1].clear()
+    figure[1, 1].add_scatter(selected_data, sizes=10)
+    figure[1, 1].auto_scale()
+
+# set initial selection
+selector_x.selection = (30, 60)
+selector_y.selection = (30, 60)
+
+figure.show(maintain_aspect=False)
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()
@@ -0,0 +1,52 @@
+"""
+Polygon Selectors with ScatterGraphic
+=====================================
+
+Example showing how to use a `PolygonSelector` with a scatter plot.
+"""
+
+# test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import numpy as np
+import fastplotlib as fpl
+
+# create a figure
+figure = fpl.Figure(
+    (1, 2),
+    size=(700, 560),
+    names=["scatter", "zoomed selection"],
+)
+
+xys = (100 * np.random.random_sample(size=(2000, 2))).astype(np.float32)
+
+# add image
+scatter = figure[0, 0].add_scatter(xys, cmap="jet", sizes=4)
+
+# add polygon selector to scatter graphic
+polygon_selector = scatter.add_polygon_selector()
+
+# add event handler to highlight selected indices and display selected data in zoomed plot
+@polygon_selector.add_event_handler("selection")
+def color_indices(ev):
+    figure[0, 1].clear()
+    scatter.cmap = "jet"
+    scatter.sizes = 4
+    ixs = ev.get_selected_indices()
+    if ixs.size == 0:
+        return
+    scatter.colors[ixs] = 'w'
+    scatter.sizes[ixs] = 8
+    figure[0, 1].add_scatter(ev.get_selected_data(), sizes=16)
+    figure[0, 1].auto_scale()
+
+# set initial selection
+polygon_selector.selection = [(50.0, 20.0,0.0), (80.0,80.0,0.0), (20.0, 50.0,0.0), (50.0, 50.0, 0.0), (50.0, 20.0,0.0)]
+
+figure.show()
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()
@@ -0,0 +1,49 @@
+"""
+Rectangle Selectors with ScatterGraphic
+=======================================
+
+Example showing how to use a `RectangleSelector` with a scatter plot.
+"""
+
+# test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import numpy as np
+import fastplotlib as fpl
+
+# create a figure
+figure = fpl.Figure(
+    size=(700, 560)
+)
+
+xys = (100 * np.random.random_sample(size=(200, 2))).astype(np.float32)
+
+# add image
+scatter = figure[0, 0].add_scatter(xys, cmap="jet", sizes=4)
+
+# add rectangle selector to image graphic
+rectangle_selector = scatter.add_rectangle_selector()
+
+# add event handler to highlight selected indices
+@rectangle_selector.add_event_handler("selection")
+def color_indices(ev):
+    scatter.cmap = "jet"
+    scatter.sizes = 4
+    ixs = ev.get_selected_indices()
+    if ixs.size == 0:
+        return
+    scatter.colors[ixs] = 'w'
+    scatter.sizes[ixs] = 8
+
+
+# manually move selector to make a nice gallery image :D
+rectangle_selector.selection = (20, 40, 40, 60)
+
+
+figure.show()
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()
@@ -4,6 +4,8 @@
 
 import pygfx
 from ._base import Graphic
+from .selectors import LinearRegionSelector, LinearSelector, RectangleSelector
+from ..utils import quick_min_max
 from .features import (
     VertexPositions,
     VertexColors,
@@ -147,3 +149,196 @@ def __init__(
 
         self._size_space = SizeSpace(size_space)
         super().__init__(*args, **kwargs)
+
+    def add_linear_selector(
+        self, selection: float = None, axis: str = "x", **kwargs
+    ) -> LinearSelector:
+        """
+        Adds a :class:`.LinearSelector`.
+
+        Selectors are just ``Graphic`` objects, so you can manage, remove, or delete them from a
+        plot area just like any other ``Graphic``.
+
+        Parameters
+        ----------
+        selection: float, optional
+            selected point on the linear selector, by default the first datapoint on the line.
+
+        axis: str, default "x"
+            axis that the selector resides on
+
+        kwargs
+            passed to :class:`.LinearSelector`
+
+        Returns
+        -------
+        LinearSelector
+
+        """
+
+        bounds_init, limits, size, center = self._get_linear_selector_init_args(
+            axis, padding=0
+        )
+
+        if selection is None:
+            selection = bounds_init[0]
+
+        selector = LinearSelector(
+            selection=selection,
+            limits=limits,
+            axis=axis,
+            parent=self,
+            **kwargs,
+        )
+
+        self._plot_area.add_graphic(selector, center=False)
+
+        # place selector above this graphic
+        selector.offset = selector.offset + (0.0, 0.0, self.offset[-1] + 1)
+
+        return selector
+
+    def add_linear_region_selector(
+        self,
+        selection: tuple[float, float] = None,
+        padding: float = 0.0,
+        axis: str = "x",
+        **kwargs,
+    ) -> LinearRegionSelector:
+        """
+        Add a :class:`.LinearRegionSelector`.
+
+        Selectors are just ``Graphic`` objects, so you can manage, remove, or delete them from a
+        plot area just like any other ``Graphic``.
+
+        Parameters
+        ----------
+        selection: (float, float), optional
+            the starting bounds of the linear region selector, computed from data if not provided
+
+        axis: str, default "x"
+            axis that the selector resides on
+
+        padding: float, default 0.0
+            Extra padding to extend the linear region selector along the orthogonal axis to make it easier to interact with.
+
+        kwargs
+            passed to ``LinearRegionSelector``
+
+        Returns
+        -------
+        LinearRegionSelector
+            linear selection graphic
+
+        """
+
+        bounds_init, limits, size, center = self._get_linear_selector_init_args(
+            axis, padding
+        )
+
+        if selection is None:
+            selection = bounds_init
+
+        # create selector
+        selector = LinearRegionSelector(
+            selection=selection,
+            limits=limits,
+            size=size,
+            center=center,
+            axis=axis,
+            parent=self,
+            **kwargs,
+        )
+
+        self._plot_area.add_graphic(selector, center=False)
+
+        # place selector below this graphic
+        selector.offset = selector.offset + (0.0, 0.0, self.offset[-1] - 1)
+
+        # PlotArea manages this for garbage collection etc. just like all other Graphics
+        # so we should only work with a proxy on the user-end
+        return selector
+
+    def add_rectangle_selector(
+        self,
+        selection: tuple[float, float, float, float] = None,
+        **kwargs,
+    ) -> RectangleSelector:
+        """
+        Add a :class:`.RectangleSelector`.
+
+        Selectors are just ``Graphic`` objects, so you can manage, remove, or delete them from a
+        plot area just like any other ``Graphic``.
+
+        Parameters
+        ----------
+        selection: (float, float, float, float), optional
+            initial (xmin, xmax, ymin, ymax) of the selection
+        """
+        # computes args to create selectors
+
+        # remove any nans
+        data = self.data.value[~np.any(np.isnan(self.data.value), axis=1)]
+
+        x_axis_vals = data[:, 0]
+        y_axis_vals = data[:, 1]
+
+        ymin = np.floor(y_axis_vals.min()).astype(int)
+        ymax = np.ceil(y_axis_vals.max()).astype(int)
+        y25p = 0.25 * (ymax - ymin)
+        xmin = np.floor(x_axis_vals.min()).astype(int)
+        xmax = np.ceil(x_axis_vals.max()).astype(int)
+        x25p = 0.25 * (xmax - xmin)
+
+        # default selection is 25% of the image
+        if selection is None:
+            selection = (xmin, xmin + x25p, ymin, ymax)
+
+        # min/max limits include the data + 25% padding in the y-direction
+        limits = (xmin, xmax, ymin - y25p, ymax + y25p)
+
+        selector = RectangleSelector(
+            selection=selection,
+            limits=limits,
+            parent=self,
+            **kwargs,
+        )
+
+        self._plot_area.add_graphic(selector, center=False)
+
+        return selector
+
+    # TODO: this method is a bit of a mess, can refactor later
+    def _get_linear_selector_init_args(
+        self, axis: str, padding
+    ) -> tuple[tuple[float, float], tuple[float, float], float, float]:
+        # computes args to create selectors
+
+        # remove any nans
+        data = self.data.value[~np.any(np.isnan(self.data.value), axis=1)]
+
+        if axis == "x":
+            # xvals
+            axis_vals = data[:, 0]
+
+            # yvals to get size and center
+            magn_vals = data[:, 1]
+        elif axis == "y":
+            axis_vals = data[:, 1]
+            magn_vals = data[:, 0]
+
+        axis_vals_min = np.floor(axis_vals.min()).astype(int)
+        axis_vals_max = np.ceil(axis_vals.max()).astype(int)
+        axis_vals_25p = axis_vals_min + 0.25 * (axis_vals_max - axis_vals_min)
+
+        # default selection is 25% of the image
+        bounds_init = axis_vals_min, axis_vals_25p
+        limits = axis_vals_min, axis_vals_max
+
+        # width or height of selector
+        size = int(np.ptp(magn_vals) * 1.5 + padding)
+
+        # center of selector along the other axis
+        center = sum(quick_min_max(magn_vals)) / 2
+
+        return bounds_init, limits, size, center