Demonstration using pyvista to create figures for cookbook documentation

[JarettBakerDunn]

This pull request is a work in progress demonstration of a new workflow for generating documentation figures using pyvista instead of paraview. It also is meant to serve as a central location to collect feedback on this idea and implementation. The idea behind creating these pyvista scripts is to make the process of updating cookbook documentation easier whenever changes to ASPECT or the cookbooks themselves cause the figures in the documentation to go out of date. The thinking is that it would be much easier to run a python script to generate a figure than to recreate a specific figure in Paraview. Also, using pyvista scripts to generate figures presents the opportunity to standardize the colormaps used in the cookbook documentation and make sure that the colormaps chosen are accessible.

The scripts in this pull request use colormaps from Fabio Crameri. The new pyvista-generated image added to the convectionBox2D benchmark is meant to demonstrate using one of Fabio Crameri’s diverging gradient colormaps to visualize temperature. The images added to the crustal deformation cookbook are meant to demonstrate using a sequential colormap to visualize viscosity. They currently use the “vik” diverging gradient colormap and the “batlow” sequential gradient colormap.

We are also looking for feedback on which colormaps to use. Are there better sequential and diverging gradient colormaps in Fabio Crameri’s scientific color maps or elsewhere?

[gassmoeller]

Thanks for making the PR and for the suggestions! As I mentioned I am all for making the figures easier to reproduce and update, but this PR is meant as a discussion space, so if anyone else wants to comment please let us know what you think about it as well.

To your questions, and a few thoughts I had when skimming through your PR:

• Your chosen colorscales looks great to me, whenever we can replace the terrible rainbow colorscales of Paraview and Visit we should do it. Also Fabio's colorscales are generally considered some of the best in our discipline. I also think you picked the right ones out of his package.
• You use a python package to make use of the colorscales, can you add that package to doc/sphinx/environment.yml? That way anyone who wants to rebuild the documentation would have the package needed to recreate the documentation figures
• you used pyvista_doc.py as the name for the scripts, but this is not a self-explaining name (a user may not know pyvista, and it does not create documentation, it creates figures), I would suggest a name like plot_figures.py
• you used figX as part of the file name of the pictures, was this just to make comparison easier? For the final PR do not use the number of figure in the file name (since it will likely change). Instead I would try to reuse the name of the figures that already exist, that will give you the smallest number of broken links in the documentation

I saw a few minor things in the python scripts, but before we go there we should get a general feel what others think about the change. Thanks for taking the time for this!

[danieldouglas92]

Aside from Rene's comments I don't have any other things to suggest on the existing content of the PR, but I just want to say that I think that this is great! I've definitely run into the issue where I save a figure that I made in Paraview for a cookbook without creating a state file, which I then need to recreate in the future when I want to modify something.

I'm just curious if you have thought about how to do this retroactively? Is there a good way to go through all the existing cookbooks/benchmarks and automate the creation of these pyvista figures? Or for now is this just a precedent that will be set for future cookbooks/benchmark figures?

[tjhei]

This looks great!

Is there a way to automatically crop the pngs to remove unnecessary white space around the figures? If not within pyvista (though, I assume you can adjust the aspect ratio at least), we could use imagemagick (convert -trim)

[JarettBakerDunn]

Thanks for the feedback everyone. I think I addressed Timo and Rene's feedback in the code (But I am not sure that I correctly added the colormaps module to doc/sphinx/environment.yml). I also added a shell script which automatically runs all of the pyvista scripts for the convection-box notebook. I only updated the convection-box scripts for now, because it is a bit more work to update the crustal deformation cookbook since for the crustal_deformation cookbook I need to review how to plot multiple pyvista meshes in the same image (though it looks possible without too much trouble).

Daniel, glad this looks like a good idea! As far as I know there is unfortunately no way to automatically generate these pyvista scripts. Do you have any ideas about how that might work? I think that the current plan was to make some example pyvista scripts which demonstrate the techniques needed to convert any cookbook figure into a pyvista script. Once those example scripts exist then people (probably me and any others who are interested) could methodically update the older cookbooks by hand as they have time.