新しいギャラリーを追加する例

このサンプルは，新しいPyVistaの Sphinx Gallery のサンプルを追加する方法を示していると同時に，それらの作成に使用することができるテンプレートでもあります．

Each example should have a reference anchor in the form:

.. _<example_name>_example:

The .. _ is necessary. Everything that follows is your reference anchor, which can potentially be used within a docstring. As convention, we keep all references all in snake_case.

このセクションでは，その事例が何について，および/または，何を示しているのかについて，簡単な概要を説明します． タイトルは，あなたの例がカバーするトピックを反映するように変更する必要があります．

新しい例は，pythonスクリプトとして以下に追加する必要があります:

examples/<index>-<directory-name>/<some_example>.py

注釈

絶対に必要でない限り，新しいディレクトリを作らないようにしましょう．もし，新しいフォルダを作らなければならない場合は， README.txt を必ず追加して，参照先，タイトル，フォルダの説明を一文で記述してください．そうしないと，新しいフォルダはSphinxによって無視されます．

Example file names should be underscore-separated snake case:

some_example.py

このプリアンブルが完了すると，最初のコードブロックが始まります．ここは一般的にインポートを設定する場所です．

注釈

By default, the documentation scrapper will generate both a static image and an interactive widget for each plot. If you want to turn this feature off, define at the top of your file:

# \sphinx_gallery_start_ignore (remove the \)
PYVISTA_GALLERY_FORCE_STATIC_IN_DOCUMENT = True
# \sphinx_gallery_end_ignore (remove the \)

Note that the sphinx_gallery_start_ignore and sphinx_gallery_end_ignore flags have been escaped to appear in the current documentation. See Sphinx-Gallery documentation for more details.

If you want to use static images only for some of your plots, define PYVISTA_GALLERY_FORCE_STATIC before the plot/show command that produces the image you want to turn into static:

...
pl.show()  # this will be interactive plot

# \sphinx_gallery_start_ignore (remove the \)
PYVISTA_GALLERY_FORCE_STATIC = True
# \sphinx_gallery_end_ignore (remove the \)
...
pl.show()  # this will be static plot

セクションタイトル

コードブロックは，テキスト "sections" で分割することができ，これは再構築されたテキストとして解釈されます．

これは，生成されたjupyterノートブックやHTMLページでもマークダウンのセルに変換されます．

セクションには，ステップバイステップのコメントやモチベーションに関するメモなど，例題に関するあらゆる情報を含めることができます．

Jupyterノートブックと同様に，コードブロックの最後にステートメントが未アサインである場合，その __repr__ メソッドに従って出力が生成され，画面に表示されます． それ以外の場合は， print() を使用してテキストを出力することができます．

from __future__ import annotations

import pyvista as pv
from pyvista import examples

# Create a dataset and exercise it's repr method
dataset = pv.Sphere()
dataset

Header	Data Arrays
PolyData Information N Cells 1680 N Points 842 N Strips 0 X Bounds -4.993e-01, 4.993e-01 Y Bounds -4.965e-01, 4.965e-01 Z Bounds -5.000e-01, 5.000e-01 N Arrays 1	Name Field Type N Comp Min Max Normals Points float32 3 -1.000e+00 1.000e+00

プロットと画像

画像を出力するもの(例えば pyvista.Plotter.show() ) を使用すると，結果の画像は出力のHTML内にレンダリングされることになります．

注釈

サンプルスクリプトの先頭に sphinx_gallery_thumbnail_number = <int> が含まれていない限り，ギャラリーのサムネイル画像には最初の図（この図）が使用されます．

また，この画像番号は1ベースインデックスを使用していることに注意してください．

dataset.plot(text='Example Figure')

スタティックシーン

インタラクティブなシーン

注意事項 - プロッターは1セル内にあること．

複数のセルにまたがる単一の pyvista.Plotter オブジェクトを使用することはできません．なぜなら，これらのオブジェクトはセルの終了時に自動的にクローズアウトされるからです．

ここでは，同じセルにプロッタを表示せずにインスタンス化する理由を示すために， pyvista.Actor repr を演習しています．

pl = pv.Plotter()
actor = pl.add_mesh(dataset)
actor

Actor (0x78724303ad40)
  Center:                     (0.0, 0.0, 0.0)
  Pickable:                   True
  Position:                   (0.0, 0.0, 0.0)
  Scale:                      (1.0, 1.0, 1.0)
  Visible:                    True
  X Bounds                    -4.993E-01, 4.993E-01
  Y Bounds                    -4.965E-01, 4.965E-01
  Z Bounds                    -5.000E-01, 5.000E-01
  User matrix:                Identity
  Has mapper:                 True

