fastplotlib · kushalkolar · Dec 25, 2025 · Dec 27, 2025 · Dec 27, 2025 · Dec 28, 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

@@ -63,31 +63,28 @@ Questions, issues, ideas? You are welcome to post an [issue](https://github.com/
 
 To install use pip:
 
-```bash
-# with imgui and jupyterlab
-pip install -U "fastplotlib[notebook,imgui]"
+### With imgui support (recommended)
 
-# minimal install, install glfw, pyqt6 or pyside6 separately
-pip install -U fastplotlib
+Without jupyterlab support, install desired GUI framework such as glfw, PyQt6, or PySide6 separately.
 
-# with imgui
-pip install -U "fastplotlib[imgui]"
+    pip install -U "fastplotlib[imgui]"
 
-# to use in jupyterlab without imgui
-pip install -U "fastplotlib[notebook]"
-```
+With jupyterlab support.
 
-We strongly recommend installing ``simplejpeg`` for use in notebooks, you must first install [libjpeg-turbo](https://libjpeg-turbo.org/)
+    pip install -U "fastplotlib[notebook,imgui]"
 
-- If you use ``conda``, you can get ``libjpeg-turbo`` through conda.
-- If you are on linux, you can get it through your distro's package manager.
-- For Windows and Mac compiled binaries are available on their release page: https://github.com/libjpeg-turbo/libjpeg-turbo/releases
+### Without imgui
 
-Once you have ``libjpeg-turbo``:
+Minimal, install desired GUI library such as PyQt6, PySide6, or glfw separately.
+
+    pip install fastplotlib
+
+With jupyterlab support only.
+
+    pip install -U "fastplotlib[notebook]"
+
+Fastplotlib is also available on conda-forge. For imgui support you will need to separately install `imgui-bundle`, and for jupyterlab you will need to install `jupyter-rfb` and `simplejpeg` which are all available on conda-forge.
 
-```bash
-pip install simplejpeg
-```
 
 > **Note:**
 > `fastplotlib` and `pygfx` are fast evolving projects, the version available through pip might be outdated, you will need to follow the "For developers" instructions below if you want the latest features. You can find the release history here: https://github.com/fastplotlib/fastplotlib/releases

@@ -25,6 +25,7 @@ Properties
     LineGraphic.axes
     LineGraphic.block_events
     LineGraphic.cmap
+    LineGraphic.color_mode
     LineGraphic.colors
     LineGraphic.data
     LineGraphic.deleted

@@ -25,6 +25,7 @@ Properties
     ScatterGraphic.axes
     ScatterGraphic.block_events
     ScatterGraphic.cmap
+    ScatterGraphic.color_mode
     ScatterGraphic.colors
     ScatterGraphic.data
     ScatterGraphic.deleted

@@ -6,31 +6,38 @@ Installation
 
 To install use pip:
 
-.. code-block::
+With imgui support (recommended)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    # with imgui and jupyterlab
-    pip install -U "fastplotlib[notebook,imgui]"
+Without jupyterlab support, install desired GUI framework such as glfw, PyQt6, or PySide6 separately.
 
-    # minimal install, install glfw, pyqt6 or pyside6 separately
-    pip install -U fastplotlib
+.. code-block::
 
-    # with imgui
     pip install -U "fastplotlib[imgui]"
 
-    # to use in jupyterlab, no imgui
-    pip install -U "fastplotlib[notebook]"
+With jupyterlab support.
 
-We strongly recommend installing ``simplejpeg`` for use in notebooks, you must first install `libjpeg-turbo <https://libjpeg-turbo.org/>`_.
+.. code-block::
+
+    pip install -U "fastplotlib[notebook,imgui]"
 
-- If you use ``conda``, you can get ``libjpeg-turbo`` through conda.
-- If you are on linux you can get it through your distro's package manager.
-- For Windows and Mac compiled binaries are available on their release page: https://github.com/libjpeg-turbo/libjpeg-turbo/releases
+Without imgui
+^^^^^^^^^^^^^
 
-Once you have ``libjpeg-turbo``:
+Minimal, install desired GUI library such as PyQt6, PySide6, or glfw separately.
 
 .. code-block::
 
-    pip install simplejpeg
+    pip install fastplotlib
+
+With jupyterlab support only.
+
+.. code-block::
+
+    pip install -U "fastplotlib[notebook]"
+
+Fastplotlib is also available on conda-forge. For imgui support you will need to separately install ``imgui-bundle``, and for jupyterlab you will need to install ``jupyter-rfb`` and ``simplejpeg`` which are all available on conda-forge.
+
 
 What is ``fastplotlib``?
 ------------------------

@@ -34,7 +34,7 @@
 xs = np.linspace(0, 4 * np.pi, 100)
 ys = np.sin(xs)
 
-figure["sine"].add_line(np.column_stack([xs, ys]))
+figure["sine"].add_line(np.column_stack([xs, ys]), color_mode="vertex")
 
 # make a 2D gaussian cloud
 cloud_data = np.random.normal(0, scale=3, size=1000).reshape(500, 2)

@@ -106,7 +106,7 @@ def make_circle(center, radius: float, n_points: int = 75) -> np.ndarray:
 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=2, cmap="jet")
+figure["scatter"].add_scatter(data=gaussian_cloud, sizes=2, cmap="jet", color_mode="vertex")
 figure["scatter"].add_scatter(data=gaussian_cloud2, colors="r", sizes=2)
 
 figure.show()

@@ -29,10 +29,10 @@
 figure = fpl.Figure(size=(700, 560))
 
 # make some scatter points at every 10th point
-figure[0, 0].add_scatter(data[::10], colors="cyan", sizes=15, name="sine-scatter", uniform_color=True)
+figure[0, 0].add_scatter(data[::10], colors="cyan", sizes=15, name="sine-scatter")
 
 # place a line above the scatter
-figure[0, 0].add_line(data, thickness=3, colors="r", name="sine-wave", uniform_color=True)
+figure[0, 0].add_line(data, thickness=3, colors="r", name="sine-wave")
 
 
 class ImguiExample(EdgeWindow):

@@ -0,0 +1,50 @@
+"""
+Image reshaping
+===============
+
+An example that shows replacement of the image data with new data of a different shape. Under the hood, this creates a
+new buffer and a new array of Textures on the GPU that replace the older Textures. Creating a new buffer and textures
+has a performance cost, so you should do this only if you need to or if the performance drawback is not a concern for
+your use case.
+
+Note that the vmin-vmax is reset when you replace the buffers.
+"""
+
+# test_example = false
+# sphinx_gallery_pygfx_docs = 'animate'
+
+
+import numpy as np
+import fastplotlib as fpl
+
+# create some data, diagonal sinusoidal bands
+xs = np.linspace(0, 2300, 2300, dtype=np.float16)
+full_data = np.vstack([np.cos(np.sqrt(xs + (np.pi / 2) * i)) * i for i in range(2_300)])
+
+figure = fpl.Figure()
+
+image = figure[0, 0].add_image(full_data)
+
+figure.show()
+
+i, j = 1, 1
+
+
+def update():
+    global i, j
+    # set the new image data as a subset of the full data
+    row = np.abs(np.sin(i)) * 2300
+    col = np.abs(np.cos(i)) * 2300
+    image.data = full_data[: int(row), : int(col)]
+
+    i += 0.01
+    j += 0.01
+
+
+figure.add_animations(update)
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()
@@ -27,7 +27,7 @@
     data=sine_data,
     thickness=10,
     cmap="plasma",
-    cmap_transform=sine_data[:, 1]
+    cmap_transform=sine_data[:, 1],
 )
 
 # qualitative colormaps, useful for cluster labels or other types of categorical labels
