sphinx gallery

docs/source/conf.py

@@ -2,7 +2,24 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+
+# need to force offscreen rendering before importing fpl
+# otherwise fpl tries to select glfw canvas
+os.environ["WGPU_FORCE_OFFSCREEN"] = "1"
+
 import fastplotlib
+from pygfx.utils.gallery_scraper import find_examples_for_gallery
+from pathlib import Path
+import sys
+from sphinx_gallery.sorting import ExplicitOrder
+import imageio.v3 as iio
+
+ROOT_DIR = Path(__file__).parents[1].parents[0]  # repo root
+EXAMPLES_DIR = Path.joinpath(ROOT_DIR, "examples", "desktop")
+
+sys.path.insert(0, str(ROOT_DIR))
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -23,8 +40,40 @@
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
     "sphinx_design",
+    "sphinx_gallery.gen_gallery"
 ]
 
+sphinx_gallery_conf = {
+    "gallery_dirs": "_gallery",
+    "backreferences_dir": "_gallery/backreferences",
+    "doc_module": ("fastplotlib",),
+    "image_scrapers": ("pygfx",),
+    "remove_config_comments": True,
+    "subsection_order": ExplicitOrder(
+        [
+            "../../examples/desktop/image",
+            "../../examples/desktop/gridplot",
+            "../../examples/desktop/line",
+            "../../examples/desktop/line_collection",
+            "../../examples/desktop/scatter",
+            "../../examples/desktop/heatmap",
+            "../../examples/desktop/misc"
+        ]
+    ),
+    "ignore_pattern": r'__init__\.py',
+    "nested_sections": False,
+    "thumbnail_size": (250, 250)
+}
+
+extra_conf = find_examples_for_gallery(EXAMPLES_DIR)
+sphinx_gallery_conf.update(extra_conf)
+
+# download imageio examples for the gallery
+iio.imread("imageio:clock.png")
+iio.imread("imageio:astronaut.png")
+iio.imread("imageio:coffee.png")
+iio.imread("imageio:hubble_deep_field.png")
+
 autosummary_generate = True
 
 templates_path = ["_templates"]
@@ -56,7 +105,7 @@
 }
 
 html_theme_options = {
-    "source_repository": "https://github.com/kushalkolar/fastplotlib",
+    "source_repository": "https://github.com/fastplotlib/fastplotlib",
     "source_branch": "main",
     "source_directory": "docs/",
 }

docs/source/index.rst

@@ -20,6 +20,12 @@ Welcome to fastplotlib's documentation!
    Utils <api/utils>
    GPU <api/gpu>
 
+.. toctree::
+   :caption: Gallery
+   :maxdepth:  1
+
+   Gallery <_gallery/index>
+
 Summary
 =======
 

examples/README.rst

@@ -0,0 +1,2 @@
+Examples that use fastplotlib
+=============================

examples/desktop/gridplot/README.rst

@@ -0,0 +1,2 @@
+GridPlot Examples
+=================

examples/desktop/gridplot/gridplot.py

@@ -1,34 +1,37 @@
 """
 GridPlot Simple
-============
+===============
+
 Example showing simple 2x2 GridPlot with Standard images from imageio.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
-fig = fpl.Figure(shape=(2, 2))
+figure = fpl.Figure(shape=(2, 2))
 
 im = iio.imread("imageio:clock.png")
 im2 = iio.imread("imageio:astronaut.png")
 im3 = iio.imread("imageio:coffee.png")
 im4 = iio.imread("imageio:hubble_deep_field.png")
 
-fig[0, 0].add_image(data=im)
-fig[0, 1].add_image(data=im2)
-fig[1, 0].add_image(data=im3)
-fig[1, 1].add_image(data=im4)
+figure[0, 0].add_image(data=im)
+figure[0, 1].add_image(data=im2)
+figure[1, 0].add_image(data=im3)
+figure[1, 1].add_image(data=im4)
 
-fig.show()
+figure.show()
 
-fig.canvas.set_logical_size(800, 800)
+figure.canvas.set_logical_size(700, 560)
 
-for subplot in fig:
+for subplot in figure:
     subplot.auto_scale()
 
+# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
+# please see our docs for using fastplotlib interactively in ipython and jupyter
 if __name__ == "__main__":
     print(__doc__)
     fpl.run()

examples/desktop/gridplot/gridplot_non_square.py

@@ -1,32 +1,35 @@
 """
