Merge pull request #91 from Louis-Pujol/main

Add a scraper for pyvista

docs/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### 0.9.0 - Pyvista
+
+- Pyvista can now be used in gallery examples as in `sphinx-gallery`. PR [#91](https://github.com/smarie/mkdocs-gallery/pull/91) by [Louis-Pujol](https://github.com/Louis-Pujol)
+
 ### 0.8.0 - Mayavi
 
  - Mayavi can now be used in gallery examples just as in `sphinx-gallery`. PR [#69](https://github.com/smarie/mkdocs-gallery/pull/69) by [GenevieveBuckley](https://github.com/GenevieveBuckley)

docs/examples/plot_11_pyvista.py

@@ -0,0 +1,55 @@
+"""
+Example with the pyvista 3d plotting library
+============================================
+
+Mkdocs-Gallery supports examples made with the
+[pyvista library](https://docs.pyvista.org/version/stable/). 
+
+In order to use pyvista, the [`conf_script` of the project](../../index.md#b-advanced) should include the
+following lines to adequatly configure pyvista:
+
+```python
+import pyvista
+
+pyvista.BUILDING_GALLERY = True
+pyvista.OFF_SCREEN = True
+
+conf = {
+    ...,
+    "image_scrapers": ("pyvista", ...),
+}
+```
+"""
+import pyvista as pv
+
+# %%
+# You can display an animation as a gif
+
+sphere = pv.Sphere()
+pl = pv.Plotter()
+pl.enable_hidden_line_removal()
+pl.add_mesh(sphere, show_edges=True, color="tan")
+# for this example
+pl.open_gif("animation.gif", fps=10)
+# alternatively, to disable movie generation:
+# pl.show(auto_close=False, interactive=False)
+delta_x = 0.05
+center = sphere.center
+for angle in range(0, 360, 10):
+
+    rot = sphere.rotate_x(angle, point=(0, 0, 0), inplace=False)
+
+    pl.clear_actors()
+    pl.add_mesh(rot, show_edges=True, color="tan")
+    pl.write_frame()
+
+
+pl.show()
+
+# %%
+# or simply show a static plot
+
+sphere = pv.Sphere()
+pl = pv.Plotter()
+pl.add_mesh(sphere, show_edges=True, color="tan")
+pl.show()

docs/gallery_conf.py

@@ -4,6 +4,10 @@
 import plotly.io as pio
 pio.renderers.default = 'sphinx_gallery'
 
+import pyvista
+pyvista.BUILDING_GALLERY = True
+pyvista.OFF_SCREEN = True
+
 from mkdocs_gallery.gen_gallery import DefaultResetArgv
 
 min_reported_time = 0

mkdocs.yml

@@ -34,6 +34,7 @@ plugins:
       image_scrapers:
         - matplotlib
         - mayavi
+        - pyvista
       compress_images: ['images', 'thumbnails']
       # specify the order of examples to be according to filename
       within_subsection_order: FileNameSortKey

noxfile.py

@@ -210,6 +210,8 @@ def flake8(session: PowerSession):
     "seaborn",
     "statsmodels",
     "plotly",
+    "pyvista",
+    "imageio",
     # "memory_profiler",
     "pillow",  # PIL, required for image rescaling
 ]

src/mkdocs_gallery/scrapers.py

@@ -34,6 +34,7 @@
     "clean_modules",
     "matplotlib_scraper",
     "mayavi_scraper",
+    "pyvista_scraper",
 ]
 
 
@@ -326,10 +327,57 @@ def mayavi_scraper(block, script: GalleryScript):
     mlab.close(all=True)
     return figure_md_or_html(image_paths, script)
 
+def pyvista_scraper(block, script: GalleryScript):
+    """Scrape PyVista images.
+
+    Parameters
+    ----------
+    block : tuple
+        A tuple containing the (label, content, line_number) of the block.
+
+    script : GalleryScript
+        Script being run
+
+    Returns
+    -------
+    md : str
+        The ReSTructuredText that will be rendered to HTML containing
+        the images. This is often produced by :func:`figure_md_or_html`.
+    """
+    import pyvista as pv
+    import pyvista.plotting as pv_plt
+    import shutil
+
+    if not pv.BUILDING_GALLERY:
+        raise RuntimeError(pv.BUILDING_GALLERY_ERROR_MSG)
+    if not pv.OFF_SCREEN:
+        raise RuntimeError("set pyvista.OFF_SCREEN=True to use the pyvista image scraper.")
+
+    image_path_iterator = script.run_vars.image_path_iterator
+    image_paths = list()
+    try:
+        # pyvista >= 0.40
+        figures = pv_plt.plotter._ALL_PLOTTERS
+    except AttributeError:
+        # pyvista < 0.40
+        figures = pv_plt._ALL_PLOTTERS
+    for _, plotter in figures.items():
+        fname = next(image_path_iterator)
+        if hasattr(plotter, "_gif_filename"):
+            # move gif to fname
+            fname = fname.with_suffix('').with_suffix(".gif")
+            shutil.move(plotter._gif_filename, fname)
+        else:
+            plotter.screenshot(fname)
+        image_paths.append(fname)
+    pv.close_all()  # close and clear all plotters
+    return figure_md_or_html(image_paths, script)
+
 
 _scraper_dict = dict(
     matplotlib=matplotlib_scraper,
     mayavi=mayavi_scraper,
+    pyvista=pyvista_scraper,
 )