Examples: add PyVista/VTK example (#132)

Co-authored-by: LSchueler <mostem@posteo.de>

.gitignore

@@ -125,3 +125,4 @@ docs/source/generated/
 
 *.vtu
 *.vtr
+*.vtk

docs/source/conf.py

@@ -25,6 +25,7 @@
 import datetime
 import warnings
 
+
 warnings.filterwarnings(
     "ignore",
     category=UserWarning,
@@ -260,11 +261,22 @@ def setup(app):
     "emcee": ("https://emcee.readthedocs.io/en/latest/", None),
 }
 
-
 # -- Sphinx Gallery Options
 from sphinx_gallery.sorting import FileNameSortKey
 
+# Use pyvista's image scraper for example gallery
+# import pyvista
+# https://github.com/tkoyama010/pyvista-doc-translations/blob/85c835a3ada3a2adefac06ba70e15a101ffa9162/conf.py#L21
+# https://github.com/simpeg/discretize/blob/f414dd7ee7c5ba9a141cb2c37d4b71fdc531eae8/docs/conf.py#L334
+# Make sure off screen is set to true when building locally
+# pyvista.OFF_SCREEN = True
+# # necessary when building the sphinx gallery
+# pyvista.BUILDING_GALLERY = True
+# # Optional - set parameters like theme or window size
+# pyvista.set_plot_theme("document")
+
 sphinx_gallery_conf = {
+    # "image_scrapers": ("pyvista", "matplotlib"),
     "remove_config_comments": True,
     # only show "print" output as output
     "capture_repr": (),
@@ -304,9 +316,10 @@ def setup(app):
     "backreferences_dir": None,
     # Modules for which function level galleries are created.  In
     "doc_module": "gstools",
+    # "first_notebook_cell": (
+    #     "%matplotlib inline\n"
+    #     "from pyvista import set_plot_theme\n"
+    #     "set_plot_theme('document')"
+    # ),
     "matplotlib_animations": True,
-    # "image_scrapers": ('pyvista', 'matplotlib'),
-    # "first_notebook_cell": ("%matplotlib inline\n"
-    #                         "from pyvista import set_plot_theme\n"
-    #                         "set_plot_theme('document')"),
 }

examples/00_misc/01_export.py

@@ -1,12 +1,24 @@
 """
 Exporting Fields
 ----------------
-"""
 
+GSTools provides simple exporting routines to convert generated fields to
+`VTK <https://vtk.org/>`__ files.
+
+These can be viewed for example with `Paraview <https://www.paraview.org/>`__.
+"""
+# sphinx_gallery_thumbnail_path = 'pics/paraview.png'
 import gstools as gs
 
 x = y = range(100)
 model = gs.Gaussian(dim=2, var=1, len_scale=10)
 srf = gs.SRF(model)
 field = srf((x, y), mesh_type="structured")
 srf.vtk_export(filename="field")
+
+###############################################################################
+# The result displayed with Paraview:
+#
+# .. image:: https://raw.githubusercontent.com/GeoStat-Framework/GeoStat-Framework.github.io/master/img/paraview.png
+#    :width: 400px
+#    :align: center

examples/01_random_field/06_pyvista_support.py

@@ -0,0 +1,56 @@
+"""
+Using PyVista meshes
+--------------------
+
+`PyVista <https://www.pyvista.org>`__ is a helper module for the
+Visualization Toolkit (VTK) that takes a different approach on interfacing with
+VTK through NumPy and direct array access.
+
+It provides mesh data structures and filtering methods for spatial datasets,
+makes 3D plotting simple and is built for large/complex data geometries.
+
+The :any:`Field.mesh` method enables easy field creation on PyVista meshes
+used by the :any:`SRF` or :any:`Krige` class.
+"""
+# sphinx_gallery_thumbnail_path = 'pics/GS_pyvista_cut.png'
+import pyvista as pv
+import gstools as gs
+
+###############################################################################
+# We create a structured grid with PyVista containing 50 segments on all three
+# axes each with a length of 2 (whatever unit).
+
+dim, spacing = (50, 50, 50), (2, 2, 2)
+grid = pv.UniformGrid(dim, spacing)
+
+###############################################################################
+# Now we set up the SRF class as always. We'll use an anisotropic model.
+
+model = gs.Gaussian(dim=3, len_scale=[16, 8, 4], angles=(0.8, 0.4, 0.2))
+srf = gs.SRF(model, seed=19970221)
+
+###############################################################################
+# The PyVista mesh can now be directly passed to the :any:`SRF.mesh` method.
+# When dealing with meshes, one can choose if the field should be generated
+# on the mesh-points (`"points"`) or the cell-centroids (`"centroids"`).
+#
+# In addition we can set a name, under which the resulting field is stored
+# in the mesh.
+
+srf.mesh(grid, points="points", name="random-field")
+
+###############################################################################
+# Now we have access to PyVista's abundancy of methods to explore the field.
+#
+# .. note::
+#    PyVista is not working on readthedocs, but you can try it out yourself by
+#    uncommenting the following line of code.
+
+# grid.contour(isosurfaces=8).plot()
+
+###############################################################################
+# The result should look like this:
+#
+# .. image:: https://github.com/GeoStat-Framework/GeoStat-Framework.github.io/raw/master/img/GS_pyvista_cut.png
+#    :width: 400px
+#    :align: center

examples/08_geo_coordinates/README.rst

@@ -1,5 +1,5 @@
-Tutorial 8: Geographic Coordinates
-==================================
+Geographic Coordinates
+======================
 
 GSTools provides support for
 `geographic coordinates <https://en.wikipedia.org/wiki/Geographic_coordinate_system>`_