注釈
Go to the end to download the full example code
新しいギャラリーを追加する例#
このサンプルは,新しいPyVistaの Sphinx Gallery のサンプルを追加する方法を示していると同時に,それらの作成に使用することができるテンプレートでもあります.
各例は,フォームに参照タグ/キーを持つ必要があります:
.. _<example-name>_example:
.. _
は必要です.この後に続くものはすべて参照タグで,docstringの中で使用できる可能性があります.慣習として,すべての参照タグは snake_case
で統一しています.
このセクションでは,その事例が何について,および/または,何を示しているのかについて,簡単な概要を説明します. タイトルは,あなたの例がカバーするトピックを反映するように変更する必要があります.
新しい例は,pythonスクリプトとして以下に追加する必要があります:
examples/<index>-<directory-name>/<some-example>.py
注釈
絶対に必要でない限り,新しいディレクトリを作らないようにしましょう.もし,新しいフォルダを作らなければならない場合は, README.txt
を必ず追加して,参照先,タイトル,フォルダの説明を一文で記述してください.そうしないと,新しいフォルダはSphinxによって無視されます.
ファイル名の例では,ハイフンで区切られたスネークケースを使用すること:
some-example.py
このプリアンブルが完了すると,最初のコードブロックが始まります.ここは一般的にインポートを設定する場所です.
import pyvista as pv
from pyvista import examples
セクションタイトル#
コードブロックは,テキスト "sections" で分割することができ,これは再構築されたテキストとして解釈されます.
これは,生成されたjupyterノートブックやHTMLページでもマークダウンのセルに変換されます.
セクションには,ステップバイステップのコメントやモチベーションに関するメモなど,例題に関するあらゆる情報を含めることができます.
Jupyterノートブックと同様に,コードブロックの最後にステートメントが未アサインである場合,その __repr__
メソッドに従って出力が生成され,画面に表示されます. それ以外の場合は, print()
を使用してテキストを出力することができます.
# Create a dataset and exercise it's repr method
dataset = pv.Sphere()
dataset
プロットと画像#
画像を出力するもの(例えば 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 (0x7f21812cae00)
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: Set
Has mapper: True
Property (0x7f21812cb520)
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 (0x7f21812cb520)
Scalar visibility: False
Scalar range: (0.0, 1.0)
Interpolate before mapping: True
Scalar map mode: default
Color mode: direct
Attached dataset:
PolyData (0x7f2186c5b280)
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()
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()
で追加したファイルに簡単にアクセスすることができます.
'/home/runner/.cache/pyvista_3/bunny.ply'
ラッピング例の追加#
単純にファイルをダウンロードして読み込むことも可能ですが, /pyvista/examples/downloads.py
内で download_<example-dataset>()
をラップして記述した方が良いでしょう.例えば download_bunny()
はダウンロードを行い, 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/>`_.
Total running time of the script: (0 minutes 2.302 seconds)