-GridPlot Simple
-============
+GridPlot Non-Square Example
+===========================
+
 Example showing simple 2x2 GridPlot with Standard images from imageio.
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import imageio.v3 as iio
 
-
-fig = fpl.Figure(shape=(2, 2), controller_ids="sync")
+figure = fpl.Figure(shape=(2, 2), controller_ids="sync")
 
 im = iio.imread("imageio:clock.png")
 im2 = iio.imread("imageio:astronaut.png")
 im3 = iio.imread("imageio:coffee.png")
 
-fig[0, 0].add_image(data=im)
-fig[0, 1].add_image(data=im2)
-fig[1, 0].add_image(data=im3)
+figure[0, 0].add_image(data=im)
+figure[0, 1].add_image(data=im2)
+figure[1, 0].add_image(data=im3)
 
-fig.show()
+figure.show()
 
-fig.canvas.set_logical_size(800, 800)
+figure.canvas.set_logical_size(700, 560)
 
-for subplot in fig:
+for subplot in figure:
     subplot.auto_scale()
 
+# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
+# please see our docs for using fastplotlib interactively in ipython and jupyter
 if __name__ == "__main__":
     print(__doc__)
     fpl.run()

examples/desktop/gridplot/multigraphic_gridplot.py

@@ -0,0 +1,116 @@
+"""
+Multi-Graphic GridPlot
+======================
+
+Example showing a Figure with multiple subplots and multiple graphic types.
+"""
+
+# test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import fastplotlib as fpl
+import numpy as np
+import imageio.v3 as iio
+from itertools import product
+
+# define figure
+figure = fpl.Figure(shape=(2, 2), names=[["image-overlay", "circles"], ["line-stack", "scatter"]])
+
+img = iio.imread("imageio:coffee.png")
+
+# add image to subplot
+figure["image-overlay"].add_image(data=img)
+
+# generate overlay
+
+# empty array for overlay, shape is [nrows, ncols, RGBA]
+overlay = np.zeros(shape=(*img.shape[:2], 4), dtype=np.float32)
+
+# set the blue values of some pixels with an alpha > 1
+overlay[img[:, :, -1] > 200] = np.array([0.0, 0.0, 1.0, 0.6]).astype(np.float32)
+
+# add overlay to image
+figure["image-overlay"].add_image(data=overlay)
+
+# generate some circles
+def make_circle(center, radius: float, n_points: int = 75) -> np.ndarray:
+    theta = np.linspace(0, 2 * np.pi, n_points)
+    xs = radius * np.sin(theta)
+    ys = radius * np.cos(theta)
+
+    return np.column_stack([xs, ys]) + center
+
+
+spatial_dims = (50, 50)
+
+# this makes 16 circles, so we can create 16 cmap values, so it will use these values to set the
+# color of the line based by using the cmap as a LUT with the corresponding cmap_transform
+circles = list()
+for center in product(range(0, spatial_dims[0], 15), range(0, spatial_dims[1], 15)):
+    circles.append(make_circle(center, 5, n_points=75))
+
+# things like class labels, cluster labels, etc.
+cmap_transform = [
+    0, 1, 1, 2,
+    0, 0, 1, 1,
+    2, 2, 8, 3,
+    1, 9, 1, 5
+]
+
+# add an image to overlay the circles on
+img2 = np.ones((60, 60))
+
+figure["circles"].add_image(data=img2)
+
+# add the circles to the figure
+figure["circles"].add_line_collection(
+    circles,
+    cmap="tab10",
+    cmap_transform=cmap_transform,
+    thickness=3,
+    alpha=0.5,
+    name="circles-graphic"
+)
+
+# move the circles graphic so that it is centered over the image
+figure["circles"]["circles-graphic"].offset = np.array([7, 7, 2])
+
+# generate some sine data
+# linspace, create 100 evenly spaced x values from -10 to 10
+xs = np.linspace(-10, 10, 100)
+# sine wave
+ys = np.sin(xs)
+sine = np.dstack([xs, ys])[0]
+
+# make 10 identical waves
+sine_waves = 10 * [sine]
+
+# add the line stack to the figure
+figure["line-stack"].add_line_stack(data=sine_waves, cmap="Wistia", separation=1)
+
+figure["line-stack"].auto_scale(maintain_aspect=True)
+
+# generate some scatter data
+# create a gaussian cloud of 500 points
+n_points = 500
+
+mean = [0, 0]  # mean of the Gaussian distribution
+covariance = [[1, 0], [0, 1]]  # covariance matrix
+
+gaussian_cloud = np.random.multivariate_normal(mean, covariance, n_points)
+gaussian_cloud2 = np.random.multivariate_normal(mean, covariance, n_points)
+
+# add the scatter graphics to the figure
+figure["scatter"].add_scatter(data=gaussian_cloud, sizes=1, cmap="jet")
+figure["scatter"].add_scatter(data=gaussian_cloud2, colors="r", sizes=1)
+
+figure.show()
+
+figure.canvas.set_logical_size(700, 560)
+
+# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
+# please see our docs for using fastplotlib interactively in ipython and jupyter
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.run()
+

