update notebooks/visclaw/animation_tools_demo.ipynb with better discu…

…ssion of making mpeg files

notebooks/visclaw/animation_tools_demo.ipynb

@@ -32,13 +32,24 @@
  " - Alternatively the `to_html5_video` method can be used to create an mp4 video.\n",
  "\n",
  " - The `to_jshtml` versions can also be embedded in another webpage or in Sphinx documentation, using the `animation_tools.make_html` and `animation_tools.make_rst` functions.\n",
- " \n",
  "\n",
- "#### Converting frames in a Clawpack `_plots` directory to animations:\n",
- " \n",
- " The `animation_tools.make_anim_outputs_from_plotdir` function can be used to turn the png files in a Clawpack `_plots` directory into stand-alone `.html`, `.mp4`, or `.rst` files.\n",
+ "All of these possibilities are illustrated below.\n",
+ " "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Converting frames in a Clawpack `_plots` directory to animations:\n",
  " \n",
- "All of these possibilities are illustrated below.\n"
+ "The `animation_tools.make_anim_outputs_from_plotdir` function (illustrated at the bottom of this notebook) can be used to turn the png files in a Clawpack `_plots` directory into stand-alone `.html`, `.mp4`, or `.rst` files.\n",
+ "\n",
+ "The advantage of this approach is that it uses `png` files already created in the `_plots` directory by `make plots` and so is an easy way to make an mpeg video with comparable resolution to the animations linked from the `_PlotIndex.html`, which are html versions of the same animations.\n",
+ "\n",
+ "The disadvantage of these animations is that they are typically low resolution since they read in `png` files and redisplay them with `imshow`, and the filesizes are often quite large if there are many frames.\n",
+ "\n",
+ "A better way to make higher-resolution animations (that are also generally smaller) is to use the [`matplotlib.animation`](https://matplotlib.org/stable/users/explain/animations/animations.html) tools more directly to create a figure and then provide an update function that only modifies the parts of the figure that change from one frame to the next. This approach is not illustrated in this notebook, but can be found in the Python script [make_fgout_animation.py](https://www.clawpack.org/gallery/_static/geoclaw/examples/tsunami/chile2010_fgmax-fgout/make_fgout_animation.py.html) found in the GeoClaw example [$CLAW/geoclaw/examples/tsunami/chile2010_fgmax-fgout](https://www.clawpack.org/gallery/_static/geoclaw/examples/tsunami/chile2010_fgmax-fgout/README.html).\n"
  ]
  },
  {
@@ -225,7 +236,7 @@
  "source": [
  "### As mp4 video\n",
  "\n",
- "Note that [ffmpeg](https://ffmpeg.org) must be installed in order to create an `mp4` file. "
+ "Note that [ffmpeg](https://ffmpeg.org) must be installed in order to create an `mp4` file, and that `anim.to_html5_video() creates an mpeg file that can be viewed right in the browser as follows:"
  ]
  },
  {
@@ -241,9 +252,14 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "### Stand-alone html file\n",
+ "### Stand-alone mp4 file\n",
+ "\n",
+ "To make a standalone mpeg file, use the `make_mp4` function. This wraps the matplotlib commands:\n",
  "\n",
- "Alternatively, a separate stand-alone html page can be created with the JSAnimation. This can be posted on the web for others to view, for example."
+ " writer = animation.writers['ffmpeg'](fps=fps)\n",
+ " anim.save(file_name, writer=writer)\n",
+ "\n",
+ "with appropriate arguments set. "
  ]
  },
  {
@@ -252,17 +268,17 @@
  "metadata": {},
  "outputs": [],
  "source": [
- "file_name = 'SineFunctions.html'\n",
- "animation_tools.make_html(anim, file_name=file_name, title=\"Sine Functions\", \n",
- " raw_html=\"Illustration of html file created by <tt>make_html</tt>\")\n",
- "FileLink(file_name)"
+ "file_name = 'SineFunctions.mp4'\n",
+ "animation_tools.make_mp4(anim, file_name=file_name) # fps=3 is default"
  ]
  },
  {
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "### Stand-alone mp4 file"
+ "### Stand-alone html file\n",
+ "\n",
+ "A separate stand-alone html page can be created with using `anim.to_jshtml()`. The `animation_tools.make_html` function wraps this and passes in appropriate arguments. The resulting html file can be posted on the web for others to view, for example."
  ]
  },
  {
@@ -271,8 +287,10 @@
  "metadata": {},
  "outputs": [],
  "source": [
- "file_name = 'SineFunctions.mp4'\n",
- "animation_tools.make_mp4(anim, file_name=file_name)"
+ "file_name = 'SineFunctions.html'\n",
+ "animation_tools.make_html(anim, file_name=file_name, title=\"Sine Functions\", \n",
+ " raw_html=\"Illustration of html file created by <tt>make_html</tt>\")\n",
+ "FileLink(file_name)"
  ]
  },
  {
@@ -470,7 +488,7 @@
  "name": "python",
  "nbconvert_exporter": "python",
  "pygments_lexer": "ipython3",
- "version": "3.10.9"
+ "version": "3.10.13"
  }
  },
  "nbformat": 4,