@@ -36,7 +36,7 @@
     data=cosine_data,
     thickness=10,
     cmap="tab10",
-    cmap_transform=labels
+    cmap_transform=labels,
 )
 
 figure.show()

@@ -31,16 +31,35 @@
 # set colormap by mapping data using a transform
 # here we map the color using the y-values of the sine data
 # i.e., the color is a function of sine(x)
-line2 = figure[0, 0].add_line(sine, thickness=10, cmap="jet", cmap_transform=sine[:, 1], offset=(0, 4, 0))
+line2 = figure[0, 0].add_line(
+    sine,
+    thickness=10,
+    cmap="jet",
+    cmap_transform=sine[:, 1],
+    offset=(0, 4, 0),
+)
 
 # make a line and change the cmap afterward, here we are using the cosine instead fot the transform
-line3 = figure[0, 0].add_line(sine, thickness=10, cmap="jet", cmap_transform=cosine[:, 1], offset=(0, 6, 0))
+line3 = figure[0, 0].add_line(
+    sine,
+    thickness=10,
+    cmap="jet",
+    cmap_transform=cosine[:, 1],
+    offset=(0, 6, 0)
+)
+
 # change the cmap
 line3.cmap = "bwr"
 
 # use quantitative colormaps with categorical cmap_transforms
 labels = [0] * 25 + [1] * 5 + [2] * 50 + [3] * 20
