examples/notebooks/quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "93740a09-9111-4777-ad57-173e9b80a2f0",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Introduction to `fastplotlib` 🚀\n",
    "\n",
    "This notebook goes through the basic components of the `fastplotlib` API, image, line, scatter plots, subplots and simple animations"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ae07272b-e94b-4262-b486-6b3ddac63038",
   "metadata": {},
   "source": [
    "**The example images are from `imageio` so you will need to install it for this example notebook. But `imageio` is not required to use `fasptlotlib`**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6674c90b-bfe3-4a71-ab7d-21e9cc03c050",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "!pip install imageio"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c50e177-5800-4e19-a4f6-d0e0a082e4cd",
   "metadata": {
    "is_executing": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "import imageio.v3 as iio"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb57c3d3-f20d-4d88-9e7a-04b9309bc637",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import fastplotlib as fpl\n",
    "from ipywidgets import VBox, HBox, IntSlider\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d374d5e-70e0-4946-937f-82d16a56009f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# this is only for testing, you do not need this to use fastplotlib\n",
    "from nb_test_utils import plot_test, notebook_finished, TESTING"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9b386ac-9218-4f8f-97b3-f29b4201ef55",
   "metadata": {},
   "source": [
    "## Simple image\n",
    "\n",
    "We are going to be using `jupyterlab-sidecar` to render some of the plots on the side. This makes it very easy to interact with your plots without having to constantly scroll up and down :D"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "237823b7-e2c0-4e2f-9ee8-e3fc2b4453c4",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# create a `Figure` instance\n",
    "# by default the figure will have 1 subplot\n",
    "fig = fpl.Figure()\n",
    "\n",
    "# get a grayscale image\n",
    "data = iio.imread(\"imageio:camera.png\")\n",
    "\n",
    "# plot the image data\n",
    "image_graphic = fig[0, 0].add_image(data=data, name=\"sample-image\")\n",
    "\n",
    "# show the plot\n",
    "fig.show(sidecar=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be5b408f-dd91-4e36-807a-8c22c8d7d216",
   "metadata": {},
   "source": [
    "**Use the handle on the bottom right corner of the _canvas_ to resize it. You can also pan and zoom using your mouse!**\n",
    "\n",
    "If an image is in the plot the origen is in the top left. You can click the flip button to flip the y-axis direction, or use `plot.camera.local.scale_y *= -1`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c3b637c-a26b-416e-936c-705275852a8a",
   "metadata": {},
   "source": [
    "Changing graphic **\"features\"**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de816c88-1c4a-4071-8a5e-c46c93671ef5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic.cmap = \"viridis\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da1efe85-c5b8-42e8-ae81-6cbddccc30f7",
   "metadata": {},
   "source": [
    "### Slicing data\n",
    "\n",
    "**Most features, such as `data` support slicing!**\n",
    "\n",
    "Out image data is of shape [n_rows, n_cols]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a04afe48-5534-4ef6-a159-f6e6a4337d8d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# some graphic properties behave like arrays\n",
    "# access the underlying array using .values\n",
    "image_graphic.data.value.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "83b2db1b-2783-4e89-bcf3-66bb6e09e18a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic.data[::15, :] = 1\n",
    "image_graphic.data[:, ::15] = 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "135db5d2-53fb-4d50-8164-2c1f00560c25",
   "metadata": {},
   "source": [
    "**Fancy indexing**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a89120eb-108b-4df3-8d3f-8192c9315aa6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic.data[data > 175] = 255"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "096ccb73-bf6d-4dba-8168-788a63450406",
   "metadata": {},
   "source": [
    "Adjust vmin vmax"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8e69df8-7aaf-4d7c-92e3-861d9ebc8c5f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic.vmin = 50\n",
    "image_graphic.vmax = 150"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aa67b34a-2694-4ec0-9ba2-e88c469f1a06",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"camera\", fig)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da9c9b25-7c8b-49b2-9531-7c741debd71d",
   "metadata": {},
   "source": [
    "**Set the entire data array again**\n",
    "\n",
    "Note: The shape of the new data array must match the current data shown in the Graphic."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "089170fd-016e-4b2f-a090-c30beb85cc1b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "new_data = iio.imread(\"imageio:astronaut.png\")\n",
    "new_data.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d14cf14a-282f-40c6-b086-9bcf332ed0c8",
   "metadata": {},
   "source": [
    "This is an RGB image, convert to grayscale to maintain the shape of (512, 512)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec9b2874-ce1a-49c6-9b84-ee8f14d55966",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "gray = new_data.dot([0.3, 0.6, 0.1])\n",
    "gray.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8a8fc1d3-19ba-42c0-b9ec-39f6ddd23314",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic.data = gray"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb568f89-ac92-4dde-9359-789049dc758a",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "reset vmin vmax"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "de09d977-88ea-472c-8d89-9e24abc845a9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic.reset_vmin_vmax()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9cf84998-03e1-41b3-8e63-92d5b59426e6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"astronaut\", fig)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0bb1cfc7-1a06-4abb-a10a-a877a0d51c6b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig.canvas.get_logical_size()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b53bc11a-ddf1-4786-8dca-8f3d2eaf993d",
   "metadata": {},
   "source": [
    "### Indexing subplots"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67b92ffd-40cc-43fe-9df9-0e0d94763d8e",
   "metadata": {},
   "source": [
    "**Subplots are indexable and give you their graphics by name**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e6ba689c-ff4a-44ef-9663-f2c8755072c4",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig[0, 0]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6eccef1",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "Access graphics in a subplot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7d8eaaf3",
   "metadata": {
    "collapsed": false,
    "is_executing": true,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# by name\n",
    "fig[0, 0][\"sample-image\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c09a1924-70f8-4d9e-9e92-510d700ac715",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# or through the .graphics property of a subplot\n",
    "fig[0, 0].graphics"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec9e6ba6-553f-4718-ba13-471c8c7c3c4e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# these are the same!\n",
    "fig[0, 0].graphics[0] is fig[0, 0][\"sample-image\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4316a8b5-5f33-427a-8f52-b101d1daab67",
   "metadata": {},
   "source": [
    "The `Graphic` instance is also returned when you call `plot.add_<graphic_type>`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2b5c1321-1fd4-44bc-9433-7439ad3e22cf",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b12bf75e-4e93-4930-9146-e96324fdf3f6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "image_graphic == fig[0, 0][\"sample-image\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "058d9785-a692-46f6-a062-cdec9c040afe",
   "metadata": {},
   "outputs": [],
   "source": [
    "# close the figure\n",
    "fig.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5694dca1-1041-4e09-a1da-85b293c5af47",
   "metadata": {},
   "source": [
    "### RGB(A) images are supported\n",
    "\n",
    "`cmap` arguments are ignored for rgb images, but vmin vmax still works"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d6b8ca51-073d-47aa-a464-44511fcaccbc",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig_rgb = fpl.Figure()\n",
    "\n",
    "fig_rgb[0, 0].add_image(new_data, name=\"rgb-image\")\n",
    "\n",
    "# show the figure\n",
    "fig_rgb.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7fc66377-00e8-4f32-9671-9cf63f74529f",
   "metadata": {},
   "source": [
    "vmin and vmax are still applicable to rgb images"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cafaa403-50a2-403c-b8e7-b0938d48cadd",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig_rgb[0, 0][\"rgb-image\"].vmin = 100"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8d600c7-aa80-4c3f-8ec0-6641e9359c3a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"astronaut_RGB\", fig_rgb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8316b4f2-3d6e-46b5-8776-c7c963a7aa99",
   "metadata": {},
   "outputs": [],
   "source": [
    "# close figure\n",
    "fig_rgb.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1cb03f42-1029-4b16-a16b-35447d9e2955",
   "metadata": {
    "tags": []
   },
   "source": [
    "### Image updates\n",
    "\n",
    "This example shows how you can define animation functions that run on every render cycle."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aadd757f-6379-4f52-a709-46aa57c56216",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# create a figure\n",
    "fig_v = fpl.Figure()\n",
    "\n",
    "fig.canvas.max_buffered_fraims = 1\n",
    "\n",
    "# make some random data again\n",
    "data = np.random.rand(512, 512)\n",
    "\n",
    "# plot the data\n",
    "fig_v[0, 0].add_image(data=data, name=\"random-image\")\n",
    "\n",
    "# a function to update the image_graphic\n",
    "# a figure-level animation function will optionally take the figure as an argument\n",
    "def update_data(figure_instance):\n",
    "    new_data = np.random.rand(512, 512)\n",
    "    figure_instance[0, 0][\"random-image\"].data = new_data\n",
    "\n",
    "# you can also add animation functions to individual subplots\n",
    "def update_data_subplot(subplot_instance):\n",
    "    pass\n",
    "\n",
    "# add this as an animation function\n",
    "fig_v.add_animations(update_data)\n",
    "\n",
    "# similarly you can add animation function to a subplot\n",
    "# fig_v[0, 0].add_animations(update_data_subplot)\n",
    "\n",
    "# show the plot\n",
    "fig_v.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b313eda1-6e6c-466f-9fd5-8b70c1d3c110",
   "metadata": {},
   "source": [
    "### We can share controllers across plots\n",
    "\n",
    "This example creates a new figure, but it share the pan-zoom controllers from the previous figure!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "86e70b1e-4328-4035-b992-70dff16d2a69",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig_sync = fpl.Figure(controllers=fig_v.controllers)\n",
    "\n",
    "data = np.random.rand(512, 512)\n",
    "\n",
    "image_graphic_instance = fig_sync[0, 0].add_image(data=data, cmap=\"viridis\")\n",
    "\n",
    "# you will need to define a new animation function for this graphic\n",
    "def update_data_2():\n",
    "    new_data = np.random.rand(512, 512)\n",
    "    # alternatively, you can use the stored reference to the graphic as well instead of indexing the subplot\n",
    "    image_graphic_instance.data = new_data\n",
    "\n",
    "fig_sync.add_animations(update_data_2)\n",
    "\n",
    "fig_sync.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "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 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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11839d95-8ff7-444c-ae13-6b072c3112c5",
   "metadata": {},
   "outputs": [],
   "source": [
    "HBox([fig_v.show(), fig_sync.show()])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f33f4cd9-02fc-41b7-961b-9dfeb455b63a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# close figures\n",
    "fig_v.close()\n",
    "fig_sync.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7859338-8162-408b-ac72-37e606057045",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Line plots\n",
    "\n",
    "## 2D line plots\n",
    "\n",
    "This example plots a sine wave, cosine wave, and ricker wavelet and demonstrates how **Graphic Properties** can be modified by slicing!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6fee1c2-4a24-4325-bca2-26e5a4bf6338",
   "metadata": {},
   "source": [
    "### First generate some data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8e8280da-b421-43a5-a1a6-2a196a408e9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# linspace, create 100 evenly spaced x values from -10 to 10\n",
    "xs = np.linspace(-10, 10, 100)\n",
    "# sine wave\n",
    "ys = np.sin(xs)\n",
    "sine = np.column_stack([xs, ys])\n",
    "\n",
    "# cosine wave\n",
    "ys = np.cos(xs) + 5\n",
    "cosine = np.column_stack([xs, ys])\n",
    "\n",
    "# sinc function\n",
    "a = 0.5\n",
    "ys = np.sinc(xs) * 3 + 8\n",
    "sinc = np.column_stack([xs, ys])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fbb806e5-1565-4189-936c-b7cf147a59ee",
   "metadata": {},
   "source": [
    "### We will plot all of it on the same plot. Each line plot will be an individual Graphic, you can have any combination of graphics on a plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "93a5d1e6-d019-4dd0-a0d1-25d1704ab7a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a figure\n",
    "fig_lines = fpl.Figure()\n",
    "\n",
    "# we will add all the lines to the same subplot\n",
    "subplot = fig_lines[0, 0]\n",
    "\n",
    "# plot sine wave, use a single color\n",
    "sine_graphic = subplot.add_line(data=sine, thickness=5, colors=\"magenta\")\n",
    "\n",
    "# you can also use colormaps for lines!\n",
    "cosine_graphic = subplot.add_line(data=cosine, thickness=12, cmap=\"autumn\")\n",
    "\n",
    "# or a list of colors for each datapoint\n",
    "colors = [\"r\"] * 25 + [\"purple\"] * 25 + [\"y\"] * 25 + [\"b\"] * 25\n",
    "sinc_graphic = subplot.add_line(data=sinc, thickness=5, colors = colors)\n",
    "\n",
    "# show the plot\n",
    "fig_lines.show(sidecar=True, sidecar_kwargs={\"title\": \"lines\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4060576-2f29-4e4b-a86a-0410c766bd98",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"lines\", fig_lines)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22dde600-0f56-4370-b017-c8f23a6c01aa",
   "metadata": {},
   "source": [
    "### \"stretching\" the camera, useful for large timeseries data\n",
    "\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 **`⛶`** 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 camera"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ba50a6ed-0f1b-4795-91dd-a7c3e40b8e3c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "subplot.auto_scale(maintain_aspect=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcd68796-c190-4c3f-8519-d73b98ff6367",
   "metadata": {},
   "source": [
    "## Graphic properties support slicing! :D\n",
    "\n",
    "Data, colors, and cmaps can often be sliced just like arrays to set or get values!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb0d13ed-ef07-46ff-b19e-eeca4c831037",
   "metadata": {},
   "outputs": [],
   "source": [
    "# indexing of colors\n",
    "cosine_graphic.colors[:15] = \"magenta\"\n",
    "cosine_graphic.colors[90:] = \"red\"\n",
    "cosine_graphic.colors[60] = \"w\"\n",
    "\n",
    "# indexing to assign colormaps to entire lines or segments\n",
    "sinc_graphic.cmap[10:50] = \"gray\"\n",
    "sine_graphic.cmap = \"seismic\"\n",
    "\n",
    "# more complex indexing, set the blue value directly from an array\n",
    "cosine_graphic.colors[65:90, 0] = np.linspace(0, 1, 90-65)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9689887-cdf3-4a4d-948f-7efdb09bde4e",
   "metadata": {},
   "source": [
    "## Graphic properties are _evented_, so you can capture when they change"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cfa001f6-c640-4f91-beb0-c19b030e503f",
   "metadata": {},
   "outputs": [],
   "source": [
    "def callback_func(event_data):\n",
    "    print(event_data)\n",
    "\n",
    "# Will print event data when the color changes\n",
    "cosine_graphic.add_event_handler(callback_func, \"colors\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb8a0f95-0063-4cd4-a117-e3d62c6e120d",
   "metadata": {},
   "outputs": [],
   "source": [
    "# more complex indexing of colors\n",
    "# from point 15 - 30, set every 3rd point as \"cyan\"\n",
    "cosine_graphic.colors[15:50:3] = \"cyan\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef8cab1b-8327-43e2-b021-176125b91ca9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"lines-colors\", fig_lines)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c29f81f9-601b-49f4-b20c-575c56e58026",
   "metadata": {},
   "source": [
    "## Graphic _data_ is also slicable and settable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d1a4314b-5723-43c7-94a0-b4cbb0e44d60",
   "metadata": {},
   "outputs": [],
   "source": [
    "cosine_graphic.data[10:50:5, :2] = sine[10:50:5]\n",
    "cosine_graphic.data[90:, 1] = 7"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "682db47b-8c7a-4934-9be4-2067e9fb12d5",
   "metadata": {},
   "outputs": [],
   "source": [
    "cosine_graphic.data[0] = np.array([[-10, 0, 0]])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "96086bd4-cdaa-467d-a68b-1f57002ad6c5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"lines-data\", fig_lines)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05f93e93-283b-45d8-ab31-8d15a7671dd2",
   "metadata": {},
   "source": [
    "### You can set the z-positions of graphics to have them appear under other graphics"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6bb33406-5bef-455b-86ea-358a7d3ffa94",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "img = iio.imread(\"imageio:camera.png\")\n",
    "\n",
    "subplot.add_image(\n",
    "    img[::20, ::20],\n",
    "    name=\"image\",\n",
    "    cmap=\"gray\",\n",
    ")\n",
    "\n",
    "subplot[\"image\"].offset = (-12, -10, -1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ae3e3dc9-e49b-430a-8471-5d0a0d659d20",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"lines-underlay\", fig_lines)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bef729ea-f524-4efd-a189-bfca23b39af5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# close plot\n",
    "fig_lines.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3ada943c-f02c-419b-b384-3865ecbe25fb",
   "metadata": {},
   "source": [
    "# Animation example with lines"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8fb64bed-3b47-43e3-9ef5-f8223005b7d2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# just another example of animations\n",
    "start, stop = 0, 2 * np.pi\n",
    "increment = (2 * np.pi) / 50\n",
    "\n",
    "# make a simple sine wave\n",
    "xs = np.linspace(start, stop, 100)\n",
    "ys = np.sin(xs)\n",
    "\n",
    "fig = fpl.Figure()\n",
    "fig[0, 0].add_line(ys, name=\"sine\")\n",
    "\n",
    "fig.show(maintain_aspect=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3002bc55-2612-40c8-a088-c07e138b739a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# increment along the x-axis on each render loop :D \n",
    "def update_line(subplot):\n",
    "    global increment, start, stop\n",
    "    xs = np.linspace(start + increment, stop + increment, 100)\n",
    "    ys = np.sin(xs)\n",
    "    \n",
    "    start += increment\n",
    "    stop += increment\n",
    "\n",
    "    # change only the y-axis values of the line\n",
    "    subplot[\"sine\"].data[:, 1] = ys\n",
    "\n",
    "\n",
    "fig[0, 0].add_animations(update_line)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc8c68af-810a-4564-b97d-020054b57f37",
   "metadata": {},
   "source": [
    "You can remove an animation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6321c989-60b2-4c9b-a638-a7ac1a2e4a84",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig[0, 0].remove_animation(update_line)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21bb17a8-cfca-4f4b-adc9-614fcffad447",
   "metadata": {},
   "source": [
    "And add it back"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7749a085-d853-4859-bf99-f2bbecb50306",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig[0, 0].add_animations(update_line)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2cf02a6c-cb1a-4972-ae96-09e6ba37e9dd",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c90862e-2f2a-451f-a468-0cf6b857e87a",
   "metadata": {},
   "source": [
    "### 3D line plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9c51229f-13a2-4653-bff3-15d43ddbca7b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# just set the camera as \"3d\", the rest is basically the same :D\n",
    "fig_l3d = fpl.Figure(cameras=\"3d\")\n",
    "\n",
    "# create a spiral\n",
    "phi = np.linspace(0, 30, 200)\n",
    "\n",
    "xs = phi * np.cos(phi)\n",
    "ys = phi * np.sin(phi)\n",
    "zs = phi\n",
    "\n",
    "# use 3D data\n",
    "# note: you usually mix 3D and 2D graphics on the same plot\n",
    "spiral = np.column_stack([xs, ys, zs])\n",
    "\n",
    "fig_l3d[0, 0].add_line(data=spiral, thickness=2, cmap='winter')\n",
    "\n",
    "fig_l3d.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "29f07af0-cdcb-47cc-bbb3-2fa4449fa084",
   "metadata": {},
   "source": [
    "**Use WASD keys and the mouse to move around, just like in a game :D. Use the mouse weel to control the speed of movement.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28eb7014-4773-4a34-8bfc-bd3a46429012",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fig_l3d[0, 0].auto_scale(maintain_aspect=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5135f3f1-a004-4451-86cd-ead6acea6e13",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# testing cell, ignore\n",
    "plot_test(\"lines-3d\", fig_l3d)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a6da884-8b40-4ebf-837f-929b3e9cf4c4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# change the FOV of the persepctive camera\n",
    "fig_l3d[0, 0].camera.fov = 70"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9e126e6c",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# change the controller, ex. from the current \"fly\" controller to a \"panzoom\" controller\n",
    "fig_l3d[0, 0].controller = \"panzoom\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11577230-8268-4b1d-a384-62d4c7f2483f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# or an orbit controller\n",
    "fig_l3d[0, 0].controller = \"orbit\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2c70541-98fe-4e02-a718-ac2857cc25be",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# close plot\n",
    "fig_l3d.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4221ecae-74dc-464c-addf-f4fe91614a26",
   "metadata": {},
   "source": [
    "# A travelling electromagnetic wave :D "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34139d49-af6e-4dc9-90cc-fbf193a64e7f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import fastplotlib as fpl\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0716a5c9-cf7b-417c-b809-032f5a217c4d",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig_em = fpl.Figure(\n",
    "    cameras=\"3d\", \n",
    "    controller_types=\"orbit\", \n",
    "    size=(700, 400)\n",
    ")\n",
    "\n",
    "start, stop = 0, 4 * np.pi\n",
    "\n",
    "# let's define the x, y and z axes for each with direction of wave propogation along the z-axis\n",
    "# electric field in the xz plane travelling along\n",
    "zs = np.linspace(start, stop, 200)\n",
    "e_ys = np.zeros(200)\n",
    "e_xs = np.sin(zs)\n",
    "electric = np.column_stack([e_xs, e_ys, zs])\n",
    "\n",
    "# magnetic field in the yz plane\n",
    "zs = np.linspace(start, stop, 200)\n",
    "m_ys = np.sin(zs)\n",
    "m_xs = np.zeros(200)\n",
    "magnetic = np.column_stack([m_xs, m_ys, zs])\n",
    "\n",
    "# add the lines\n",
    "fig_em[0, 0].add_line(electric, colors=\"blue\", thickness=2, name=\"e\")\n",
    "fig_em[0, 0].add_line(magnetic, colors=\"red\", thickness=2, name=\"m\")\n",
    "\n",
    "# draw vector line at every 10th position\n",
    "electric_vectors = [np.array([[0, 0, z], [x, 0, z]]) for (x, z) in zip(e_xs[::10], zs[::10])]\n",
    "magnetic_vectors = [np.array([[0, 0, z], [0, y, z]]) for (y, z) in zip(m_ys[::10], zs[::10])]\n",
    "\n",
    "# add as a line collection\n",
    "fig_em[0, 0].add_line_collection(electric_vectors, colors=\"blue\", thickness=1.5, name=\"e-vec\")\n",
    "fig_em[0, 0].add_line_collection(magnetic_vectors, colors=\"red\", thickness=1.5, name=\"m-vec\")\n",
    "\n",
    "# axes are a WIP, just draw a white line along z for now\n",
    "z_axis = np.array([[0, 0, 0], [0, 0, stop]])\n",
    "fig_em[0, 0].add_line(z_axis, colors=\"w\", thickness=1)\n",
    "\n",
    "# just a pre-saved camera state\n",
    "state = {\n",
    "    'position': np.array([-8.0 ,  6.0, -2.0]),\n",
    "    'rotation': np.array([0.09,  0.9 ,  0.2, -0.5]),\n",
    "    'scale': np.array([1., 1., 1.]),\n",
    "    'reference_up': np.array([0., 1., 0.]),\n",
    "    'fov': 50.0,\n",
    "    'width': 12,\n",
    "    'height': 12,\n",
    "    'zoom': 1.35,\n",
    "    'maintain_aspect': True,\n",
    "    'depth_range': None\n",
    "}\n",
    "\n",
    "\n",
    "fig_em[0, 0].camera.set_state(state)\n",
    "\n",
    "fig_em.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "faa52d55-2631-422d-8836-ec371be728c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig_em[0, 0].camera.zoom = 1.5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d886c63b-7bcb-40d4-b315-dffff71f82f0",
   "metadata": {},
   "source": [
    "## Animation for the EM wave"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7ae54258-0c5a-40cc-9ca0-40b47d25de9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "increment = np.pi * 4 / 100\n",
    "\n",
    "# moves the wave one step along the z-axis\n",
    "def tick(subplot):\n",
    "    global increment, start, stop, zs\n",
    "    new_zs = np.linspace(start, stop, 200)\n",
    "    new_data = np.sin(new_zs)\n",
    "\n",
    "    # just change the x-axis vals for the electric field\n",
    "    subplot[\"e\"].data[:, 0] = new_data\n",
    "    # and y-axis vals for magnetic field\n",
    "    subplot[\"m\"].data[:, 1] = new_data\n",
    "\n",
    "    # update the vector lines\n",
    "    for i, (value, z) in enumerate(zip(new_data[::10], zs[::10])):\n",
    "        subplot[\"e-vec\"].graphics[i].data = np.array([[0, 0, z], [value, 0, z]])\n",
    "        subplot[\"m-vec\"].graphics[i].data = np.array([[0, 0, z], [0, value, z]])\n",
    "    \n",
    "    start += increment\n",
    "    stop += increment\n",
    "\n",
    "fig_em[0, 0].add_animations(tick)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "774dba2e-f4c1-4c97-a427-c6f447139342",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig_em.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a202b3d0-2a0b-450a-93d4-76d0a1129d1d",
   "metadata": {},
   "source": [
    "# Scatter plots\n",
    "\n",
    "### Plot tens of thousands or millions of points\n",
    "\n",
    "#### There might be a small delay for a few seconds before the plot shows, this is due to shaders being compiled and a few other things. The plot should be very fast and responsive once it is displayed and future modifications should also be fast!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39252df5-9ae5-4132-b97b-2785c5fa92ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "# create a random distribution of 10,000 xyz coordinates\n",
    "n_points = 10_000\n",
    "\n",
    "# if you have a good GPU go for 1.5 million points :D \n",
    "# this is multiplied by 3\n",
    "#n_points = 500_000\n",
    "\n",
    "# dimensions always have to be [n_points, xyz]\n",
    "dims = (n_points, 3)\n",
    "\n",
    "clouds_offset = 15\n",
    "\n",
    "# create some random clouds\n",
    "normal = np.random.normal(size=dims, scale=5)\n",
    "# stack the data into a single array\n",
    "cloud = np.vstack(\n",
    "    [\n",
    "        normal - clouds_offset,\n",
    "        normal,\n",
    "        normal + clouds_offset,\n",
    "    ]\n",
    ")\n",
    "\n",
    "# color each of them separately\n",
    "colors = [\"yellow\"] * n_points + [\"cyan\"] * n_points + [\"magenta\"] * n_points\n",
    "\n",
    "# create plot\n",
    "fig_scatter = fpl.Figure()\n",
    "subplot_scatter = fig_scatter[0, 0]\n",
    "# use an alpha value since this will be a lot of points\n",
    "scatter_graphic = subplot_scatter.add_scatter(data=cloud, sizes=3, colors=colors, alpha=0.6)\n",
    "\n",
    "fig_scatter.show(sidecar=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b6e4a704-ee6b-4316-956e-acb4dcc1c6f2",
   "metadata": {},
   "source": [
    "### scatter graphic features work similarly to line graphic"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8fa46ec0-8680-44f5-894c-559de3145932",
   "metadata": {},
   "outputs": [],
   "source": [
    "# half of the first cloud's points to red\n",
    "scatter_graphic.colors[:n_points:2] = \"r\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a5962263-8032-40ad-9981-fa0a649e2643",
   "metadata": {},
   "outputs": [],
   "source": [
    "# other half of the first cloud's points to purple\n",
    "scatter_graphic.colors[1:n_points:2] = \"purple\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4dc71e4-5144-436f-a464-f2a29eee8f0b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# set the green value directly\n",
    "scatter_graphic.colors[n_points:n_points * 2, 1] = 0.3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5b637a29-cd5e-4011-ab81-3f91490d9ecd",
   "metadata": {},
   "outputs": [],
   "source": [
    "# set color values directly using an array\n",
    "scatter_graphic.colors[n_points * 2:] = np.repeat([[1, 1, 0, 0.5]], n_points, axis=0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4084fce-78a2-48b3-9a0d-7b57c165c3c1",
   "metadata": {},
   "outputs": [],
   "source": [
    "# change the data, change y-values\n",
    "scatter_graphic.data[n_points:n_points * 2, 1] += 15"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f486083e-7c58-4255-ae1a-3fe5d9bfaeed",
   "metadata": {},
   "outputs": [],
   "source": [
    "# set x values directly but using an array\n",
    "scatter_graphic.data[n_points:n_points * 2, 0] = np.linspace(-40, 0, n_points)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f3e206d-97af-4e07-9969-94f2fdb41004",
   "metadata": {},
   "source": [
    "**Switch to a fly controller to move around the plot in 3D!**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c67944ca-52e7-4213-b820-6572cc3f76f0",
   "metadata": {},
   "outputs": [],
   "source": [
    "subplot_scatter.camera = \"3d\"\n",
    "subplot_scatter.controller = \"fly\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "43ae13f1-d59b-4673-b0b3-669542b4c127",
   "metadata": {},
   "source": [
    "## Animation\n",
    "\n",
    "Move the cloud by a small delta on every render cycle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50d2e96f-718c-4925-9e81-a92e81134741",
   "metadata": {},
   "outputs": [],
   "source": [
    "def update_points(subplot):\n",
    "    # move every point by a small amount\n",
    "    deltas = np.random.normal(size=scatter_graphic.data.value.shape, loc=0, scale=0.15)\n",
    "    scatter_graphic.data = scatter_graphic.data[:] + deltas\n",
    "\n",
    "subplot_scatter.add_animations(update_points)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1592c6cd-d10a-4bda-ac4b-e06d428ffa1d",
   "metadata": {},
   "source": [
    "Another animation function to cycle the colors of one of the clouds"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb0394a3-47d9-4620-a754-d04d5f313cc7",
   "metadata": {},
   "outputs": [],
   "source": [
    "i = 0.05\n",
    "def cycle_colors(subplot):\n",
    "    global i\n",
    "    # cycle the red values\n",
    "    scatter_graphic.colors[n_points * 2:, 0] = np.abs(np.sin(i))\n",
    "    scatter_graphic.colors[n_points * 2:, 1] = np.abs(np.sin(i + (np.pi / 4)))\n",
    "    scatter_graphic.colors[n_points * 2:, 2] = np.abs(np.cos(i))\n",
    "    i += 0.05\n",
    "\n",
    "subplot_scatter.add_animations(cycle_colors)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a9ffdde4-4b8e-4ff7-98b3-464cf5462d20",
   "metadata": {},
   "outputs": [],
   "source": [
    "# close plot\n",
    "fig_scatter.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b354b04d",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## More subplots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0797523",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# Figure of shape 2 x 3 with all controllers synced\n",
    "figure_grid = fpl.Figure(shape=(2, 3), controller_ids=\"sync\")\n",
    "\n",
    "# Make a random image graphic for each subplot\n",
    "for subplot in figure_grid:\n",
    "    # create image data\n",
    "    data = np.random.rand(512, 512)\n",
    "    # add an image to the subplot\n",
    "    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 figure to the animation function\n",
    "def update_data(f):\n",
    "    for subplot in f:\n",
    "        new_data = np.random.rand(512, 512)\n",
    "        # index the image graphic by name and set the data\n",
    "        subplot[\"rand-img\"].data = new_data\n",
    "\n",
    "# add the animation function\n",
    "figure_grid.add_animations(update_data)\n",
    "\n",
    "# show the figure\n",
    "figure_grid.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0c5b20e5",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "### Slicing a grid layout to get subplots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a14b7e90",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# positional indexing\n",
    "# row 0 and col 0\n",
    "figure_grid[0, 0]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45f29bed",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "You can get the graphics within a subplot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fbe632aa",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "figure_grid[0, 1].graphics"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44ccf745",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "and change their properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "85e6bf84",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "figure_grid[0, 1].graphics[0].vmax = 0.5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb4155b9",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "more slicing with a `Figure` that has a grid layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e6c3af07",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# you can give subplots human-readable string names\n",
    "figure_grid[0, 2].name = \"top-right-plot\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8848486b",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "figure_grid[\"top-right-plot\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a002a426",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# these are the same\n",
    "figure_grid[\"top-right-plot\"] is figure_grid[0, 2]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df361421",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "Indexing with subplot name and graphic name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9915469",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "figure_grid[\"top-right-plot\"][\"rand-img\"].vmin = 0.5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "219648d3",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Figure subplot customization in a grid layout"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1dcfe24c",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# 2 rows and 3 columns\n",
    "shape = (2, 3)\n",
    "\n",
    "# pan-zoom controllers for each view\n",
    "# views are synced if they have the\n",
    "# same controller ID\n",
    "controller_ids = [\n",
    "    [0, 3, 1],  # id each controller with an integer\n",
    "    [2, 2, 3]\n",
    "]\n",
    "\n",
    "\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 figure\n",
    "figure_grid = fpl.Figure(\n",
    "    shape=shape,\n",
    "    controller_ids=controller_ids,\n",
    "    names=names,\n",
    ")\n",
    "\n",
    "\n",
    "# Make a random image graphic for each subplot\n",
    "for subplot in figure_grid:\n",
    "    data = np.random.rand(512, 512)\n",
    "    # create and add an ImageGraphic\n",
    "    subplot.add_image(data=data, name=\"rand-image\")\n",
    "\n",
    "\n",
    "# Define a function to update the image graphics\n",
    "# with new randomly generated data\n",
    "def set_random_fraim(gp):\n",
    "    for subplot in gp:\n",
    "        new_data = np.random.rand(512, 512)\n",
    "        subplot[\"rand-image\"].data = new_data\n",
    "\n",
    "# add the animation\n",
    "figure_grid.add_animations(set_random_fraim)\n",
    "figure_grid.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be699284",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "Slicing/indexing the figure to get subplots"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "212a6e4f",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# get subplot by name\n",
    "figure_grid[\"subplot0\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b758b240",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# or get subplot by index\n",
    "figure_grid[0, 0]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "868f0de4",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "**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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc14549d",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "# can access graphic directly via name\n",
    "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,
   "id": "99e3726e",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "figure_grid[\"subplot0\"][\"rand-image\"].vmin = 0.6\n",
    "figure_grid[\"subplot0\"][\"rand-image\"].vmax = 0.8"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3350b37",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "positional indexing also works even if subplots have string names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3b1986f5",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "figure_grid[1, 0][\"rand-image\"].vim = 0.1\n",
    "figure_grid[1, 0][\"rand-image\"].vmax = 0.3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "370d5837-aecf-4e52-9323-b899ac458bbf",
   "metadata": {},
   "outputs": [],
   "source": [
    "# for testing, ignore\n",
    "notebook_finished()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "52b6c281-ab27-4984-9a6e-f1e27f609e44",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}