Mayaviによる高度なスクリプト機能

Mayaviの概要 セクションで説明されているように,データを視覚化するためにPythonからMayaviをスクリプト化することができます.Mayaviは,最初から高度な評価できるように設計されています.ユーザインタフェースから実行できる操作はすべて,Pythonスクリプトを使用して実行できます.Mayavi2アプリケーションのスクリプト作成は,既存のフレームワークにドメイン固有の機能を追加する優れた方法です.さらに,このアプリケーションを理解すると,強力な視覚化ライブラリとしてMayaviを使用して独自のアプリケーションを設計するのに役立ちます.

Mayavi2アプリケーション自体のスクリプトを作成したり,アプリケーションを構築したりするのではなく,単純なコードで視覚化を行う簡単な方法を探している場合は,Mayaviの mlab モジュールを確認してください.これは mlab: 3Dプロット用のPythonスクリプト の章でより詳細に説明されています.このMayaviには,自動スクリプト記録機能も備わっています.この機能は,GUIを使用したときに自動的にPythonスクリプトを作成します.詳細については, スクリプトへのMayaviアクションの記録 の章を参照してください.これはおそらく,Mayaviをスクリプト化する最も簡単で強力な方法です.

しかし,Mayaviのスクリプトの書き方を最もよく理解するには,Mayaviの内部構造を合理的に理解する必要があります.以下のセクションでは,Mayaviパイプラインの基本設計とオブジェクトの概要について説明します.以降のセクションでは,この概念を説明するMayaviソースに含まれる特定のサンプルスクリプトについて説明します.

Mayaviは内部的に TraitsTVTK を使用します. Traits は多くの点でプログラム方法を変えます.したがって,Mayaviの内部構造を理解するには,Traitsをよく理解することが重要です.Traitがよくわからない場合は,ここでTraitの概要を理解することをお勧めします.私を信じてください,あなたの伝統を学ぶ努力は無駄にならないでしょう!

設計の概要:視覚化フレームワークとしてのMayavi

このセクションでは,Mayaviの内部アーキテクチャについて簡単に説明します.

視覚化の "全体像" はMayaviの Engine (mayavi.engine.Engine) オブジェクトが視覚化全体を管理することです. EngineScene (mayavi.core.scene.Scene) オブジェクトのコレクションを管理します.各シーンにおいて,ユーザは任意の数の Source (mayavi.core.source.Source) オブジェクトを作成することができます.Sourceオブジェクトには,さらに任意の数の Filter (mayavi.core.filter.Filter) または ModuleManager (mayavi.core.module_manager.ModuleManager) オブジェクトを含めることができます. Filter には,他の filters または ModuleManagers を含めることができます. ModuleManager は,任意の数の Modules を管理します.次の図は,この階層をグラフ形式で示しています.

Illustration of the various objects in the Mayavi pipeline.

Mayaviパイプラインのさまざまなオブジェクトの図.

この階層は,UIのMayaviツリービューに表示されるものとまったく同じであるため,UIはこの内部ワールドビューの単なるグラフィック表現にすぎません.これらのオブジェクトの詳細を次に示します.詳細については,ソースコード(ヒント:クラスのソースコードは Class?? )を参照してください.

視覚化のオブジェクト指向の構造

視覚化を作成または変更するためにMayaviをスクリプト化する場合,主にエンジンへのオブジェクトの追加や削除,またはプロパティの変更を行います.このようにして, mlab を使用したパイプラインの組み立て で参照したmlabを使用してパイプラインを構築する例を,エンジンへの明示的な呼び出しによって書き直すことができます.

import numpy as np
a = np.random.random((4, 4))
from mayavi.api import Engine
e = Engine()
e.start()
s = e.new_scene()
from mayavi.sources.api import ArraySource
src = ArraySource(scalar_data=a)
e.add_source(src)
from mayavi.filters.api import WarpScalar, PolyDataNormals
warp = WarpScalar()
e.add_filter(warp, obj=src)
normals = PolyDataNormals()
e.add_filter(normals, obj=warp)
from mayavi.modules.api import Surface
surf = Surface()
e.add_module(surf, obj=normals)

すべてのMayaviコードと同様に,視覚化を有効にするにはGUIメインループを実行する必要があります.これを行うには,ターミナルかコマンドプロンプトに ipython --gui=qt と入力します.

この明示的なオブジェクト指向のコードは,このように mlab.pipeline のコード.よりきめ細かく,より細かく制御できます.たとえば,オブジェクトの初期化と,エンジンへのオブジェクトの追加または削除を分離します.一般に,スクリプトではなくアプリケーションの開発に適しています.

異なるオブジェクトのライフサイクル