-line4 = figure[0, 0].add_line(sine, thickness=10, cmap="tab10", cmap_transform=labels, offset=(0, 8, 0))
+line4 = figure[0, 0].add_line(
+    sine,
+    thickness=10,
+    cmap="tab10",
+    cmap_transform=labels,
+    offset=(0, 8, 0),
+)
 
 # some text labels
 for i in range(5):

@@ -30,7 +30,8 @@
 sine = figure[0, 0].add_line(
     data=sine_data,
     thickness=5,
-    colors="magenta"
+    colors="magenta",
+    color_mode="vertex",  # initialize with same color across vertices, but we will change the per-vertex colors later
 )
 
 # you can also use colormaps for lines!
@@ -56,6 +57,7 @@
     data=zeros_data,
     thickness=8,
     colors="w",
+    color_mode="vertex",  # initialize with same color across vertices, but we will change the per-vertex colors later
     offset=(0, 10, 0)
 )
 

@@ -26,6 +26,7 @@
     multi_data,
     thickness=[2, 10, 2, 5, 5, 5, 8, 8, 8, 9, 3, 3, 3, 4, 4],
     separation=4,
+    color_mode="vertex",  # this will allow us to set per-vertex colors on each line
     metadatas=list(range(15)),  # some metadata
     names=list("abcdefghijklmno"),  # unique name for each line
 )

@@ -80,6 +80,7 @@
     sizes=5,
     cmap="tab10", # use a qualitative cmap
     cmap_transform=kmeans.labels_, # color by the predicted cluster
+    uniform_size=False,
 )
 
 # initial index

@@ -0,0 +1,91 @@
+"""
+Buffer replacement garbage collection test
+==========================================
+
+This is an example that used for a manual test to ensure that GPU VRAM is free when buffers are replaced.
+
+Use while monitoring VRAM usage with nvidia-smi
+"""
+
+# test_example = false
+# sphinx_gallery_pygfx_docs = 'code'
+
+
+from typing import Literal
+import numpy as np
+import fastplotlib as fpl
+from fastplotlib.ui import EdgeWindow
+from imgui_bundle import imgui
+
+
+def generate_dataset(size: int) -> dict[str, np.ndarray]:
+    return {
+        "data": np.random.rand(size, 3),
+        "colors": np.random.rand(size, 4),
+        # TODO: there's a wgpu bind group issue with edge_colors, will figure out later
+        # "edge_colors": np.random.rand(size, 4),
+        "markers": np.random.choice(list("osD+x^v<>*"), size=size),
+        "sizes": np.random.rand(size) * 5,
+        "point_rotations": np.random.rand(size) * 180,
+    }
+
+
+datasets = {
+    "init": generate_dataset(50_000),
+    "small": generate_dataset(100),
+    "large": generate_dataset(5_000_000),
+}
+
+
+class UI(EdgeWindow):
+    def __init__(self, figure):
+        super().__init__(figure=figure, size=200, location="right", title="UI")
+        init_data = datasets["init"]
+        self._figure["line"].add_line(
+            data=init_data["data"], colors=init_data["colors"], name="line"
+        )
+        self._figure["scatter"].add_scatter(
+            **init_data,
+            uniform_size=False,
+            uniform_marker=False,
+            uniform_edge_color=False,
+            point_rotation_mode="vertex",
+            name="scatter",
+        )
+
+    def update(self):
+        for graphic in ["line", "scatter"]:
+            if graphic == "line":
+                features = ["data", "colors"]
+
+            elif graphic == "scatter":
+                features = list(datasets["init"].keys())
+
+            for size in ["small", "large"]:
+                for fea in features:
+                    if imgui.button(f"{size} - {graphic} - {fea}"):
+                        self._replace(graphic, fea, size)
+
+    def _replace(
+        self,
+        graphic: Literal["line", "scatter", "image"],
+        feature: Literal["data", "colors", "markers", "sizes", "point_rotations"],
+        size: Literal["small", "large"],
+    ):
+        new_value = datasets[size][feature]
+
+        setattr(self._figure[graphic][graphic], feature, new_value)
+
+
+figure = fpl.Figure(shape=(3, 1), size=(700, 1600), names=["line", "scatter", "image"])
+ui = UI(figure)
+figure.add_gui(ui)
+
+figure.show()
+
+
+# NOTE: fpl.loop.run() should not be used for interactive sessions
+# See the "JupyterLab and IPython" section in the user guide
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()