Documentation for Surface animations

Author: johnomotani

docs/source/api.rst

@@ -49,6 +49,7 @@ These blocks are built to animate data.
     Pcolormesh
     Imshow
     Scatter
+    Surface
 
 Graph Label Blocks
 ~~~~~~~~~~~~~~~~~~

docs/source/tutorial/images/surface.gif

@@ -0,0 +1,143 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Surface animations\n",
+    "\n",
+    "Here we show how to make animations of surface plots.\n",
+    "\n",
+    "First we need some imports:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%matplotlib notebook\n",
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "import animatplot as amp"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's use: $z = \\sin(x^2+y^2-t)$.\n",
+    "\n",
+    "First, we generate the data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "x = np.linspace(-2, 2, 41)\n",
+    "y = np.linspace(-2, 2, 41)\n",
+    "t = np.linspace(0, 2*np.pi, 30)\n",
+    "\n",
+    "X, Y, T = np.meshgrid(x, y, t)\n",
+    "\n",
+    "data = np.sin(X*X+Y*Y-T)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We need to be careful here. Our time axis is the last axis of our data, but animatplot assumes it is the first axis by default. Fortunately, we can use the ```t_axis``` argument.\n",
+    "\n",
+    "We need to create a special `Axes` object with a 3d projection to make surface animations. Here we do this by using `plt.subplots(subplot_kw={\"projection\": \"3d\"})`. In more complicated situations, you might need to pass an axes argument for various subplots, but here we only have one subplot, so we do not need to pass in the axes as animatplot can pick them up using `plt.gca()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "# standard matplotlib stuff\n",
+    "# create the different plotting axes\n",
+    "fig, ax = plt.subplots(subplot_kw={\"projection\": \"3d\"})\n",
+    "\n",
+    "ax.set_xlabel(\"x\")\n",
+    "ax.set_ylabel(\"y\")\n",
+    "ax.set_zlabel(\"z\")\n",
+    "\n",
+    "# animatplot stuff\n",
+    "# now we make our block\n",
+    "\n",
+    "block = amp.blocks.Surface(X[:,:,0], Y[:,:,0], data, t_axis=2)\n",
+    "timeline = amp.Timeline(t, fps=10)\n",
+    "\n",
+    "# now to contruct the animation\n",
+    "anim = amp.Animation([block], timeline)\n",
+    "anim.controls()\n",
+    "\n",
+    "anim.save_gif('images/surface')\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There is a lot going on here so lets break it down.\n",
+    "\n",
+    "Firstly, the ```standard matplotlib stuff``` is creating, and labeling all of our axes for our subplot. This is exactly how one might do a static, non-animated plot.\n",
+    "\n",
+    "When we make the Surface block, we pass in the x, y data as 2D arrays (```X[:,:,0]``` and ```Y[:,:,0]```), and the z data as a 3D array. We also specifify that the time axis is the last axis of the data ```t_axis=2```.\n",
+    "\n",
+    "To set the axis limits, you need to use `ax.set_xlim()`, `ax.set_ylim()` and `ax.set_zlim()`. The keywords ```vmin```, and ```vmax``` control the color scale if you pass a cmap argument.\n",
+    "\n",
+    "The rest simply brings the block and the timeline together into an animation."
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {
+    "raw_mimetype": "text/restructuredtext"
+   },
+   "source": [
+    ".. image:: images/surface.gif"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "celltoolbar": "Raw Cell Format",
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.8.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}