{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"%matplotlib inline"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Adding a New Gallery Example {#add_example_example}\n\nThis example demonstrates how to add a new PyVista [Sphinx\nGallery](https://sphinx-gallery.github.io/) example as well as being a\ntemplate that can be used in their creation.\n\nEach example should have a reference tag/key in the form:\n\n`.. _<example-name>_example:`\n\nThe `.. _` is necessary. Everything that follows is your reference tag,\nwhich can potentially be used within a docstring. As convention, we keep\nall references all in `snake_case`.\n\nThis section should give a brief overview of what the example is about\nand/or demonstrates. The title should be changed to reflect the topic\nyour example covers.\n\nNew examples should be added as python scripts to:\n\n`examples/<index>-<directory-name>/<some-example>.py`\n\n::: note\n::: title\nNote\n:::\n\nAvoid creating new directories unless absolutely necessary.If you *must*\ncreate a new folder, make sure to add a `README.txt` containing a\nreference, a title and a single sentence description of the folder.\nOtherwise the new folder will be ignored by Sphinx.\n:::\n\nExample file names should be hyphen separated snake case:\n\n`some-example.py`\n\nAfter this preamble is complete, the first code block begins. This is\nwhere you typically set up your imports.\n\n::: note\n::: title\nNote\n:::\n\nBy default, the documentation scrapper will generate both a static image\nand an interactive widget for each plot. If you want to turn this\nfeature off define at the top of your file:\n\n`# sphinx_gallery_start_ignore`\n\n`PYVISTA_GALLERY_FORCE_STATIC_IN_DOCUMENT = True`\n\n`# sphinx_gallery_end_ignore`\n\nIf you want to use static images only for some of your plots. Define\n`PYVISTA_GALLERY_FORCE_STATIC` before the `plot`/`show` command that\nproduces the image you want to turn into static.\n\n``` \n...\npl.show() # this will be interactive plot\n\n...\npl.show() # this will be static plot\n```\n:::\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"import pyvista as pv\nfrom pyvista import examples"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Section Title\n\nCode blocks can be broken up with text \\\"sections\\\" which are\ninterpreted as restructured text.\n\nThis will also be translated into a markdown cell in the generated\njupyter notebook or the HTML page.\n\nSections can contain any information you may have regarding the example\nsuch as step-by-step comments or notes regarding motivations etc.\n\nAs in Jupyter notebooks, if a statement is unassigned at the end of a\ncode block, output will be generated and printed to the screen according\nto its `__repr__` method. Otherwise, you can use `print()` to output\ntext.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"# Create a dataset and exercise it's repr method\ndataset = pv.Sphere()\ndataset"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Plots and images\n\nIf you use anything that outputs an image (for example,\n`pyvista.Plotter.show`{.interpreted-text role=\"func\"}) the resulting\nimage will be rendered within the output HTML.\n\n::: note\n::: title\nNote\n:::\n\nUnless `sphinx_gallery_thumbnail_number = <int>` is included at the top\nof the example script, first figure (this one) will be used for the\ngallery thumbnail image.\n\nAlso note that this image number uses one based indexing.\n:::\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"dataset.plot(text='Example Figure')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Caveat - Plotter must be within One Cell\n\nIt\\'s not possible for a single `pyvista.Plotter`{.interpreted-text\nrole=\"class\"} object across multiple cells because these are closed out\nautomatically at the end of a cell.\n\nHere we just exercise the `pyvista.Actor`{.interpreted-text\nrole=\"class\"} `repr` for demonstrating why you might want to instantiate\na plotter without showing it in the same cell.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"pl = pv.Plotter()\nactor = pl.add_mesh(dataset)\nactor"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# This Cell Cannot Run the Plotter\n\nThe plotter will already be closed by `sphinx_gallery`.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"# This cannot be run here because the plotter is already closed and would raise\n# an error:\n# >>> pl.show()\n\n# You can, however, close out the plotter or access other attributes.\npl.close()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Animations\n\nYou can even create animations, and while there is a full example in\n`movie_example`{.interpreted-text role=\"ref\"}, this cell explains how\nyou can create an animation within a single cell.\n\nHere, we explode a simple sphere.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"pl = pv.Plotter(off_screen=True)\n\n# optimize for size\npl.open_gif('example_movie.gif', palettesize=16)\n\nsphere = pv.Sphere(theta_resolution=10, phi_resolution=10)\n\n# Add initial mesh to setup the camera\nactor = pl.add_mesh(sphere)\npl.background_color = 'w'\n\n# clear and overwrite the mesh on each frame\nn_frames = 20\nfor i in range(n_frames):\n exploded = sphere.explode(factor=i / (n_frames * 2)).extract_surface()\n actor.mapper.dataset.copy_from(exploded)\n pl.camera.reset_clipping_range()\n pl.write_frame() # Write this frame\n\n# Be sure to close the plotter when finished\npl.close()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Adding Example Files\n\nPyVista has a variety of example files all stored at\n[pyvista/vtk_data](https://github.com/pyvista/vtk-data), and you can add\nthe file by following the directions there.\n\nUnder the hood, PyVista uses [pooch](https://github.com/fatiando/pooch),\nand you can easily access any files added with\n`pyvista.examples.downloads.download_file`{.interpreted-text\nrole=\"func\"}.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"filename = examples.download_file('bunny.ply')\nfilename"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Adding a Wrapped Example\n\nWhile it\\'s possible to simply download a file and then read it in,\nit\\'s better for you to write a wrapped `download_<example-dataset>()`\nwithin `/pyvista/examples/downloads.py`. For example `download_bunny()\n<pyvista.examples.downloads.download_bunny>`{.interpreted-text\nrole=\"func\"} downloads and reads with `pyvista.read`{.interpreted-text\nrole=\"func\"}.\n\nIf you intend on adding an example file, you should add a new function\nin `downloads.py` to make it easy for users to add example files.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"dataset = examples.download_bunny()\ndataset\n\n\n# Making a Pull Request\n# ~~~~~~~~~~~~~~~~~~~~~\n# Once your example is complete and you've verified it builds locally, you can\n# make a pull request (PR).\n#\n# Branches containing examples should be prefixed with `docs/` as per the branch\n# naming conventions found in out `Contributing Guidelines\n# <https://github.com/pyvista/pyvista/blob/main/CONTRIBUTING.rst>`_.\n#\n# .. note::\n# You only need to create the Python source example (``*.py``). The jupyter\n# notebook and the example HTML will be auto-generated via `sphinx-gallery\n# <https://sphinx-gallery.github.io/>`_."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.2"
}
},
"nbformat": 4,
"nbformat_minor": 0
}