examples/desktop/heatmap/README.rst

@@ -0,0 +1,2 @@
+Heatmap Examples
+================

examples/desktop/heatmap/heatmap.py

@@ -5,12 +5,12 @@
 """
 
 # test_example = true
+# sphinx_gallery_pygfx_docs = 'screenshot'
 
 import fastplotlib as fpl
 import numpy as np
 
-
-fig = fpl.Figure()
+figure = fpl.Figure()
 
 xs = np.linspace(0, 1_000, 10_000, dtype=np.float32)
 
@@ -19,14 +19,16 @@
 data = np.vstack([sine * i for i in range(20_000)])
 
 # plot the image data
-img = fig[0, 0].add_image(data=data, name="heatmap")
+img = figure[0, 0].add_image(data=data, name="heatmap")
 
-fig.show()
+figure.show()
 
-fig.canvas.set_logical_size(1500, 1500)
+figure.canvas.set_logical_size(700, 560)
 
-fig[0, 0].auto_scale()
+figure[0, 0].auto_scale()
 
+# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
+# please see our docs for using fastplotlib interactively in ipython and jupyter
 if __name__ == "__main__":
     print(__doc__)
     fpl.run()

examples/desktop/heatmap/heatmap_cmap.py

@@ -4,13 +4,14 @@
 Change the cmap of a heatmap
 """
 
+
 # test_example = false
+# sphinx_gallery_pygfx_docs = 'hidden'
 
 import fastplotlib as fpl
 import numpy as np
 
-
-fig = fpl.Figure()
+figure = fpl.Figure()
 
 xs = np.linspace(0, 1_000, 10_000, dtype=np.float32)
 
@@ -19,16 +20,18 @@
 data = np.vstack([sine * i for i in range(20_000)])
 
 # plot the image data
-img = fig[0, 0].add_image(data=data, name="heatmap")
+img = figure[0, 0].add_image(data=data, name="heatmap")
 
-fig.show()
+figure.show()
 
-fig.canvas.set_logical_size(1500, 1500)
+figure.canvas.set_logical_size(700, 560)
 
-fig[0, 0].auto_scale()
+figure[0, 0].auto_scale()
 
 img.cmap = "viridis"
 
+# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
+# please see our docs for using fastplotlib interactively in ipython and jupyter
 if __name__ == "__main__":
     print(__doc__)
     fpl.run()