Property (0x78724303b0a0)
  Ambient:                     0.0
  Ambient color:               Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Anisotropy:                  0.0
  Color:                       Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Culling:                     "none"
  Diffuse:                     1.0
  Diffuse color:               Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Edge color:                  Color(name='black', hex='#000000ff', opacity=255)
  Edge opacity:                1.0
  Interpolation:               InterpolationType.FLAT
  Lighting:                    True
  Line width:                  1.0
  Metallic:                    0.0
  Opacity:                     1.0
  Point size:                  5.0
  Render lines as tubes:       False
  Render points as spheres:    False
  Roughness:                   0.5
  Show edges:                  False
  Specular:                    0.0
  Specular color:              Color(name='lightblue', hex='#add8e6ff', opacity=255)
  Specular power:              100.0
  Style:                       "Surface"

DataSetMapper (0x78724303b0a0)
  Scalar visibility:           False
  Scalar range:                (0.0, 1.0)
  Interpolate before mapping:  True
  Scalar map mode:             default
  Color mode:                  direct

Attached dataset:
PolyData (0x78724303ac20)
  N Cells:    1680
  N Points:   842
  N Strips:   0
  X Bounds:   -4.993e-01, 4.993e-01
  Y Bounds:   -4.965e-01, 4.965e-01
  Z Bounds:   -5.000e-01, 5.000e-01
  N Arrays:   1

このセルではプロッタを動作させることができない

プロッターは sphinx_gallery によってすでに閉じられています．

# This cannot be run here because the plotter is already closed and would raise
# an error:
# >>> pl.show()

# You can, however, close out the plotter or access other attributes.
pl.close()

アニメーション

アニメーションを作成することもできます．完全な例は MP 4ムービーを作成する にありますが，このセルは一つのセルの中でアニメーションを作成する方法を説明しています．

ここでは，単純な球体を爆発させます．

pl = pv.Plotter(off_screen=True)

# optimize for size
pl.open_gif('example_movie.gif', palettesize=16)

sphere = pv.Sphere(theta_resolution=10, phi_resolution=10)

# Add initial mesh to setup the camera
actor = pl.add_mesh(sphere)
pl.background_color = 'w'

# clear and overwrite the mesh on each frame
n_frames = 20
for i in range(n_frames):
    exploded = sphere.explode(factor=i / (n_frames * 2)).extract_surface(algorithm=None)
    actor.mapper.dataset.copy_from(exploded)
    pl.camera.reset_clipping_range()
    pl.write_frame()  # Write this frame

# Be sure to close the plotter when finished
pl.close()

サンプルファイルの追加

PyVistaには様々なサンプルファイルがあり，すべて pyvista/vtk_data に格納されているので，そこの指示に従ってファイルを追加することができます．

PyVistaの内部では， pooch を使用しており， pyvista.examples.downloads.download_file() で追加したファイルに簡単にアクセスすることができます．

filename = examples.download_file('bunny.ply')
filename

'/home/runner/.cache/pyvista_3/bunny.ply'

ラッピング例の追加

While it's possible to simply download a file and then read it in, it's better for you to write a wrapped download_<example_dataset>() within /pyvista/examples/downloads.py. For example download_bunny() downloads and reads with pyvista.read().

もし，サンプルファイルを追加するつもりなら， downloads.py に新しい関数を追加して，ユーザーが簡単にサンプルファイルを追加できるようにする必要があります．

dataset = examples.download_bunny()
dataset


# Making a Pull Request
# ~~~~~~~~~~~~~~~~~~~~~
# Once your example is complete and you've verified it builds locally, you can
# make a pull request (PR).
#
# Branches containing examples should be prefixed with `docs/` as per the branch
# naming conventions found in out `Contributing Guidelines
# <https://github.com/pyvista/pyvista/blob/main/CONTRIBUTING.rst>`_.
#
# .. note::
#    You only need to create the Python source example (``*.py``).  The jupyter
#    notebook and the example HTML will be auto-generated via `sphinx-gallery
#    <https://sphinx-gallery.github.io/>`_.

PolyData	Information
N Cells	69451
N Points	35947
N Strips	0
X Bounds	-9.469e-02, 6.101e-02
Y Bounds	3.299e-02, 1.873e-01
Z Bounds	-6.187e-02, 5.880e-02
N Arrays	0