add volume graphic, basic stuff works

fastplotlib · clewis7 · Oct 1, 2025 · Apr 12, 2025 · Apr 12, 2025 · Apr 12, 2025
commit 2eeea6ec450f1f41a0b3217c34dc33bc71761db2
@@ -56,6 +56,7 @@
     "subsection_order": ExplicitOrder(
         [
             "../../examples/image",
+            "../../examples/image_volume",
             "../../examples/heatmap",
             "../../examples/image_widget",
             "../../examples/gridplot",

@@ -0,0 +1,2 @@
+Image Volume Examples
+=====================
diff --git a/examples/image_volume/image_volume_ray.py b/examples/image_volume/image_volume_ray.py
@@ -0,0 +1,24 @@
+"""
+Volume Ray mode
+===============
+
+View a volume, uses the fly controller by default so you can fly around the scene using WASD keys and the mouse:
+https://docs.pygfx.org/stable/_autosummary/controllers/pygfx.controllers.FlyController.html#pygfx.controllers.FlyController
+"""
+
+# test_example = false
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import numpy as np
+import fastplotlib as fpl
+import imageio.v3 as iio
+
+voldata = iio.imread("imageio:stent.npz").astype(np.float32)
+
+fig = fpl.Figure(cameras="3d", size=(700, 560))
+
+fig[0, 0].add_image_volume(voldata)
+
+fig.show()
+
+fpl.loop.run()
@@ -18,6 +18,7 @@
 # examples live in themed sub-folders
 example_globs = [
     "image/*.py",
+    "image_volume/*.py",
     "image_widget/*.py",
     "heatmap/*.py",
     "scatter/*.py",

@@ -2,6 +2,7 @@
 from .line import LineGraphic
 from .scatter import ScatterGraphic
 from .image import ImageGraphic
+from .image_volume import ImageVolumeGraphic
 from .text import TextGraphic
 from .line_collection import LineCollection, LineStack
 
@@ -10,6 +11,7 @@
     "LineGraphic",
     "ScatterGraphic",
     "ImageGraphic",
+    "ImageVolumeGraphic",
     "TextGraphic",
     "LineCollection",
     "LineStack",

@@ -53,13 +53,6 @@ class Graphic:
     _features: dict[str, type] = dict()
 
     def __init_subclass__(cls, **kwargs):
-        # set the type of the graphic in lower case like "image", "line_collection", etc.
-        cls.type = (
-            cls.__name__.lower()
-            .replace("graphic", "")
-            .replace("collection", "_collection")
-            .replace("stack", "_stack")
-        )
 
         # set of all features
         cls._features = {

@@ -13,8 +13,12 @@
 )
 
 
-# manages an array of 8192x8192 Textures representing chunks of an image
 class TextureArray(GraphicFeature):
+    """
+    Manages an array of Textures representing chunks of an image.
+
+    Creates multiple pygfx.Texture objects based on the GPU's max texture dimension limit.
+    """
     event_info_spec = [
         {
             "dict key": "key",
@@ -28,13 +32,30 @@ class TextureArray(GraphicFeature):
         },
     ]
 
-    def __init__(self, data, isolated_buffer: bool = True):
+    def __init__(self, data, dim: int, isolated_buffer: bool = True):
+        """
+
+        Parameters
+        ----------
+        dim: int, 2 | 3
+            whether the data array represents a 2D or 3D texture
+
+        """
+        if dim not in (2, 3):
+            raise ValueError("`dim` must be 2 | 3")
+
+        self._dim = dim
+
         super().__init__()
 
         data = self._fix_data(data)
 
         shared = pygfx.renderers.wgpu.get_shared()
-        self._texture_limit_2d = shared.device.limits["max-texture-dimension-2d"]
+
+        if self._dim == 2:
+            self._texture_size_limit = shared.device.limits["max-texture-dimension-2d"]
+        else:
+            self._texture_size_limit = shared.device.limits["max-texture-dimension-3d"]
 
         if isolated_buffer:
             # useful if data is read-only, example: memmaps
@@ -47,26 +68,38 @@ def __init__(self, data, isolated_buffer: bool = True):
         # data start indices for each Texture
         self._row_indices = np.arange(
             0,
-            ceil(self.value.shape[0] / self._texture_limit_2d) * self._texture_limit_2d,
-            self._texture_limit_2d,
+            ceil(self.value.shape[0] / self._texture_size_limit) * self._texture_size_limit,
+            self._texture_size_limit,
         )
         self._col_indices = np.arange(
             0,
-            ceil(self.value.shape[1] / self._texture_limit_2d) * self._texture_limit_2d,
-            self._texture_limit_2d,
+            ceil(self.value.shape[1] / self._texture_size_limit) * self._texture_size_limit,
+            self._texture_size_limit,
         )
 
+        shape = [self.row_indices.size, self.col_indices.size]
+
+        if self._dim == 3:
+            self._zdim_indices = np.arange(
+                0,
+                ceil(self.value.shape[2] / self._texture_size_limit) * self._texture_size_limit,
+                self._texture_size_limit,
+            )
+            shape += [self.zdim_indices.size]
+        else:
+            self._zdim_indices = np.empty(0)
+
         # buffer will be an array of textures
         self._buffer: np.ndarray[pygfx.Texture] = np.empty(
-            shape=(self.row_indices.size, self.col_indices.size), dtype=object
+            shape=shape, dtype=object
         )
 
         self._iter = None
 
         # iterate through each chunk of passed `data`
         # create a pygfx.Texture from this chunk
         for _, buffer_index, data_slice in self:
-            texture = pygfx.Texture(self.value[data_slice], dim=2)
+            texture = pygfx.Texture(self.value[data_slice], dim=self._dim)
 
             self.buffer[buffer_index] = texture
 
@@ -99,6 +132,10 @@ def col_indices(self) -> np.ndarray:
         """
         return self._col_indices
 
+    @property
+    def zdim_indices(self) -> np.ndarray:
+        return self._zdim_indices
+
     @property
     def shared(self) -> int:
         return self._shared
@@ -114,7 +151,11 @@ def _fix_data(self, data):
         return data.astype(np.float32)
 
     def __iter__(self):
-        self._iter = product(enumerate(self.row_indices), enumerate(self.col_indices))
+        if self._dim == 2:
+            self._iter = product(enumerate(self.row_indices), enumerate(self.col_indices))
+        elif self._dim == 3:
+            self._iter = product(enumerate(self.row_indices), enumerate(self.col_indices), enumerate(self.zdim_indices))
+
         return self
 
     def __next__(self) -> tuple[pygfx.Texture, tuple[int, int], tuple[slice, slice]]:
@@ -128,22 +169,32 @@ def __next__(self) -> tuple[pygfx.Texture, tuple[int, int], tuple[slice, slice]]
             | tuple[int, int]: chunk index, i.e corresponding index of ``self.buffer`` array
             | tuple[slice, slice]: data slice of big array in this chunk and Texture
         """
-        (chunk_row, data_row_start), (chunk_col, data_col_start) = next(self._iter)
+        if self._dim == 2:
+            (chunk_row, data_row_start), (chunk_col, data_col_start) = next(self._iter)
+        elif self._dim == 3:
+            (chunk_row, data_row_start), (chunk_col, data_col_start), (chunk_z, data_z_start) = next(self._iter)
 
         # indices for to self.buffer for this chunk
-        chunk_index = (chunk_row, chunk_col)
+        chunk_index = [chunk_row, chunk_col]
+
+        if self._dim == 3:
+            chunk_index += [chunk_z]
 
         # stop indices of big data array for this chunk
-        row_stop = min(self.value.shape[0], data_row_start + self._texture_limit_2d)
-        col_stop = min(self.value.shape[1], data_col_start + self._texture_limit_2d)
+        row_stop = min(self.value.shape[0], data_row_start + self._texture_size_limit)
+        col_stop = min(self.value.shape[1], data_col_start + self._texture_size_limit)
+        if self._dim == 3:
+            z_stop = min(self.value.shape[2], data_z_start + self._texture_size_limit)
 
         # row and column slices that slice the data for this chunk from the big data array
-        data_slice = (slice(data_row_start, row_stop), slice(data_col_start, col_stop))
+        data_slice = [slice(data_row_start, row_stop), slice(data_col_start, col_stop)]
+        if self._dim == 3:
+            data_slice += [slice(data_z_start, z_stop)]
 
         # texture for this chunk
-        texture = self.buffer[chunk_index]
+        texture = self.buffer[tuple(chunk_index)]
 
-        return texture, chunk_index, data_slice
+        return texture, chunk_index, tuple(data_slice)
 
     def __getitem__(self, item):
         return self.value[item]