Debian Codegraph @

examples/99-advanced/add_example.py

raw
1 r"""
2 .. _add_example_example:
3
4 Adding a New Gallery Example
5 ----------------------------
6 This example demonstrates how to add a new PyVista `Sphinx Gallery
7 <https://sphinx-gallery.github.io/>`_ example as well as being a template that
8 can be used in their creation.
9
10 Each example should have a reference anchor in the form:
11
12 ``.. _<example_name>_example:``
13
14 The ``.. _`` is necessary. Everything that follows is your reference anchor, which
15 can potentially be used within a docstring. As convention, we keep all
16 references all in ``snake_case``.
17
18 This section should give a brief overview of what the example is about and/or
19 demonstrates. The title should be changed to reflect the topic your example
20 covers.
21
22 New examples should be added as python scripts to:
23
24 ``examples/<index>-<directory-name>/<some_example>.py``
25
26 .. note::
27 Avoid creating new directories unless absolutely necessary.If you *must*
28 create a new folder, make sure to add a ``README.txt`` containing a
29 reference, a title and a single sentence description of the folder.
30 Otherwise the new folder will be ignored by Sphinx.
31
32 Example file names should be underscore-separated snake case:
33
34 ``some_example.py``
35
36 After this preamble is complete, the first code block begins. This is where you
37 typically set up your imports.
38
39 .. note::
40 By default, the documentation scrapper will generate both a static image and
41 an interactive widget for each plot. If you want to turn this feature off,
42 define at the top of your file:
43
44 .. code-block::
45
46 # \sphinx_gallery_start_ignore (remove the \)
47 PYVISTA_GALLERY_FORCE_STATIC_IN_DOCUMENT = True
48 # \sphinx_gallery_end_ignore (remove the \)
49
50 Note that the ``sphinx_gallery_start_ignore`` and ``sphinx_gallery_end_ignore``
51 flags have been escaped to appear in the current documentation.
52 See ``Sphinx-Gallery`` `documentation <https://sphinx-gallery.github.io/stable/configuration.html#hiding-code-blocks>`_
53 for more details.
54
55 If you want to use static images only for some of your plots, define
56 ``PYVISTA_GALLERY_FORCE_STATIC`` before the ``plot``/``show`` command that
57 produces the image you want to turn into static:
58
59 .. code-block::
60
61 ...
62 pl.show() # this will be interactive plot
63
64 # \sphinx_gallery_start_ignore (remove the \)
65 PYVISTA_GALLERY_FORCE_STATIC = True
66 # \sphinx_gallery_end_ignore (remove the \)
67 ...
68 pl.show() # this will be static plot
69
70 """
71
72
73 # %%
74 # Section Title
75 # ~~~~~~~~~~~~~
76 # Code blocks can be broken up with text "sections" which are interpreted as
77 # restructured text.
78 #
79 # This will also be translated into a markdown cell in the generated jupyter
80 # notebook or the HTML page.
81 #
82 # Sections can contain any information you may have regarding the example
83 # such as step-by-step comments or notes regarding motivations etc.
84 #
85 # As in Jupyter notebooks, if a statement is unassigned at the end of a code
86 # block, output will be generated and printed to the screen according to its
87 # ``__repr__`` method. Otherwise, you can use ``print()`` to output text.
88
89 import pyvista as pv
90 from pyvista import examples
91
92 # Create a dataset and exercise it's repr method
93 dataset = pv.Sphere()
94 dataset
95
96
97 # %%
98 # Plots and images
99 # ~~~~~~~~~~~~~~~~
100 # If you use anything that outputs an image (for example,
101 # :func:`pyvista.Plotter.show`) the resulting image will be rendered within the
102 # output HTML.
103 #
104 # .. note::
105 # Unless ``sphinx_gallery_thumbnail_number = <int>`` is included at the top
106 # of the example script, first figure (this one) will be used for the
107 # gallery thumbnail image.
108 #
109 # Also note that this image number uses one based indexing.
110
111 dataset.plot(text='Example Figure')
112
113
114 # %%
115 # Caveat - Plotter must be within One Cell
116 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117 # It's not possible for a single :class:`pyvista.Plotter` object across
118 # multiple cells because these are closed out automatically at the end of a
119 # cell.
120 #
121 # Here we just exercise the :class:`pyvista.Actor` ``repr`` for demonstrating
122 # why you might want to instantiate a plotter without showing it in the same
123 # cell.
124
125 pl = pv.Plotter()
126 actor = pl.add_mesh(dataset)
127 actor
128
129
130 # %%
131 # This Cell Cannot Run the Plotter
132 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 # The plotter will already be closed by ``sphinx_gallery``.
134
135 # This cannot be run here because the plotter is already closed and would raise
136 # an error:
137 # >>> pl.show()
138
139 # You can, however, close out the plotter or access other attributes.
140 pl.close()
141
142
143 # %%
144 # Animations
145 # ~~~~~~~~~~
146 # You can even create animations, and while there is a full example in
147 # :ref:`movie_example`, this cell explains how you can create an animation
148 # within a single cell.
149 #
150 # Here, we explode a simple sphere.
151
152 pl = pv.Plotter(off_screen=True)
153
154 # optimize for size
155 pl.open_gif('example_movie.gif', palettesize=16)
156
157 sphere = pv.Sphere(theta_resolution=10, phi_resolution=10)
158
159 # Add initial mesh to setup the camera
160 actor = pl.add_mesh(sphere)
161 pl.background_color = 'w'
162
163 # clear and overwrite the mesh on each frame
164 n_frames = 20
165 for i in range(n_frames):
166 exploded = sphere.explode(factor=i / (n_frames * 2)).extract_surface(algorithm=None)
167 actor.mapper.dataset.copy_from(exploded)
168 pl.camera.reset_clipping_range()
169 pl.write_frame() # Write this frame
170
171 # Be sure to close the plotter when finished
172 pl.close()
173
174
175 # %%
176 # Adding Example Files
177 # ~~~~~~~~~~~~~~~~~~~~
178 # PyVista has a variety of example files all stored at `pyvista/data
179 # <https://github.com/pyvista/data>`_, and you can add the file by
180 # following the directions there.
181 #
182 # Under the hood, PyVista uses `pooch <https://github.com/fatiando/pooch>`_,
183 # and you can easily access any files added with
184 # :func:`pyvista.examples.downloads.download_file`.
185
186 filename = examples.download_file('bunny.ply')
187 filename
188
189
190 # %%
191 # Adding a Wrapped Example
192 # ~~~~~~~~~~~~~~~~~~~~~~~~
193 # While it's possible to simply download a file and then read it in, it's
194 # better for you to write a wrapped ``download_<example_dataset>()`` within
195 # ``/pyvista/examples/downloads.py``. For example :func:`download_bunny()
196 # <pyvista.examples.downloads.download_bunny>` downloads and reads with
197 # :func:`pyvista.read`.
198 #
199 # If you intend on adding an example file, you should add a new function in
200 # ``downloads.py`` to make it easy for users to add example files.
201
202 dataset = examples.download_bunny()
203 dataset
204
205
206 # Making a Pull Request
207 # ~~~~~~~~~~~~~~~~~~~~~
208 # Once your example is complete and you've verified it builds locally, you can
209 # make a pull request (PR).
210 #
211 # Branches containing examples should be prefixed with `docs/` as per the branch
212 # naming conventions found in out `Contributing Guidelines
213 # <https://github.com/pyvista/pyvista/blob/main/CONTRIBUTING.rst>`_.
214 #
215 # .. note::
216 # You only need to create the Python source example (``*.py``). The jupyter
217 # notebook and the example HTML will be auto-generated via `sphinx-gallery
218 # <https://sphinx-gallery.github.io/>`_.