Mayaviパイプラインのすべてのオブジェクトには, start メソッドと stop メソッドがあります.この理由は,Mayaviのオブジェクトは起動されない限り使用できない(出力がない場合があります.)からです.同様に, stop メソッドはオブジェクトを "deactivates" します.これは,Mayaviが基本的に下にあるVTKオブジェクトを操作するためです.これらのオブジェクトは,有用な操作を行うために入力を必要とします.したがって,パイプラインに接続されていないオブジェクトは使用できません.たとえば, IsoSurface モジュールを考えてみましょう.等高線を作成するには,データが必要です.したがって,分離されたモジュールは全く役に立たない.これはMayaviパイプラインに追加された場合にのみ使用できます.オブジェクトがパイプラインに追加されると,入力が設定され,その start``メソッドが自動的に呼び出されます.オブジェクトがパイプラインから削除されると,その ``stop メソッドが自動的に呼び出されます.mayaviパイプラインからオブジェクトを削除する場合は, remove メソッドを使用して削除できます.例(以下では ipython --gui=qt を使う必要があります.)

>>> from mayavi.api import Engine
>>> e = Engine()
>>> e.start()
>>> s = e.new_scene()
>>> from mayavi.sources.api import ParametricSurface
>>> p = ParametricSurface()
>>> e.add_source(p) # calls p.start internally.
>>> p.remove() # Removes p from the engine.

Engine オブジェクトを除き,Mayaviパイプラインの他のすべてのオブジェクトには,オブジェクトが関連付けられている現在の tvtk.pyface.tvtk_scene.TVTKScene インスタンスを参照する scene traitがあります.オブジェクトには, "children" オブジェクトを追加してパイプラインを構築する add_child メソッドもあります. add_child のメソッドは "intelligent" で,コンテキストに基づいて適切な場所に子を追加しようとします.

mayavi2 アプリケーションのスクリプト作成

mayavi2 アプリケーションは mayavi.scripts.mayavi2 モジュールに実装されます( mayavi2 スクリプトではなく mayavi2.py ファイルを参照してください).このコードは,コマンドライン引数の解析を処理し,アプリケーションを実行します.

mayavi2 はEnvisage_applicationです.Envisageアプリケーションを main メソッドで起動します.このコードは mayavi.plugins.app モジュールにあります.Mayaviはその機能を構築するためにいくつかの予想されるプラグインを使用する.これらのプラグインは, mayavi.plugins.app モジュールで定義されます.このモジュールには,デフォルトのプラグインのリストを返す2つの関数 get_pluginsget_non_gui_plugins``があります.デフォルトのアプリケーションは前者を使用して,ユーザーが使用できるGUIを生成します.後者 ( ``get_non_gui_plugins ) を使用すると,アプリケーションの実行時にmayaviツリービュー,オブジェクトエディタ,およびメニュー項目を使用できません.これにより,開発者はmayaviを使用するがユーザインタフェースを表示しないアプリケーションを作成できます.これを行う方法の例を examples/mayavi/nongui.py に示します.

UIからのスクリプト作成

mayavi2 アプリケーションを使用する場合,UI上の埋め込みPythonインタプリタからスクリプトを実行できます.インタプリタ上では, mayavi という名前が自動的に mayavi.plugins.script.Script インスタンスにバインドされます.このインスタンスを使用すると,mayaviを簡単にスクリプト化できます.このインスタンスは単純なラッパーオブジェクトで,UIからスクリプトを作成するときに便利な機能を提供するだけです.このインスタンスには,実行中のmayaviエンジンを参照する engine traitがあります.mayaviのスクリプトに Engine インスタンス自体を使用するのと同じくらい便利であることに注意してください.

組み込みPythonインタプリタ セクションで説明されているように,ツリーからmayaviパイプラインオブジェクトをドラッグし,インタプリタにドロップして直接スクリプトを作成することができます.

File->Open Text File... メニューを選択して既存のPythonファイルをテキストエディタで開くか, File->New Text File メニューを選択して新しいファイルを作成します.テキストエディタはPythonに対応しており, mayavi の名前がシェル上の Script インスタンスにバインドされていると仮定してスクリプトを書くことができます.このスクリプトを実行するには,前述のように Control-r キーを押します. Control-s はスクリプトを保存します. Control-b はフォントサイズを大きくし, Control-n はフォントサイズを小さくします.

この種のスクリプトの良いところは,インタプリタやエディタで何かを書いた場合,その内容をファイルに保存できることです.次にこのスクリプトを次のように実行します.

$ mayavi2 -x script.py

これにより,のスクリプトが自動的に実行されます. mayavi という名前はスクリプトで使用でき, Script インスタンスにバインドされます.これはとても便利です.mayaviに複数のスクリプトを実行させることができます.次に例を示します.

$ mayavi2 -d foo.vtk -m IsoSurface -x setup_iso.py -x script2.py

