fastplotlib · clewis7 · May 20, 2025 · May 19, 2025 · May 19, 2025 · May 19, 2025
@@ -24,15 +24,15 @@
    [2, 0],
 ]

-names = [f"contr. id: {i}" for i in np.asarray(ids).ravel()]
-
 figure = fpl.Figure(
    shape=(2, 2),
    controller_ids=ids,
-    names=names,
    size=(700, 560),
 )

+for subplot, controller_id in zip(figure, np.asarray(ids).ravel()):
+    subplot.title = f"contr. id: {controller_id}"
+
 figure[0, 0].add_line(np.column_stack([xs, sine]))

 figure[0, 1].add_line(np.random.rand(100))

@@ -1,2 +1,2 @@
-GridPlot Examples
-=================
+Grid layout Examples
+====================
@@ -1,8 +1,8 @@
 """
-GridPlot Simple
-===============
+Grid layout Simple
+==================

-Example showing simple 2x2 GridPlot with Standard images from imageio.
+Example showing simple 2x2 grid layout with standard images from imageio.
 """

 # test_example = true

@@ -1,8 +1,8 @@
 """
-GridPlot Non-Square Example
-===========================
+Grid Layout 2
+=============

-Example showing simple 2x2 GridPlot with Standard images from imageio.
+Simple 2x2 grid layout Figure with standard images from imageio, one subplot is left empty
 """

 # test_example = true

@@ -1,6 +1,6 @@
 """
-GridPlot test viewport rects
-============================
+Grid layout test viewport rects
+===============================

 Test figure to test that viewport rects are positioned correctly
 """

@@ -1,8 +1,8 @@
 """
-Multi-Graphic GridPlot
-======================
+Multi-Graphic Grid layout
+=========================

-Example showing a Figure with multiple subplots and multiple graphic types.
+A Figure with multiple subplots and multiple graphic types.
 """

 # test_example = false

@@ -2,7 +2,7 @@
 Multi-Subplot Image Update
 ==========================

