fastplotlib · kushalkolar · Jun 29, 2025 · Aug 11, 2025 · Aug 11, 2025 · Aug 17, 2025
@@ -49,7 +49,7 @@ jobs:
       - name: build docs
         run: |
           cd docs
-          RTD_BUILD=1 make html SPHINXOPTS="-W --keep-going"
+          DOCS_BUILD=1 make html SPHINXOPTS="-W --keep-going"
 
       # set environment variable `DOCS_VERSION_DIR` to either the pr-branch name, "dev", or the release version tag
       - name: set output pr

@@ -160,6 +160,7 @@ def __init__(
         self._alpha_mode = AlphaMode(alpha_mode)
         self._visible = Visible(visible)
         self._block_events = False
+        self._block_handlers = list()
 
         self._axes: Axes = None
 
@@ -242,6 +243,11 @@ def block_events(self) -> bool:
     def block_events(self, value: bool):
         self._block_events = value
 
+    @property
+    def block_handlers(self) -> list:
+        """Used to block event handlers for a graphic and prevent recursion."""
+        return self._block_handlers
+
     @property
     def world_object(self) -> pygfx.WorldObject:
         """Associated pygfx WorldObject. Always returns a proxy, real object cannot be accessed directly."""
@@ -370,6 +376,9 @@ def _handle_event(self, callback, event: pygfx.Event):
         if self.block_events:
             return
 
+        if callback in self._block_handlers:
+            return
+
         if event.type in self._features:
             # for feature events
             event._target = self.world_object

@@ -320,7 +320,7 @@ def __repr__(self):
 def block_reentrance(set_value):
     # decorator to block re-entrant set_value methods
     # useful when creating complex, circular, bidirectional event graphs
-    def set_value_wrapper(self: GraphicFeature, graphic_or_key, value):
+    def set_value_wrapper(self: GraphicFeature, graphic_or_key, value, **kwargs):
         """
         wraps GraphicFeature.set_value
 
@@ -336,7 +336,7 @@ def set_value_wrapper(self: GraphicFeature, graphic_or_key, value):
         try:
             # block re-execution of set_value until it has *fully* finished executing
             self._reentrant_block = True
-            set_value(self, graphic_or_key, value)
+            set_value(self, graphic_or_key, value, **kwargs)
         except Exception as exc:
             # raise original exception
             raise exc  # set_value has raised. The line above and the lines 2+ steps below are probably more relevant!

@@ -118,7 +118,7 @@ def axis(self) -> str:
         return self._axis
 
     @block_reentrance
-    def set_value(self, selector, value: Sequence[float]):
+    def set_value(self, selector, value: Sequence[float], *, change: str = "full"):
         """
         Set start, stop range of selector
 
@@ -182,7 +182,9 @@ def set_value(self, selector, value: Sequence[float]):
         if len(self._event_handlers) < 1:
             return
 
-        event = GraphicFeatureEvent(self._property_name, {"value": self.value})
+        event = GraphicFeatureEvent(
+            self._property_name, {"value": self.value, "change": change}
+        )
 
         event.get_selected_indices = selector.get_selected_indices
         event.get_selected_data = selector.get_selected_data

@@ -158,19 +158,26 @@ def __init__(
         self._interpolation = ImageInterpolation(interpolation)
 
         # set map to None for RGB images
-        if self._data.value.ndim > 2:
+        if self._data.value.ndim == 3:
             self._cmap = None
+            self._cmap_interpolation = None
             _map = None
-        else:
+
+        elif self._data.value.ndim == 2:
             # use TextureMap for grayscale images
             self._cmap = ImageCmap(cmap)
             self._cmap_interpolation = ImageCmapInterpolation(cmap_interpolation)
-
             _map = pygfx.TextureMap(
                 self._cmap.texture,
                 filter=self._cmap_interpolation.value,
                 wrap="clamp-to-edge",
             )
+        else:
+            raise ValueError(
+                f"ImageGraphic `data` must have 2 dimensions for grayscale images, or 3 dimensions for RGB(A) images.\n"
+                f"You have passed a a data array with: {self._data.value.ndim} dimensions, "
+                f"and of shape: {self._data.value.shape}"
+            )
 
         # one common material is used for every Texture chunk
         self._material = pygfx.ImageBasicMaterial(
@@ -223,8 +230,6 @@ def cmap(self) -> str | None:
         if self._cmap is not None:
             return self._cmap.value
 
-        return None
-
     @cmap.setter
     def cmap(self, name: str):
         if self.data.value.ndim > 2:
@@ -259,9 +264,10 @@ def interpolation(self, value: str):
         self._interpolation.set_value(self, value)
 
     @property
-    def cmap_interpolation(self) -> str:
-        """cmap interpolation method"""
-        return self._cmap_interpolation.value
+    def cmap_interpolation(self) -> str | None:
+        """cmap interpolation method, 'linear' or 'nearest'. `None` if image is RGB(A)"""
+        if self._cmap_interpolation is not None:
+            return self._cmap_interpolation.value
 
     @cmap_interpolation.setter
     def cmap_interpolation(self, value: str):

@@ -211,16 +211,28 @@ def __init__(
 
         self._interpolation = ImageInterpolation(interpolation)
 
-        # TODO: I'm assuming RGB volume images aren't supported???
-        # use TextureMap for grayscale images
-        self._cmap = ImageCmap(cmap)
-        self._cmap_interpolation = ImageCmapInterpolation(cmap_interpolation)
-
-        self._texture_map = pygfx.TextureMap(
-            self._cmap.texture,
-            filter=self._cmap_interpolation.value,
-            wrap="clamp-to-edge",
-        )
+        if self._data.value.ndim == 4:
+            # set map to None for RGB image volumes
+            self._cmap = None
+            self._texture_map = None
+            self._cmap_interpolation = None
+
+        elif self._data.value.ndim == 3:
+            # use TextureMap for grayscale images
+            self._cmap = ImageCmap(cmap)
+            self._cmap_interpolation = ImageCmapInterpolation(cmap_interpolation)
+            self._texture_map = pygfx.TextureMap(
+                self._cmap.texture,
+                filter=self._cmap_interpolation.value,
+                wrap="clamp-to-edge",
+            )
+        else:
+            raise ValueError(
+                f"ImageVolumeGraphic `data` must have 3 dimensions for grayscale images, "
+                f"or 4 dimensions for RGB(A) images.\n"
+                f"You have passed a a data array with: {self._data.value.ndim} dimensions, "
+                f"and of shape: {self._data.value.shape}"
+            )
 
         self._plane = VolumeSlicePlane(plane)
         self._threshold = VolumeIsoThreshold(threshold)
@@ -282,9 +294,10 @@ def mode(self, mode: str):
         self._mode.set_value(self, mode)
 
     @property
-    def cmap(self) -> str:
+    def cmap(self) -> str | None:
         """Get or set colormap name"""
-        return self._cmap.value
+        if self._cmap is not None:
+            return self._cmap.value
 
     @cmap.setter
     def cmap(self, name: str):
@@ -318,9 +331,10 @@ def interpolation(self, value: str):
         self._interpolation.set_value(self, value)
 
     @property
-    def cmap_interpolation(self) -> str:
+    def cmap_interpolation(self) -> str | None:
         """Get or set the cmap interpolation method"""
-        return self._cmap_interpolation.value
+        if self._cmap_interpolation is not None:
+            return self._cmap_interpolation.value
 
     @cmap_interpolation.setter
     def cmap_interpolation(self, value: str):

@@ -472,9 +472,9 @@ def _move_graphic(self, move_info: MoveInfo):
         if move_info.source == self._edges[0]:
             # change only left or bottom bound
             new_min = min(cur_min + delta, cur_max)
-            self._selection.set_value(self, (new_min, cur_max))
+            self._selection.set_value(self, (new_min, cur_max), change="min")
 
         elif move_info.source == self._edges[1]:
             # change only right or top bound
             new_max = max(cur_max + delta, cur_min)
-            self._selection.set_value(self, (cur_min, new_max))
+            self._selection.set_value(self, (cur_min, new_max), change="max")
@@ -1,13 +1,16 @@
 from contextlib import contextmanager
+from typing import Callable, Iterable
 
 from ._base import Graphic
 
 
 @contextmanager
-def pause_events(*graphics: Graphic):
+def pause_events(*graphics: Graphic, event_handlers: Iterable[Callable] = None):
     """
     Context manager for pausing Graphic events.
 
+    Optionally pass in only specific event handlers which are blocked. Other events for the graphic will not be blocked.
+
     Examples
     --------
 
@@ -30,8 +33,14 @@ def pause_events(*graphics: Graphic):
     original_vals = [g.block_events for g in graphics]
 
     for g in graphics:
-        g.block_events = True
+        if event_handlers is not None:
+            g.block_handlers.extend([e for e in event_handlers])
+        else:
+            g.block_events = True
     yield
 
     for g, value in zip(graphics, original_vals):
-        g.block_events = value
+        if event_handlers is not None:
+            g.block_handlers.clear()
+        else:
+            g.block_events = value
@@ -554,7 +554,7 @@ def show_tooltips(self, val: bool):
 
         if val:
             # register all graphics
-            for subplot in self:
+            for subplot in self._subplots.ravel():
                 for graphic in subplot.graphics:
                     self._tooltip_manager.register(graphic)
 
@@ -572,7 +572,7 @@ def _render(self, draw=True):
 
         # call the animation functions before render
         self._call_animate_functions(self._animate_funcs_pre)
-        for subplot in self:
+        for subplot in self._subplots.ravel():
             subplot._render()
 
         # overlay render pass
@@ -639,14 +639,14 @@ def show(
             sidecar_kwargs = dict()
 
         # flip y-axis if ImageGraphics are present
-        for subplot in self:
+        for subplot in self._subplots.ravel():
             for g in subplot.graphics:
                 if isinstance(g, ImageGraphic):
                     subplot.camera.local.scale_y *= -1
                     break
 
         if autoscale:
-            for subplot in self:
+            for subplot in self._subplots.ravel():
                 if maintain_aspect is None:
                     _maintain_aspect = subplot.camera.maintain_aspect
                 else:
@@ -655,7 +655,7 @@ def show(
 
         # set axes visibility if False
         if not axes_visible:
-            for subplot in self:
+            for subplot in self._subplots.ravel():
                 subplot.axes.visible = False
 
         # parse based on canvas type
@@ -679,15 +679,15 @@ def show(
         elif self.canvas.__class__.__name__ == "OffscreenRenderCanvas":
             # for test and docs gallery screenshots
             self._fpl_reset_layout()
-            for subplot in self:
+            for subplot in self._subplots.ravel():
                 subplot.axes.update_using_camera()
 
                 # render call is blocking only on github actions for some reason,
                 # but not for rtd build, this is a workaround
                 # for CI tests, the render call works if it's in test_examples
                 # but it is necessary for the gallery images too so that's why this check is here
-                if "RTD_BUILD" in os.environ.keys():
-                    if os.environ["RTD_BUILD"] == "1":
+                if "DOCS_BUILD" in os.environ.keys():
+                    if os.environ["DOCS_BUILD"] == "1":
                         self._render()
 
         else:  # assume GLFW
@@ -803,7 +803,7 @@ def clear_animations(self, removal: str = None):
 
     def clear(self):
         """Clear all Subplots"""
-        for subplot in self:
+        for subplot in self._subplots.ravel():
             subplot.clear()
 
     def export_numpy(self, rgb: bool = False) -> np.ndarray:
@@ -962,18 +962,20 @@ def __getitem__(self, index: str | int | tuple[int, int]) -> Subplot:
                     return subplot
             raise IndexError(f"no subplot with given name: {index}")
 
+        if isinstance(index, (int, np.integer)):
+            return self._subplots.ravel()[index]
+
         if isinstance(self.layout, GridLayout):
             return self._subplots[index[0], index[1]]
 
-        return self._subplots[index]
+        raise TypeError(
+            f"Can index figure using <str> subplot name, numerical <int> subplot index, or a "
+            f"tuple[int, int] if the layout is a grid"
+        )
 
     def __iter__(self):
-        self._current_iter = iter(range(len(self)))
-        return self
-
-    def __next__(self) -> Subplot:
-        pos = self._current_iter.__next__()
-        return self._subplots.ravel()[pos]
+        for subplot in self._subplots.ravel():
+            yield subplot
 
     def __len__(self):
         """number of subplots"""
@@ -988,6 +990,6 @@ def __repr__(self):
         return (
             f"fastplotlib.{self.__class__.__name__}"
             f"  Subplots:\n"
-            f"\t{newline.join(subplot.__str__() for subplot in self)}"
+            f"\t{newline.join(subplot.__str__() for subplot in self._subplots.ravel())}"
             f"\n"
         )
@@ -226,7 +226,10 @@ def controller(self, new_controller: str | pygfx.Controller):
         #  pygfx plans on refactoring viewports anyways
         if self.parent is not None:
             if self.parent.__class__.__name__.endswith("Figure"):
-                for subplot in self.parent:
+                # always use figure._subplots.ravel() in internal fastplotlib code
+                # otherwise if we use `for subplot in figure`, this could conflict
+                # with a user's iterator where they are doing `for subplot in figure` !!!
+                for subplot in self.parent._subplots.ravel():
                     if subplot.camera in cameras_list:
                         new_controller.register_events(subplot.viewport)
                         subplot._controller = new_controller