optimized array subsampling (#721)

FlynnOConnell · kushalkolar · web-flow · commit 718c98c3007f · 2025-04-10T14:34:08.000-04:00
* add 4D case with a single z-plane

* add subsample_array function

* use new subsample_array function

* remove redundant target_elements from subsample

* import utils from __all__

* rename subsample vars using standard numpy names

* subsample max_items -&gt; max_size

* largest bytesize -&gt; largest array size, lowercase errrrything

* use subsample_array in quick_min_max

* make 1e6 int

* update png from artifact (imgui-screenshots)

* fix subsample array

* bring back original image_widget_grid

* Update functions.py

* revert image_widget_grid from regenerate

* hopefully the correct screenshot

* black

* replace iw-zfish-grid-qreplace nb-iw-zfish-grid-init-mw5 to see

* replace nb-image-widget screenshots

* force git to refresh

* nb-iw from regen screenshots

* plzplzplzplzplz work

---------

Co-authored-by: Kushal Kolar &lt;kushalkolar@gmail.com&gt;
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-0-reset.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-0-reset.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6c9b898259fc965452ef0b6ff53ac7fa41196826c6e27b6b5d417d33fb352051
-size 112399
+oid sha256:d3f5a721456b5a54e819fc987b8fa1f61d638f578339a7332ad46a22e7aa8fc0
+size 112674
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-0.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-0.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6c9b898259fc965452ef0b6ff53ac7fa41196826c6e27b6b5d417d33fb352051
-size 112399
+oid sha256:d3f5a721456b5a54e819fc987b8fa1f61d638f578339a7332ad46a22e7aa8fc0
+size 112674
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-279.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-279.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b9cbc2a6916c7518d40812a13276270eb1acfc596f3e6e02e98a6a5185da03a4
-size 132971
+oid sha256:4511a28e728af412f5006bb456f133aea1fdc9c1922c3174f127c79d9878401d
+size 133635
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-max-33.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-max-33.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:070748e90bd230a01d3ae7c6d6487815926b0158888a52db272356dc8b0a89d7
-size 119453
+oid sha256:c6910106cd799a4327a6650edbc956ddb9b6a489760b86b279c593575ae805b8
+size 120114
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-mean-13.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-mean-13.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b24450ccf1f8cf902b8e37e73907186f37a6495f227dcbd5ec53f75c52125f56
-size 105213
+oid sha256:8233dfc429a7fefe96f0fdb89eb2c57188b7963c16db5d1d08f7faefb45d8cb7
+size 105755
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-mean-33.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-mean-33.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:3dfc8e978eddf08d1ed32e16fbf93c037ccdf5f7349180dcda54578a8c9e1a18
-size 97359
+oid sha256:a4af684cdaec8f98081862eb8a377cd419efec64cdf08b662a456276b78f1fb5
+size 98091
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-reset.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-50-window-reset.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:00130242d3f199926604df16dda70a062071f002566a8056e4794805f29adfde
-size 118044
+oid sha256:133dfe6b0028dda6248df1afde1288c57625be99b25c8224673597de4d4f70fc
+size 118588
diff --git a/examples/notebooks/screenshots/nb-image-widget-movie-single-50.png b/examples/notebooks/screenshots/nb-image-widget-movie-single-50.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:00130242d3f199926604df16dda70a062071f002566a8056e4794805f29adfde
-size 118044
+oid sha256:133dfe6b0028dda6248df1afde1288c57625be99b25c8224673597de4d4f70fc
+size 118588
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-frame-apply-gaussian.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-frame-apply-gaussian.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:70c7738ed303f5a3e19271e8dfc12ab857a6f3aff767bdbecb485b763a09913e
-size 55584
+oid sha256:87a3947d6c59c7f67acca25911e0ab93ddc9231a8c3060d2fffe3c53f39055f2
+size 62263
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-frame-apply-reset.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-frame-apply-reset.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:66a435e45dc4643135633115af2eeaf70761e408a94d70d94d80c14141574528
-size 69343
+oid sha256:b57c65974362d258ec7be8de391c41d7909ed260b92411f4b0ed8ed03b886a29
+size 73040
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-max-window-13.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-max-window-13.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:731f225fa2de3457956b2095d1cc539734983d041b13d6ad1a1f9d8e7ebfa4bc
-size 115239
+oid sha256:008381b267ae26e8693ae51e7a4fabc464288ec8aa911ff3a1deb37543cc4fbe
+size 115543
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-mean-window-13.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-mean-window-13.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:7e2d70159ac47c004acb022b3a669e7bd307299ddd590b83c08854b0dba27b70
-size 93885
+oid sha256:fedfec781724d4731f8cc34ffc39388d14dc60dad4a9fae9ff56625edf11f87a
+size 94178
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-mean-window-5.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50-mean-window-5.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:1756783ab90435b46ded650033cf29ac36d2b4380744bf312caa2813267f7f38
-size 89813
+oid sha256:08e8379187754fa14f360ed54f2ed8cf61b3df71a8b6f2e95ff1ed27aa435d60
+size 90105
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-50.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:a35e2e4b892b55f5d2500f895951f6a0289a2df3b69cf12f59409bbc091d1caf
-size 72810
+oid sha256:b57c65974362d258ec7be8de391c41d7909ed260b92411f4b0ed8ed03b886a29
+size 73040
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-frame-99.png b/examples/notebooks/screenshots/nb-image-widget-zfish-frame-99.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:3bdb0ed864c8a6f2118cfe0d29476f61c54576f7b8e041f3c3a895ba0a440c05
-size 65039
+oid sha256:848e89e38b9b5ef97d6bb4b301c0ae10cc29f438518721663ae52fa42f492408
+size 65267
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-frame-apply-gaussian.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-frame-apply-gaussian.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:7ae7c86bee3a30bde6cfa44e1e583e6dfd8de6bb29e7c86cea9141ae30637b4a
-size 80627
+oid sha256:17cd05ae14cacdef6aa1eca3544246b814ef21762a33f6e785f6d621ea30ff96
+size 80570
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-frame-apply-reset.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-frame-apply-reset.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b51a5d26f2408748e59e3ee481735694f8f376539b50deb2b5c5a864b7de1079
-size 105581
+oid sha256:a673fa1ffa6f746ab9f462b4d592492ec02bfdd3fb53bdf1f71fb9427f8d6d23
+size 105798
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-max-window-13.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-max-window-13.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:e854f7f2fdaeeac6c8358f94a33698b5794c0f6c55b240d384e8c6d51fbfb0ff
-size 143301
+oid sha256:446d54cea3d54b0fd92b70abcc090cfee30b19454dce118d9875fbeb8b40b4a8
+size 141294
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-mean-window-13.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-mean-window-13.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:c8c8d3c59c145a4096deceabc71775a03e5e121e82509590787c768944d155bd
-size 110744
+oid sha256:99d3706d5574a1236264f556eb3ce6d71e81b65bd8dcce1c1415e5f139316c23
+size 107894
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-mean-window-5.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50-mean-window-5.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:c4b4af7b99cad95ea3f688af8633de24b6602bd700cb244f93c28718af2e1e85
-size 114982
+oid sha256:ffa17fc1b71c5146cae88493ed40c606dd0a99f3e10f3827ac349d5a5d6f6108
+size 112702
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-50.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6d28a4be4c76d5c0da5f5767b169acf7048a268b010f33f96829a5de7f06fd7d
-size 107477
+oid sha256:a673fa1ffa6f746ab9f462b4d592492ec02bfdd3fb53bdf1f71fb9427f8d6d23
+size 105798
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-99.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-frame-99.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:30dba982c9a605a7a3c0f2fa6d8cdf0df4160b2913a95b26ffdb6b04ead12add
-size 104603
+oid sha256:4d3e88eee05bc68dd17918197602fb5c0a959ad74a4f592aea4514e570d29232
+size 103431
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-init-mean-window-5.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-init-mean-window-5.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:e431229806ee32a78fb9313a09af20829c27799798232193feab1723b66b1bca
-size 112646
+oid sha256:272156c4261bba40eba92f953a0f5078ad8ff2aa80f06a53f73a3572eb537dd5
+size 111155
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-set_data-reset-indices-false.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-set_data-reset-indices-false.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:a8e899b48881e3eb9200cc4e776db1f865b0911c340c06d4009b3ae12aa1fc85
-size 105421
+oid sha256:8203f859fe54e2b59a143a9a569c2854640b1501b9ab4f8512520bbf73dae3c6
+size 105658
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-grid-set_data-reset-indices-true.png b/examples/notebooks/screenshots/nb-image-widget-zfish-grid-set_data-reset-indices-true.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:93933e7ba5f791072df2934c94a782e39ed97f7db5b55c5d71c8c5bbfc69d800
-size 106360
+oid sha256:8ca187ba67e7928c8f96b1f9a0a18bec65f81352701e60c33d47aaadb2756d5c
+size 106446
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-init-mean-window-5.png b/examples/notebooks/screenshots/nb-image-widget-zfish-init-mean-window-5.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:bf38b2af1ceb372cd0949d42c027acb5fcc4c6b9a8f38c5aacdce1cd14e290fe
-size 78533
+oid sha256:f42367c833a23d3fe10c6fb0d754338c12a30288d9769ad3f8b1159505abf8ff
+size 78796
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-mixed-rgb-cockatoo-frame-50.png b/examples/notebooks/screenshots/nb-image-widget-zfish-mixed-rgb-cockatoo-frame-50.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:ff462d24820f0bdd509e58267071fa956b5c863b8b8d66fea061c5253b7557cf
-size 113926
+oid sha256:cb99cd81a18fa2f8986c5f00071c45dc778c8aa177f4b02dca6bc5fab122b054
+size 114825
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-mixed-rgb-cockatoo-set-data.png b/examples/notebooks/screenshots/nb-image-widget-zfish-mixed-rgb-cockatoo-set-data.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:2b8fd14f8e8a90c3cd3fbb84a00d50b1b826b596d64dfae4a5ea1bab0687d906
-size 110829
+oid sha256:31b2b92b9d983950b58b90a09f16199740e35a0737fc1b18904f507ea322d8f2
+size 111118
diff --git a/examples/notebooks/screenshots/nb-image-widget-zfish-mixed-rgb-cockatoo-windowrgb.png b/examples/notebooks/screenshots/nb-image-widget-zfish-mixed-rgb-cockatoo-windowrgb.png
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d88c64b716d19a3978bd60f8d75ffe09e022183381898fa1c48b77598be8fb7c
-size 111193
+oid sha256:0fb724e005c6e081ae3bf235e155f3f526c3480facac7479d9b9452aae81baf0
+size 111437
diff --git a/examples/screenshots/image_widget_grid.png b/examples/screenshots/image_widget_grid.png
@@ -1,3 +1,4 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:306977f7eebdb652828ba425d73b6018e97c100f3cf8f3cbaa0244ffb6c040a3
-size 249103
+
+oid sha256:430cd0ee5c05221c42073345480acbeee672c299311f239dc0790a9495d0d758
+size 248046
diff --git a/fastplotlib/tools/_histogram_lut.py b/fastplotlib/tools/_histogram_lut.py
@@ -5,6 +5,7 @@
 
 import pygfx
 
+from ..utils import subsample_array
 from ..graphics import LineGraphic, ImageGraphic, TextGraphic
 from ..graphics.utils import pause_events
 from ..graphics._base import Graphic
@@ -193,28 +194,10 @@ def _fpl_add_plot_area_hook(self, plot_area):
         self._plot_area.controller.enabled = True
 
     def _calculate_histogram(self, data):
-        if data.ndim > 2:
-            # subsample to max of 500 x 100 x 100,
-            # np.histogram takes ~30ms with this size on a 8 core Ryzen laptop
-            # dim0 is usually time, allow max of 500 timepoints
-            ss0 = max(1, int(data.shape[0] / 500))  # max to prevent step = 0
-            # allow max of 100 for x and y if ndim > 2
-            ss1 = max(1, int(data.shape[1] / 100))
-            ss2 = max(1, int(data.shape[2] / 100))
 
-            data_ss = data[::ss0, ::ss1, ::ss2]
-
-            hist, edges = np.histogram(data_ss, bins=self._nbins)
-
-        else:
-            # allow max of 1000 x 1000
-            # this takes ~4ms on a 8 core Ryzen laptop
-            ss0 = max(1, int(data.shape[0] / 1_000))
-            ss1 = max(1, int(data.shape[1] / 1_000))
-
-            data_ss = data[::ss0, ::ss1]
-
-            hist, edges = np.histogram(data_ss, bins=self._nbins)
+        # get a subsampled view of this array
+        data_ss = subsample_array(data, max_size=int(1e6))  # 1e6 is default
+        hist, edges = np.histogram(data_ss, bins=self._nbins)
 
         # used if data ptp <= 10 because event things get weird
         # with tiny world objects due to floating point error
diff --git a/fastplotlib/utils/functions.py b/fastplotlib/utils/functions.py
@@ -267,7 +267,7 @@ def make_colors_dict(labels: Sequence, cmap: str, **kwargs) -> OrderedDict:
     return OrderedDict(zip(labels, colors))
 
 
-def quick_min_max(data: np.ndarray) -> tuple[float, float]:
+def quick_min_max(data: np.ndarray, max_size=1e6) -> tuple[float, float]:
     """
     Adapted from pyqtgraph.ImageView.
     Estimate the min/max values of *data* by subsampling.
@@ -276,6 +276,9 @@ def quick_min_max(data: np.ndarray) -> tuple[float, float]:
     ----------
     data: np.ndarray or array-like with `min` and `max` attributes
 
+    max_size : int, optional
+        largest array size allowed in the subsampled array. Default is 1e6.
+
     Returns
     -------
     (float, float)
@@ -289,11 +292,7 @@ def quick_min_max(data: np.ndarray) -> tuple[float, float]:
         ):
             return data.min, data.max
 
-    while np.prod(data.shape) > 1e6:
-        ax = np.argmax(data.shape)
-        sl = [slice(None)] * data.ndim
-        sl[ax] = slice(None, None, 2)
-        data = data[tuple(sl)]
+    data = subsample_array(data, max_size=max_size)
 
     return float(np.nanmin(data)), float(np.nanmax(data))
 
@@ -405,3 +404,62 @@ def parse_cmap_values(
         colors = np.vstack([colormap[val] for val in norm_cmap_values])
 
         return colors
+
+
+def subsample_array(arr: np.ndarray, max_size: int = 1e6):
+    """
+    Subsamples an input array while preserving its relative dimensional proportions.
+
+    The dimensions (shape) of the array can be represented as:
+
+    .. math::
+
+        [d_1, d_2, \\dots d_n]
+
+    The product of the dimensions can be represented as:
+
+    .. math::
+
+        \\prod_{i=1}^{n} d_i
+
+    To find the factor ``f`` by which to divide the size of each dimension in order to
+    get max_size ``s`` we must solve for ``f`` in the following expression:
+
+    .. math::
+
+        \\prod_{i=1}^{n} \\frac{d_i}{\\mathbf{f}} = \\mathbf{s}
+
+    The solution for ``f`` is is simply the nth root of the product of the dims divided by the max_size
+    where n is the number of dimensions
+
+    .. math::
+
+        \\mathbf{f} = \\sqrt[n]{\\frac{\\prod_{i=1}^{n} d_i}{\\mathbf{s}}}
+
+    Parameters
+    ----------
+    arr: np.ndarray
+        input array of any dimensionality to be subsampled.
+
+    max_size: int, default 1e6
+        maximum number of elements in subsampled array
+
+    Returns
+    -------
+    np.ndarray
+        subsample of the input array
+    """
+    if np.prod(arr.shape) <= max_size:
+        return arr  # no need to subsample if already below the threshold
+
+    # get factor by which to divide all dims
+    f = np.power((np.prod(arr.shape) / max_size), 1.0 / arr.ndim)
+
+    # new shape for subsampled array
+    ns = np.floor(np.array(arr.shape) / f).clip(min=1)
+
+    # get the step size for the slices
+    slices = tuple(
+        slice(None, None, int(s)) for s in np.floor(arr.shape / ns).astype(int)
+    )
+    return np.asarray(arr[slices])