-Example showing updating a multiple subplots with new random 512x512 data.
+Multiple subplots with an image that updates with new data on every render.
 """

 # test_example = false
@@ -27,7 +27,7 @@
 figure[1,1]["rand-img"].cmap = "spring"

 # Define a function to update the image graphics with new data
-# add_animations will pass the gridplot to the animation function
+# add_animations will pass the figure to the animation function
 def update_data(f):
    for subplot in f:
        new_data = np.random.rand(512, 512)
@@ -37,7 +37,7 @@ def update_data(f):
 # add the animation function
 figure.add_animations(update_data)

-# show the gridplot
+# show the figure
 figure.show()



@@ -463,7 +463,7 @@
   "id": "5694dca1-1041-4e09-a1da-85b293c5af47",
   "metadata": {},
   "source": [
-    "### RGB images are also supported\n",
+    "### RGB(A) images are supported\n",
    "\n",
    "`cmap` arguments are ignored for rgb images, but vmin vmax still works"
   ]
@@ -538,7 +538,7 @@
   "source": [
    "### Image updates\n",
    "\n",
-    "This examples show how you can define animation functions that run on every render cycle."
+    "This example shows how you can define animation functions that run on every render cycle."
   ]
  },
  {
@@ -620,15 +620,15 @@
   "id": "f226c9c2-8d0e-41ab-9ab9-1ae31fd91de5",
   "metadata": {},
   "source": [
-    "#### Keeping a reference to the Graphic instance, as shown above `image_graphic_instance`, is useful if you're creating something where you need flexibility in the naming of the graphics"
+    "#### Keeping a reference to the Graphic instance, as shown above `image_graphic_instance`, is useful if you're creating something where it is convenient to keep your own reference to a `Graphic`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d11fabb7-7c76-4e94-893d-80ed9ee3be3d",
   "metadata": {},
   "source": [
-    "### You can also use `ipywidgets.VBox` and `HBox` to stack plots. See the `subplot` notebooks for more automated subplotting"
+    "### You can also use `ipywidgets.VBox` and `HBox` to stack plots."
   ]
  },
  {
@@ -664,7 +664,7 @@
    "\n",
    "## 2D line plots\n",
    "\n",
-    "This example plots a sine wave, cosine wave, and ricker wavelet and demonstrates how **Graphic Features** can be modified by slicing!"
+    "This example plots a sine wave, cosine wave, and ricker wavelet and demonstrates how **Graphic Properties** can be modified by slicing!"
   ]
  },
  {
@@ -755,15 +755,15 @@
    "\n",
    "Set `maintain_aspect = False` on a camera, and then use the right mouse button and move the mouse to stretch and squeeze the view!\n",
    "\n",
-    "You can also click the **`1:1`** button to toggle this, or use `subplot.camera.maintain_aspect`"
+    "You can also click the **`⛶`** button to toggle this, or use `subplot.camera.maintain_aspect`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1651e965-f750-47ac-bf53-c23dae84cc98",
   "metadata": {},
   "source": [
-    "### reset the plot area"
+    "### reset the plot area camera"
   ]
  },
  {
@@ -783,7 +783,9 @@
   "id": "dcd68796-c190-4c3f-8519-d73b98ff6367",
   "metadata": {},
   "source": [
-    "## Graphic features support slicing! :D "
+    "## Graphic properties support slicing! :D\n",
+    "\n",
+    "Data, colors, and cmaps can often be sliced just like arrays to set or get values!"
   ]
  },
  {
@@ -811,7 +813,7 @@
   "id": "c9689887-cdf3-4a4d-948f-7efdb09bde4e",
   "metadata": {},
   "source": [
-    "## You can capture changes to a graphic feature as events"
+    "## Graphic properties are _evented_, so you can capture when they change"
   ]
  },
  {
@@ -1551,7 +1553,7 @@
    "    subplot.add_image(data, name=\"rand-img\")\n",
    "\n",
    "# Define a function to update the image graphics with new data\n",
-    "# add_animations will pass the gridplot to the animation function\n",
+    "# add_animations will pass the figure to the animation function\n",
    "def update_data(f):\n",
    "    for subplot in f:\n",
    "        new_data = np.random.rand(512, 512)\n",
@@ -1561,7 +1563,7 @@
    "# add the animation function\n",
    "figure_grid.add_animations(update_data)\n",
    "\n",
-    "# show the gridplot\n",
+    "# show the figure\n",
    "figure_grid.show()"
   ]
  },
@@ -1575,7 +1577,7 @@
    }
   },
   "source": [
-    "### Slicing GridPlot"
+    "### Slicing a grid layout to get subplots"
   ]
  },
  {
@@ -1605,7 +1607,7 @@
    }
   },
   "source": [
-    "You can get the graphics within a subplot, just like with simple `Plot`"
+    "You can get the graphics within a subplot"
   ]
  },
  {
@@ -1661,7 +1663,7 @@
    }
   },
   "source": [
-    "more slicing with `GridPlot`"
+    "more slicing with a `Figure` that has a grid layout"
   ]
  },
  {
@@ -1707,7 +1709,7 @@
   },
   "outputs": [],
   "source": [
-    "# these are really the same\n",
+    "# these are the same\n",
    "figure_grid[\"top-right-plot\"] is figure_grid[0, 2]"
   ]
  },
@@ -1749,7 +1751,7 @@
    }
   },
   "source": [
-    "## Figure subplot customization"
+    "## Figure subplot customization in a grid layout"
   ]
  },
  {
@@ -1776,13 +1778,13 @@
    "]\n",
    "\n",
    "\n",
-    "# you can give string names for each subplot within the gridplot\n",
+    "# you can give string names for each subplot within the figure\n",
    "names = [\n",
    "    [\"subplot0\", \"subplot1\", \"subplot2\"],\n",
    "    [\"subplot3\", \"subplot4\", \"subplot5\"]\n",
    "]\n",
    "\n",
-    "# Create the grid plot\n",
+    "# Create the figure\n",
    "figure_grid = fpl.Figure(\n",
    "    shape=shape,\n",
    "    controller_ids=controller_ids,\n",
@@ -1819,7 +1821,7 @@
    }
   },
   "source": [
-    "Indexing the gridplot to access subplots"
+    "Slicing/indexing the figure to get subplots"
   ]
  },
  {
@@ -1834,7 +1836,7 @@
   },
   "outputs": [],
   "source": [
-    "# can access subplot by name\n",
+    "# get subplot by name\n",
    "figure_grid[\"subplot0\"]"
   ]
  },
@@ -1850,7 +1852,7 @@
   },
   "outputs": [],
   "source": [
-    "# can access subplot by index\n",
+    "# or get subplot by index\n",
    "figure_grid[0, 0]"
   ]
  },
@@ -1864,7 +1866,7 @@
    }
   },
   "source": [
-    "**subplots also support indexing!**\n",
+    "**from before, remember subplots themselves also support slicing to get graphics within them!**\n",
    "\n",
    "this can be used to get graphics if they are named"
   ]
@@ -1885,6 +1887,17 @@
    "figure_grid[\"subplot0\"][\"rand-image\"]"
   ]
  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "87905450bdc0ec0a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# or by their numerical index\n",
+    "figure_grid[\"subplot0\"].graphics[0]"
+   ]
+  },
  {
   "cell_type": "code",
   "execution_count": null,
@@ -1911,7 +1924,7 @@
    }
   },
   "source": [
-    "positional indexing also works event if subplots have string names"
+    "positional indexing also works even if subplots have string names"
   ]
  },
  {

@@ -2,7 +2,10 @@
 Scatter Plot Size
 =================

-Example showing point size change for scatter plot.
+Example that shows how to set scatter sizes in two different ways.
+
+One subplot uses a single scaler value for every point, and another subplot uses an array that defines the size for
+each individual scatter point.
 """

 # test_example = true
@@ -14,10 +17,10 @@
 # figure with 2 rows and 3 columns
 shape = (2, 1)

-# you can give string names for each subplot within the gridplot
+# you can give string names for each subplot within the figure
 names = [["scalar_size"], ["array_size"]]

-# Create the grid plot
+# Create the figure
 figure = fpl.Figure(shape=shape, names=names, size=(700, 560))

 # get y_values using sin function

@@ -19,7 +19,7 @@ class PositionsGraphic(Graphic):

    @property
    def data(self) -> VertexPositions:
-        """Get or set the vertex positions data"""
+        """Get or set the graphic's data"""
        return self._data

    @data.setter
@@ -28,7 +28,7 @@ def data(self, value):

    @property
    def colors(self) -> VertexColors | pygfx.Color:
-        """Get or set the colors data"""
+        """Get or set the colors"""
        if isinstance(self._colors, VertexColors):
            return self._colors

@@ -45,7 +45,11 @@ def colors(self, value: str | np.ndarray | tuple[float] | list[float] | list[str

    @property
    def cmap(self) -> VertexCmap:
-        """Control the cmap, cmap transform, or cmap alpha"""
+        """
+        Control the cmap, cmap transform, or cmap alpha
+
+        For supported colormaps see the ``cmap`` library catalogue: https://cmap-docs.readthedocs.io/en/stable/catalog/
+        """
        return self._cmap

    @cmap.setter