foo.vtk ファイルをロードし, IsoSurface モジュールを作成し, setup_iso.py を実行してから script2.py を実行します.

mayaviの examples ディレクトリには,これを行う方法を示すスクリプトがいくつかあります. examples/README.txt には,スクリプトの推奨法に関する情報が含まれています.

IPythonからのスクリプト

IPython を使用してMayaviをスクリプト化することができます.mayaviアプリケーションをインタラクティブにスクリプト化できるようにするには,IPythonを --gui=qt コマンドラインオプションで起動する必要があります.

$ ipython --gui=qt

視覚化を開始するには,次の操作を行います.

from mayavi.plugins.app import main
# Note, this does not process any command line arguments.
mayavi = main()
# 'mayavi' is the mayavi Script instance.

この目的のために mlab ( mlab: 3Dプロット用のPythonスクリプト を参照してください)を使うこともできます.

from mayavi import mlab
f = mlab.figure() # Returns the current scene.
engine = mlab.get_engine() # Returns the running mayavi engine.

これにより,組み込みインタプリタまたはテキストエディタで実行されるのと同じ方法でMayaviをスクリプト化できるはずです.

以下は,Mayaviスクリプトのさまざまな機能を示すサンプルスクリプトです(これは,Mayavi内部に埋め込まれたPythonシェルから以下を実行する場合,または mayavi2 -x script.py として実行する場合に機能します).

# Create a new mayavi scene.
mayavi.new_scene()

# Get the current active scene.
s = mayavi.engine.current_scene

# Read a data file.
d = mayavi.open('fire_ug.vtu')

# Import a few modules.
from mayavi.modules.api import Outline, IsoSurface, Streamline

# Show an outline.
o = Outline()
mayavi.add_module(o)
o.actor.property.color = 1, 0, 0 # red color.

# Make a few contours.
iso = IsoSurface()
mayavi.add_module(iso)
iso.contour.contours = [450, 570]
# Make them translucent.
iso.actor.property.opacity = 0.4
# Show the scalar bar (legend).
iso.module_manager.scalar_lut_manager.show_scalar_bar = True

# A streamline.
st = Streamline()
mayavi.add_module(st)
# Position the seed center.
st.seed.widget.center = 3.5, 0.625, 1.25
st.streamline_type = 'tube'

# Save the resulting image to a PNG file.
s.scene.save('test.png')

# Make an animation:
for i in range(36):
    # Rotate the camera by 10 degrees.
    s.scene.camera.azimuth(10)

    # Resets the camera clipping plane so everything fits and then
    # renders.
    s.scene.reset_zoom()

    # Save the scene.
    s.scene.save_png('anim%d.png'%i)

Mayaviの Script インスタンスや Engine インスタンスでは,特定のモジュールやオブジェクトに移動できると便利な場合があります.上記の例では,次のようになります.

x = mayavi.engine.scenes[0].children[0].children[0].children[-1]
print x

この場合, x は作成した Streamline インスタンスに設定されます.

examples/mayavi ディレクトリには,さまざまなことを説明した例がたくさんあります.これらはすべてかなりよく文書化されています.

特に standalone.py の例は,想定されるアプリケーションをまったく使用せずにmayaviをスクリプト化する方法を示しています. offscreen.py は,(特定のビルドのVTKでサポートされている場合)オフスクリーンレンダリングを使用してこれを行う方法を示しています.

examples/README.txt には,スクリプトの推奨方法と追加情報が含まれています.

Mayavi envisageプラグインの使用

使用するMayavi関連のプラグイン定義は次のとおりです.

  • mayavi_plugin.py
  • mayavi_ui_plugin.py

これらは mayavi.plugins にあります.このコマンドの使用例については, mayavi.plugins.app を参照してください. examples/mayavi/explorer にあるexplorer3Dの例でも,Mayaviを予想プラグインとして使う方法を説明しています.

アプリケーション用のEnvisageプラグインを作成していて,プラグイン/アプリケーションからMayaviプラグインを使用したい場合は,Mayaviが便利な3つのワークベンチサービスを作成することに注意してください.次のものがあります.

  • mayavi.plugins.script.Script: これはmayaviを簡単にスクリプト化するために使用できるスクリプト mayavi.plugins.script.Script です.これは単純なラッパー・オブジェクトで,UIからスクリプトを作成する際に便利な機能を提供するだけのもので,実行中のMayaviエンジンを参照する engine 特性を持っています.
  • mayavi.core.engine.Engine: これは実行中のMayaviエンジンインスタンスです.

examples/mayavi/explorer ディレクトリには,envisageアプリケーションでのMayaviプラグインの使用例が含まれています.これは,想定しているアプリケーションで同じことがどのように行われるかを理解するために検討することができます.