napari · psobolewskiPhD · Mar 23, 2024 · Dec 6, 2023 · Mar 8, 2024 · Mar 15, 2024
diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
@@ -52,6 +52,12 @@ jobs:
           python -c 'import napari; print(napari.__version__)'
           python -c 'import napari.layers; print(napari.layers.__doc__)'
 
+      - name: Create fallback videos
+        run: |
+          sudo apt-get update && sudo apt-get install -y ffmpeg
+          cd docs
+          make fallback-videos
+
       - name: Build Docs
         uses: aganders3/headless-gui@v2
         env:

diff --git a/.gitignore b/.gitignore
@@ -154,3 +154,6 @@ docs/sg_execution_times.rst
 # come from npe2 docs
 docs/plugins/_npe2_*.md
 npe2/
+
+# autogenerated fallback videos
+docs/_static/images/*.mp4
diff --git a/Makefile b/Makefile
@@ -59,3 +59,15 @@ html-noplot: clean prep-docs
 
 linkcheck-files:
 	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build ${FILES} -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
+
+fallback-videos:
+	for video in $(basename $(wildcard docs/_static/images/*.webm)); do \
+		if [ -a $$video.mp4 ]; then \
+			echo "skipping $$video.mp4"; \
+			continue; \
+		fi; \
+		ffmpeg -i $$video.webm -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -preset slow -crf 22 -c:a aac -b:a 128k -strict -2 -y $$video.mp4; \
+	done
+
+fallback-videos-clean:
+	rm -f docs/_static/images/*.mp4
diff --git a/docs/_static/images/LLSM.png b/docs/_static/images/LLSM.png
diff --git a/docs/images/LLSM.webm → docs/_static/images/LLSM.webm b/docs/images/LLSM.webm → docs/_static/images/LLSM.webm
diff --git a/docs/_static/images/brain_surface.png b/docs/_static/images/brain_surface.png
diff --git a/docs/images/brain_surface.webm → docs/_static/images/brain_surface.webm b/docs/images/brain_surface.webm → docs/_static/images/brain_surface.webm
diff --git a/docs/_static/images/dask1.png b/docs/_static/images/dask1.png
diff --git a/docs/tutorials/assets/tutorials/dask1.webm → docs/_static/images/dask1.webm b/docs/tutorials/assets/tutorials/dask1.webm → docs/_static/images/dask1.webm
diff --git a/docs/_static/images/dask2.png b/docs/_static/images/dask2.png
diff --git a/docs/tutorials/assets/tutorials/dask2.webm → docs/_static/images/dask2.webm b/docs/tutorials/assets/tutorials/dask2.webm → docs/_static/images/dask2.webm
diff --git a/docs/_static/images/delete_label.png b/docs/_static/images/delete_label.png
diff --git a/docs/images/delete_label.webm → docs/_static/images/delete_label.webm b/docs/images/delete_label.webm → docs/_static/images/delete_label.webm
diff --git a/docs/_static/images/draw_component.png b/docs/_static/images/draw_component.png
diff --git a/docs/images/draw_component.webm → docs/_static/images/draw_component.webm b/docs/images/draw_component.webm → docs/_static/images/draw_component.webm
diff --git a/docs/_static/images/editing_points.png b/docs/_static/images/editing_points.png
diff --git a/docs/images/editing_points.webm → docs/_static/images/editing_points.webm b/docs/images/editing_points.webm → docs/_static/images/editing_points.webm
diff --git a/docs/_static/images/editing_shapes.png b/docs/_static/images/editing_shapes.png
diff --git a/docs/images/editing_shapes.webm → docs/_static/images/editing_shapes.webm b/docs/images/editing_shapes.webm → docs/_static/images/editing_shapes.webm
diff --git a/docs/_static/images/manual_label.png b/docs/_static/images/manual_label.png
diff --git a/docs/images/manual_label.webm → docs/_static/images/manual_label.webm b/docs/images/manual_label.webm → docs/_static/images/manual_label.webm
diff --git a/docs/_static/images/merge_labels.png b/docs/_static/images/merge_labels.png
diff --git a/docs/images/merge_labels.webm → docs/_static/images/merge_labels.webm b/docs/images/merge_labels.webm → docs/_static/images/merge_labels.webm
diff --git a/docs/_static/images/mitosis.png b/docs/_static/images/mitosis.png
diff --git a/docs/guides/images/mitosis.webm → docs/_static/images/mitosis.webm b/docs/guides/images/mitosis.webm → docs/_static/images/mitosis.webm
diff --git a/docs/_static/images/nD_shapes.png b/docs/_static/images/nD_shapes.png
diff --git a/docs/images/nD_shapes.webm → docs/_static/images/nD_shapes.webm b/docs/images/nD_shapes.webm → docs/_static/images/nD_shapes.webm
diff --git a/docs/_static/images/nD_vectors.png b/docs/_static/images/nD_vectors.png
diff --git a/docs/images/nD_vectors.webm → docs/_static/images/nD_vectors.webm b/docs/images/nD_vectors.webm → docs/_static/images/nD_vectors.webm
diff --git a/docs/_static/images/pathology.png b/docs/_static/images/pathology.png
diff --git a/docs/images/pathology.webm → docs/_static/images/pathology.webm b/docs/images/pathology.webm → docs/_static/images/pathology.webm
diff --git a/docs/_static/images/point_annotator_demo.png b/docs/_static/images/point_annotator_demo.png
diff --git a/...ssets/tutorials/point_annotator_demo.webm → .../_static/images/point_annotator_demo.webm b/...ssets/tutorials/point_annotator_demo.webm → .../_static/images/point_annotator_demo.webm
diff --git a/docs/_static/images/scaling.png b/docs/_static/images/scaling.png
diff --git a/docs/guides/images/scaling.webm → docs/_static/images/scaling.webm b/docs/guides/images/scaling.webm → docs/_static/images/scaling.webm
diff --git a/docs/_static/images/shape_resizing.png b/docs/_static/images/shape_resizing.png
diff --git a/docs/images/shape_resizing.webm → docs/_static/images/shape_resizing.webm b/docs/images/shape_resizing.webm → docs/_static/images/shape_resizing.webm
diff --git a/docs/_static/images/shape_vertex_editing.png b/docs/_static/images/shape_vertex_editing.png
diff --git a/docs/_static/images/shape_vertex_editing.webm b/docs/_static/images/shape_vertex_editing.webm
diff --git a/docs/_static/images/smFISH.png b/docs/_static/images/smFISH.png
diff --git a/docs/images/smFISH.webm → docs/_static/images/smFISH.webm b/docs/images/smFISH.webm → docs/_static/images/smFISH.webm
diff --git a/docs/_static/images/split_label.png b/docs/_static/images/split_label.png
diff --git a/docs/images/split_label.webm → docs/_static/images/split_label.webm b/docs/images/split_label.webm → docs/_static/images/split_label.webm
diff --git a/docs/_static/images/tracks_3d_t.png b/docs/_static/images/tracks_3d_t.png
diff --git a/docs/images/tracks_3d_t.webm → docs/_static/images/tracks_3d_t.webm b/docs/images/tracks_3d_t.webm → docs/_static/images/tracks_3d_t.webm
diff --git a/docs/_static/images/tracks_color_by.png b/docs/_static/images/tracks_color_by.png
diff --git a/docs/images/tracks_color_by.webm → docs/_static/images/tracks_color_by.webm b/docs/images/tracks_color_by.webm → docs/_static/images/tracks_color_by.webm
diff --git a/docs/_static/images/tracks_isbi.png b/docs/_static/images/tracks_isbi.png
diff --git a/...torials/assets/tutorials/tracks_isbi.webm → docs/_static/images/tracks_isbi.webm b/...torials/assets/tutorials/tracks_isbi.webm → docs/_static/images/tracks_isbi.webm
diff --git a/docs/_static/images/tracks_simple_demo.png b/docs/_static/images/tracks_simple_demo.png
diff --git a/docs/images/tracks_simple_demo.webm → docs/_static/images/tracks_simple_demo.webm b/docs/images/tracks_simple_demo.webm → docs/_static/images/tracks_simple_demo.webm
diff --git a/docs/_static/images/tracks_tail_length.png b/docs/_static/images/tracks_tail_length.png
diff --git a/docs/images/tracks_tail_length.webm → docs/_static/images/tracks_tail_length.webm b/docs/images/tracks_tail_length.webm → docs/_static/images/tracks_tail_length.webm
diff --git a/docs/_static/images/tracks_tail_width.png b/docs/_static/images/tracks_tail_width.png
diff --git a/docs/images/tracks_tail_width.webm → docs/_static/images/tracks_tail_width.webm b/docs/images/tracks_tail_width.webm → docs/_static/images/tracks_tail_width.webm
diff --git a/docs/_static/images/tribolium.mp4 b/docs/_static/images/tribolium.mp4
diff --git a/docs/_static/images/viewer_pan_zoom.png b/docs/_static/images/viewer_pan_zoom.png
diff --git a/...als/assets/tutorials/viewer_pan_zoom.webm → docs/_static/images/viewer_pan_zoom.webm b/...als/assets/tutorials/viewer_pan_zoom.webm → docs/_static/images/viewer_pan_zoom.webm
diff --git a/docs/developers/contributing/documentation/docs_template.md b/docs/developers/contributing/documentation/docs_template.md
@@ -45,6 +45,25 @@ You should include pictures/videos, particularly when describing interactions wi
 accompanied by complete and descriptive alt-text. If you're using arrows/circles to highlight portions of the image, make sure
 they contrast well against the background of the image.
 
+`````{important} Adding videos
+  If you want to include videos in your documentation, you should use the .webm format and add a screenshot of the video as a fallback for browsers that don't support the video tag. Both files should be added to `docs/_static/images`. When the documentation is built, a .mp4 version of the video will be automatically generated and included in the documentation. You can then use the .webm file in your documentation like so:
+
+  ````{code}
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="_static/images/your-video.webm" type="video/webm" />
+    <source src="_static/images/your-video.mp4" type="video/mp4" />
+    <img src="_static/images/your-video-screenshot.png"
+      title="your browser does not support the video tag"
+      alt="Your video's alt text"
+    >
+  </video>
+</figure>
+```
+  ````
+`````
+
 ### Take screenshots of the viewer
 
 It's common for napari documentation to include code that has some effect in the napari Viewer e.g. adding layers,

diff --git a/docs/guides/layers.md b/docs/guides/layers.md
@@ -91,7 +91,18 @@ or 3 less than the total number of dimensions of the layer, allowing you to
 browse volumetric timeseries data and other high dimensional data. See for
 example these cells undergoing mitosis in this volumetric timeseries:
 
-![napari viewer with an image of a cell undergoing mitosis. The scroll bar below the canvas controls the timeseries, allowing different stages of mitosis to be visible.](./images/mitosis.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../_static/images/mitosis.webm" type="video/webm" />
+    <source src="../_static/images/mitosis.mp4" type="video/mp4" />
+    <img src="../_static/images/mitosis.png"
+      title="Your browser does not support the video tag"
+      alt="napari viewer with an image of a cell undergoing mitosis. The scroll bar below the canvas controls the timeseries, allowing different stages of mitosis to be visible."
+    >
+  </video>
+</figure>
+```
 
 ```{note}
 Switching to 3D mode for a very large data set could trigger computation that
@@ -147,8 +158,18 @@ napari.view_image(retina, name='retina', scale=[1,10,1,1])
 viewer.layers['retina'].scale = [1,10,1,1]
 ```
 
-![napari viewer with an image where all layers are scaled equally; when rotated, the image appears flat. By using console below the canvas and applying a scale factor to one of the dimensions, the image's volume becomes apparent.](images/scaling.webm)
-
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../_static/images/scaling.webm" type="video/webm" />
+    <source src="../_static/images/scaling.mp4" type="video/mp4" />
+    <img src="../_static/images/scaling.png"
+      title="Your browser does not support the video tag"
+      alt="napari viewer with an image where all layers are scaled equally; when rotated, the image appears flat. By using console below the canvas and applying a scale factor to one of the dimensions, the image's volume becomes apparent."
+    >
+  </video>
+</figure>
+```
 
 ## Translating layers
 

diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md
@@ -145,7 +145,18 @@ napari to seamlessly browse enormous datasets that are loaded in the right way.
 For example, here we are browsing over 100GB of lattice lightsheet data stored
 in a `zarr` file:
 
-![napari viewer with an image layer of lattice lightsheet data opened. It can be browsed using the slider at the bottom of the viewer.](../../images/LLSM.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/LLSM.webm" type="video/webm" />
+    <source src="../../_static/images/LLSM.mp4" type="video/mp4" />
+    <img src="../../_static/images/LLSM.png"
+      title="Your browser does not support the video tag"
+      alt="napari viewer with an image layer of lattice lightsheet data opened. It can be browsed using the slider at the bottom of the viewer."
+    >
+  </video>
+</figure>
+```
 
 ## Multiscale images
 
@@ -162,7 +173,18 @@ viewed in 2D or incredibly large 3D images when viewed in 3D. For example this
 easily browsed as at each moment in time we only load the level of the
 multiscale image and the part of the image that needs to be displayed:
 
-![napari viewer with a large image layer zoomed all the way in and all the way out in a matter of seconds thanks to multiscale image support.](../../images/pathology.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/pathology.webm" type="video/webm" />
+    <source src="../../_static/images/pathology.mp4" type="video/mp4" />
+    <img src="../../_static/images/pathology.png"
+      title="Your browser does not support the video tag"
+      alt="napari viewer with a large image layer zoomed all the way in and all the way out in a matter of seconds thanks to multiscale image support."
+    >
+  </video>
+</figure>
+```
 
 This example had precomputed multiscale images stored in a `zarr` file, which is
 best for performance. If you don't have a precomputed multiscale image but try

diff --git a/docs/howtos/layers/labels.md b/docs/howtos/layers/labels.md
@@ -151,7 +151,8 @@ layer:
   label, or you want to replace only one label with a different one, or maybe
   you have painted around the edge of a region and you want to quickly fill in
   its inside. To do this you can select the `fill bucket` tool by clicking on
-  its icon in the `layer controls` panel, and then click on a target region of interest in the layer. The fill bucket will fill using the currently selected
+  its icon in the `layer controls` panel, and then click on a target region of
+  interest in the layer. The fill bucket will fill using the currently selected
   label. If nothing is selected the entire layer will be filled with that label.
 
   By default, the `fill bucket` will change only contiguous or connected pixels
@@ -301,26 +302,75 @@ and `fill bucket` tools. Below we show how to use these tools by performing
 common editing tasks on connected components (keep the `contiguous` box checked).
 
 * Creating or drawing a connected component
-  ![Using the paintbrush and fill bucket tools to draw a connected component](../../images/draw_component.webm)
+
+  ```{raw} html
+  <figure>
+    <video width="100%" controls autoplay loop muted playsinline>
+      <source src="../../_static/images/draw_component.webm" type="video/webm" />
+      <source src="../../_static/images/draw_component.mp4" type="video/mp4" />
+      <img src="../../_static/images/draw_component.png"
+        title="Your browser does not support the video tag"
+        alt="Using the paintbrush and fill bucket tools to draw a connected component."
+      >
+    </video>
+  </figure>
+  ```
 
   * Press `m` to select a label color that has not been used.
   * Select the `paintbrush` tool and draw a closed contour around the object.
   * Select the `fill bucket` tool and click inside the contour to assign the
     label to all pixels of the object.
 
 * Deleting a connected component
-  ![Deleting selected labels](../../images/delete_label.webm)
+
+  ```{raw} html
+  <figure>
+    <video width="100%" controls autoplay loop muted playsinline>
+      <source src="../../_static/images/delete_label.webm" type="video/webm" />
+      <source src="../../_static/images/delete_label.mp4" type="video/mp4" />
+      <img src="../../_static/images/delete_label.png"
+        title="Your browser does not support the video tag"
+        alt="Deleting selected labels."
+      >
+    </video>
+  </figure>
+  ```
+
   Select the background label with the `color picker` or press `x`, then use the 
   `fill bucket` to set all pixels of the
   connected component to background.
 
 * Merging connected components
-  ![Selecting a label and merging with a connecting label](../../images/merge_labels.webm)
+
+  ```{raw} html
+  <figure>
+    <video width="100%" controls autoplay loop muted playsinline>
+      <source src="../../_static/images/merge_labels.webm" type="video/webm" />
+      <source src="../../_static/images/merge_labels.mp4" type="video/mp4" />
+      <img src="../../_static/images/merge_labels.png"
+        title="Your browser does not support the video tag"
+        alt="Selecting a label and merging with a connecting label."
+      >
+    </video>
+  </figure>
+  ```
+
   * Select the label of one of the components with the `color picker` tool.
   * Select the `fill bucket` and fill the components to be merged.
 
 * Splitting a connected component
-  ![Using the paintbrush tool to split a label into two](../../images/split_label.webm)
+  ```{raw} html
+  <figure>
+    <video width="100%" controls autoplay loop muted playsinline>
+      <source src="../../_static/images/split_label.webm" type="video/webm" />
+      <source src="../../_static/images/split_label.mp4" type="video/mp4" />
+      <img src="../../_static/images/split_label.png"
+        title="Your browser does not support the video tag"
+        alt="Using the paintbrush tool to split a label into two."
+      >
+    </video>
+  </figure>
+  ```
   Splitting a connected component will introduce an additional object.
   * Select the background label with the `color picker` or press `x`.
   * Use the `paintbrush` tool to draw a dividing line where you want to split

diff --git a/docs/howtos/layers/points.md b/docs/howtos/layers/points.md
@@ -283,7 +283,18 @@ dimensions of the layer, allowing you to browse volumetric timeseries data and
 other high dimensional data. See for example these points overlaid on an image
 in both 2D and 3D:
 
-![image: smFISH with points overlaid](../../images/smFISH.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/smFISH.webm" type="video/webm" />
+    <source src="../../_static/images/smFISH.mp4" type="video/mp4" />
+    <img src="../../_static/images/smFISH.png"
+      title="Your browser does not support the video tag"
+      alt="smFISH with points overlaid."
+    >
+  </video>
+</figure>
+```
 
 ### Adding, deleting, and selecting points
 
@@ -434,4 +445,15 @@ layer using the `symbol` keyword argument.
 Here you can see an example of adding, selecting, deleting points, and changing
 their properties:
 
-![image: editing points](../../images/editing_points.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/editing_points.webm" type="video/webm" />
+    <source src="../../_static/images/editing_points.mp4" type="video/mp4" />
+    <img src="../../_static/images/editing_points.png"
+      title="Your browser does not support the video tag"
+      alt="Selecting and changing points color, size and symbol in napari."
+    >
+  </video>
+</figure>
+```
diff --git a/docs/howtos/layers/shapes.md b/docs/howtos/layers/shapes.md
@@ -44,7 +44,18 @@ All shapes are edited in the same way:
    `shift` key down and when finished release the mouse button first! Here is a
    shape being resized:
 
-   ![image: shape resizing](../../images/shape_resizing.webm)
+   ```{raw} html
+   <figure>
+     <video width="100%" controls autoplay loop muted playsinline>
+       <source src="../../_static/images/shape_resizing.webm" type="video/webm" />
+       <source src="../../_static/images/shape_resizing.mp4" type="video/mp4" />
+       <img src="../../_static/images/shape_resizing.png"
+         title="Your browser does not support the video tag"
+         alt="Resizing a shape"
+       >
+     </video>
+   </figure>
+   ```
 
 4. Change the face or edge color by clicking on the thumbnail to the right of
    `face color:` or `edge color:` and choosing or creating a color from the
@@ -72,7 +83,18 @@ new slice values.
 
 ### Adding (inserting), editing, and deleting (removing) individual vertices
 
-![animation of napari viewer with a shapes layer bounded by vertices over an initial static image. The shapes are selected and the vertices moved by the mouse pointer, resulting in new shapes.](../../images/shape_vertex_editing.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/shape_vertex_editing.webm" type="video/webm" />
+    <source src="../../_static/images/shape_vertex_editing.mp4" type="video/mp4" />
+    <img src="../../_static/images/shape_vertex_editing.png"
+      title="Your browser does not support the video tag"
+      alt="animation of napari viewer with a shapes layer bounded by vertices over an initial static image. The shapes are selected and the vertices moved by the mouse pointer, resulting in new shapes."
+    >
+  </video>
+</figure>
+```
 
 ### Creating a new `shapes` layer
 
@@ -545,7 +567,18 @@ dimensions of the layer, allowing you to browse volumetric timeseries data and
 other high dimensional data. See [](../../gallery/nD_shapes) to see shapes in
 both 2D and 3D:
 
-![A stack of colorful polygon shapes over an image layer. The view alternates between 2D and 3D views of the data.](../../images/nD_shapes.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/nD_shapes.webm" type="video/webm" />
+    <source src="../../_static/images/nD_shapes.mp4" type="video/mp4" />
+    <img src="../../_static/images/nD_shapes.png"
+      title="Your browser does not support the video tag"
+      alt="A stack of colorful polygon shapes over an image layer. The view alternates between 2D and 3D views of the data."
+    >
+  </video>
+</figure>
+```
 
 Also note that for a multidimensional shape to be displayed on a given view
 slice, all of its non-displayed coordinates must match the coordinates of that
@@ -602,4 +635,15 @@ opacity of individual shapes you need to adjust the alpha value in the
 Here you can see an example of adding, selecting, and editing shapes and
 changing their properties:
 
-![image: editing shapes](../../images/editing_shapes.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/editing_shapes.webm" type="video/webm" />
+    <source src="../../_static/images/editing_shapes.mp4" type="video/mp4" />
+    <img src="../../_static/images/editing_shapes.png"
+      title="Your browser does not support the video tag"
+      alt="Editing shapes properties in napari."
+    >
+  </video>
+</figure>
+```
diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md
@@ -123,7 +123,18 @@ The number of dimensions sliders will be 2 or 3 less than the total number of
 dimensions of the layer, allowing you to browse volumetric timeseries data and
 other high dimensional data. An example is these brain surfaces rendered in 3D:
 
-![image: brain surface](../../images/brain_surface.webm)
+```{raw} html
+<figure>
+  <video width="100%" controls autoplay loop muted playsinline>
+    <source src="../../_static/images/brain_surface.webm" type="video/webm" />
+    <source src="../../_static/images/brain_surface.mp4" type="video/mp4" />
+    <img src="../../_static/images/brain_surface.png"
+      title="Your browser does not support the video tag"
+      alt="Brain surface in 3D view."
+    >
+  </video>
+</figure>
+```
 
 ## Working with colormaps