fastplotlib · kushalkolar · Feb 16, 2026 · Jun 29, 2025 · Aug 11, 2025 · Aug 11, 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

@@ -134,5 +134,6 @@
     "numpy": ("https://numpy.org/doc/stable", None),
     "pygfx": ("https://docs.pygfx.org/stable", None),
     "wgpu": ("https://wgpu-py.readthedocs.io/en/latest", None),
+    "rendercanvas": ("https://rendercanvas.readthedocs.io/stable/", None),
     # "fastplotlib": ("https://www.fastplotlib.org/", None),
 }
@@ -56,15 +56,14 @@ For example let's look at ``LineGraphic`` in ``fastplotlib/graphics/line.py``. E
 ``"data", "colors", "cmap", "thickness"`` in addition to properties common to all graphics, such as ``"name", "offset", "rotation", and "visible"``
 
 Now look at the constructor for the ``LineGraphic`` base class ``PositionsGraphic``, it first creates an instance of ``VertexPositions``.
-This is a class that manages vertex positions buffer. For the user, it defines the line data, and provides additional useful functionality.
-It defines the line, and provides additional useful functionality.
+This is a class that manages vertex positions buffer. For the user, it defines the line vertex positions, and provides additional useful functionality.
 For example, every time that the ``data`` is changed, the new data will be marked for upload to the GPU before the next draw.
 In addition, event handlers will be called if any event handlers are registered.
 
-``VertexColors`` behaves similarly, but it can perform additional parsing that can create the colors buffer from different
+``VertexColors`` behaves similarly, but it can perform additional parsing that can create or set the colors buffer from different
 forms of user input. For example if a user runs: ``line_graphic.colors = "blue"``, then ``VertexColors.__setitem__()`` will
-create a buffer that corresponds to what ``pygfx.Color`` thinks is "blue". Users can also take advantage of fancy indexing,
-ex: ``line_graphics.colors[bool_array] = "red"`` 😊
+set the buffer that corresponds to what ``pygfx.Color`` thinks is "blue", i.e the RGBA array `[0, 0, 1, 1]. Users can also take advantage of fancy indexing,
+ex: ``line_graphics.colors[bool_array] = "red"`` 😊 to set the color of specific vertices.
 
 ``LineGraphic`` also has a ``VertexCmap``, this manages the line ``VertexColors`` instance to parse colormaps, for example:
 ``line_graphic.cmap = "jet"`` or even ``line_graphic.cmap[50:] = "viridis"``.
@@ -73,4 +72,4 @@ ex: ``line_graphics.colors[bool_array] = "red"`` 😊
 callbacks to indicate that the graphic has been deleted (for example, removing references to a graphic from a legend).
 
 Other graphics have properties that are relevant to them, for example ``ImageGraphic`` has ``cmap``, ``vmin``, ``vmax``,
-properties unique to images.
+properties unique to images.
@@ -178,6 +178,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
 
@@ -274,6 +275,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."""
@@ -440,6 +446,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

@@ -318,7 +318,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
 
@@ -334,7 +334,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

@@ -162,10 +162,11 @@ def __init__(
         self._cmap_interpolation = ImageCmapInterpolation(cmap_interpolation)
 
         # set map to None for RGB images
-        if self._data.value.ndim > 2:
+        if self._data.value.ndim == 3:
             self._cmap = None
             _map = None
-        else:
+
+        elif self._data.value.ndim == 2:
             # use TextureMap for grayscale images
             self._cmap = ImageCmap(cmap)
 
@@ -174,6 +175,12 @@ def __init__(
                 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(
@@ -275,8 +282,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:
@@ -312,7 +317,7 @@ def interpolation(self, value: str):
 
     @property
     def cmap_interpolation(self) -> str:
-        """cmap interpolation method"""
+        """cmap interpolation method, 'linear' or 'nearest'. Used only for grayscale images"""
         return self._cmap_interpolation.value
 
     @cmap_interpolation.setter

@@ -204,18 +204,24 @@ def __init__(
         self._vmax = ImageVmax(vmax)
 
         self._interpolation = ImageInterpolation(interpolation)
+        self._cmap_interpolation = ImageCmapInterpolation(cmap_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 not in (3, 4):
+            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)
         self._step_size = VolumeIsoStepSize(step_size)
@@ -301,7 +307,7 @@ def mode(self, mode: str):
 
     @property
     def cmap(self) -> str:
-        """Get or set colormap name"""
+        """Get or set colormap name, only used for grayscale images"""
         return self._cmap.value
 
     @cmap.setter

@@ -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
@@ -539,7 +539,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
@@ -606,14 +606,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:
@@ -622,7 +622,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
@@ -646,15 +646,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
@@ -770,7 +770,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:
@@ -929,18 +929,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"""
@@ -955,6 +957,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"
         )
@@ -233,7 +233,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