mlab: 3Dプロット用のPythonスクリプト

セクションの概要

このセクションでは,スクリプトやインタラクティブセッションでMayaviを単純なプロットとして使用するための mlab APIについて説明します.これは,PythonでMatlabやIDLのような3Dプロットを行うことに関心のある人にとっての主要なエントリー・ポイントです.mlabで公開されているすべての関数のリストに興味があるなら, MLabリファレンス を見てください.

mayavi.mlab と呼ばれるmlabモジュールを使用すると, matplotlib pylab インタフェースで実行されるように,1行でスクリプトやインタラクティブプロンプトから簡単にデータを視覚化することができます.ただし,Mayavi2を使用した3D視覚化に重点が置かれています.これにより,Mayaviの強力な機能を使用しながらすばやく3D視覚化を実行できます.

Mayaviのmlabは,スクリプトに適した方法で使用するように設計されており,完全にオブジェクト指向のAPIを提供しているわけではありません.

警告

次の例のように,mlabでIPythonを使用する場合,IPythonは次のように --gui=qt コマンドラインオプションで起動する必要があります.

$ ipython --gui=qt

IPythonの最近のバージョンでは,次のようにしてIPython自体からオンにできます.

In []: %gui qt

次の例外が発生した場合:

ValueError: API 'QString' has already been set to version 1

これは,PyQtとPySideの間で互換性のない設定が行われた結果です.解決策は QT_API=pyqt ETS_TOOLKIT=qt4 ipython を実行することです.詳細は ipython documentation page を参照してください.

何らかの理由でMayaviがQtバックエンドで失敗した場合は,次のようにしてwxPythonバックエンドを使用してみることもできます.

$ ETS_TOOLKIT=wx
$ ipython --gui=wx

mlabの使用とスクリプトの実行の詳細については,以下の章 mlabスクリプトの実行 を読んでください.

このセクションでは,最初に numpy 配列の表現として3Dオブジェクトを作成する簡単なプロット関数を紹介します.次に, (1) 色やグリフサイズなどのプロパティを変更したり,データを表すために使用したりする方法について説明します.;(2) mlab で作成したビジュアル化をダイアログでインタラクティブに変更する方法, (3) スクリプトとアニメーションを実行する方法.最後に,完全な可視化パイプラインがスクリプトに組み込まれた mlab のより高度な使用法を公開し,これらのツールをボリュームスカラーとベクトルデータの可視化に適用する詳細な例を提供します.

デモ

まず,球面調和関数をサーフェスとして表示する例を示します.

# Create the data.
from numpy import pi, sin, cos, mgrid
dphi, dtheta = pi/250.0, pi/250.0
[phi,theta] = mgrid[0:pi+dphi*1.5:dphi,0:2*pi+dtheta*1.5:dtheta]
m0 = 4; m1 = 3; m2 = 2; m3 = 3; m4 = 6; m5 = 2; m6 = 6; m7 = 4;
r = sin(m0*phi)**m1 + cos(m2*phi)**m3 + sin(m4*theta)**m5 + cos(m6*theta)**m7
x = r*sin(phi)*cos(theta)
y = r*cos(phi)
z = r*sin(phi)*sin(theta)

# View it.
from mayavi import mlab
s = mlab.mesh(x, y, z)
mlab.show()

上記の例のコードの大部分は,データを作成するためのものです.それを可視化するには1行で十分です.これにより,次の表示が生成されます.

_images/mlab_surf_example.jpg

視覚化は,上記の mesh() という単一の関数によって作成されます.

mlab( test_contour3d, test_points3d, test_plot3d_anim などを参照してください.)には,この種の例がいくつか用意されています.上記のデモは mlab.test として入手できます.IPythonでは,mlabでタブを補完することで,これらを見つけることができます.また,便利な `mlab.test_contour3d?? を使ってIPythonのソースを調べることもできます.

numpy配列の3Dプロット関数

numpy配列上で動作する関数のセットによって, mlab 内に視覚化を作成することができます.

mlabプロット関数は,データの x, y, z 座標を記述するために,多数の配列を入力として受け取ります.データソースの作成,必要に応じたフィルタリング,ビジュアライゼーションモジュールの追加など,本格的なビジュアライゼーションを構築します.これらの関数の振る舞い,そしてその結果作成される視覚化は,pylabと同様に,キーワード引数によって微調整することができます.さらに,これらはすべて,作成されたビジュアル化モジュールを返すため,このモジュールの属性を変更することによってビジュアル化を変更することもできます.

注釈

このセクションでは,異なる関数のみをリストします.各関数の詳細については,ユーザガイドの最後にある MLabリファレンス を参照してください.リンクをたどってください.

0D/1Dデータ

   
points3d points3d()
与えられたデータの位置にグリフ(同点)をプロットします.グリフは x, y, z で記述された同じ形のnumpy配列です.
plot3d plot3d()
与えられたデータの間に線を引いて, x, y, z と同じ長さの1D numpy配列で記述します.

2Dデータ

   
imshow imshow()
2D配列をイメージとして表示します.
surf surf()
2D配列をカーペットプロットとして表示し,配列ポイントの値をz軸で表します.
contour_surf contour_surf()
2D配列を線の輪郭として表示し,配列の点の値に応じて高くします.
mesh mesh()
3つの2D配列, x, y, z で表されるサーフェスをプロットし,データポイントの座標をグリッドとして与えます.
surf(), とは異なり,サーフェスは x, y, z 座標で定義され,特別な方向性はありません.より複雑なサーフェスを作成できます.
barchart barchart()
配列``s`,または明示的な座標配列``x',``y''と``z''を持つ点の集合を棒グラフとしてプロットします.|hack|この関数は非常に汎用性が高く,2Dまたは3D配列だけでなく,点群を使用してバーを配置することもできます.
triangular_mesh triangular_mesh()
三角形メッシュをプロットします.このメッシュは,頂点の x, y, z 座標,および三角形のインデックスの (n, 3) 配列で完全に指定されます.

surf()contour_surf() の鉛直スケール

surf() および contour_surf() は,2Dデータの3D表現として使用できます.既定では,Z軸はX軸およびY軸と同じ単位であることが想定されていますが,2/3のアスペクト比になるように自動スケールすることもできます.この動作は, "warp_scale='auto'" を指定することで制御できます.

データポイントからサーフェスへ.

データ点の位置を知るだけではサーフェスを定義することはできません.接続情報も必要です. surf() および mesh() 関数を使用すると,この接続情報は入力配列の形状から暗黙的に抽出されます.つまり,2D入力配列内の隣接するデータポイントが接続され,データはグリッド上にあります. triangular_mesh() 関数を使用すると,接続性が明示的に指定されます.接続性が定期的でないことはよくありますが,事前にもわかりません.データ点はサーフェス上にあり,暗黙的に定義されたサーフェスをプロットします.( 不規則なデータのサーフェスの例 )に示されているように,`delaunay2d`フィルタは,必要な最近接マッチングと補間を行います.

3Dデータ

   
contour3d contour3d()
3D配列として定義されたボリュームデータの等値面をプロットします.
quiver3d quiver3d()
データポイントのベクトルを表す矢印をプロットします. x, y, z の位置は,ベクトルの u, v, w 成分と同様に,多数の配列によって指定される.
flow flow()
3つの3D配列で記述されたベクトルフィールドに沿って粒子の軌跡をプロットし,グリッド上にe u, v, w 成分を与える.
slice volume_slice()
ボリュームデータをスライスしたインタラクティブなイメージプレーンをプロットします.

構造化データまたは非構造化データ

contour3d(), volume_slice()flow() は順序付けされたデータ(点と点の間を補間することができます)を必要としますが, quiver3d() は任意の点のセットで動作します.必要な構造体の詳細については,関数のドキュメントを参照してください.

注釈

データソースのフィルタとモジュールを組み合わせることで,より高度な視覚化を実現できます. mlab を使用したパイプラインの組み立て および 視覚化の事例 のセクションを参照してください.

作成したビジュアルオブジェクトの外観を変更する

色やサイズのバリエーションを追加する

Color:

プロット関数によって作成されたオブジェクトの色は,関数の 'color' キーワード引数を使用して明示的に指定できます.このカラーは,作成されるすべてのオブジェクトに均一に適用されます.

ビジュアル化全体でカラーを変更する場合は,データポイントごとにスカラー情報を指定する必要があります.関数の中には,この情報を推測しようとするものがあります.これらのスカラーは,ベクトルを持つ関数の場合はベクトルのノルムを,意味のある関数の場合はz仰角をデフォルトとします. surf()barchart() などです.

このスカラー情報は,ルックアップテーブルのカラーマップまたはLUTを使用してカラーに変換されます.可能なコロンマップのリストは次のとおりです.

accent       flag          hot      pubu     set2
autumn       gist_earth    hsv      pubugn   set3
black-white  gist_gray     jet      puor     spectral
blue-red     gist_heat     oranges  purd     spring
blues        gist_ncar     orrd     purples  summer
bone         gist_rainbow  paired   rdbu     winter
brbg         gist_stern    pastel1  rdgy     ylgnbu
bugn         gist_yarg     pastel2  rdpu     ylgn
bupu         gnbu          pink     rdylbu   ylorbr
cool         gray          piyg     rdylgn   ylorrd
copper       greens        prgn     reds
dark2        greys         prism    set1

視覚化に最も適したカラーマップを選択する最も簡単な方法は,GUIを使用することです(次項記載).カラーマップを設定するダイアログは, Colors and legends ノードにあります.

カスタム定義のカラーマップを使用するには,当分の間, カスタムカラーマップの例 に示すように,特定のコードを記述する必要があります.

字形のサイズ:

スカラー情報は,さまざまな方法で表示することもできます.例えば,データポイントに配置された字形のサイズを調整するために使用できます.

注意:クランプ:相対スケーリングまたは絶対スケーリング ポイント間隔1のライン上に6つのポイントが配置されている場合:

x = [1, 2, 3, 4, 5, 6]
y = [0, 0, 0, 0, 0, 0]
z = y

このデータセットで0.5から1までのスカラーを表す場合は,次のようになります.

s = [.5, .6, .7, .8, .9, 1]

points3d() を使ってデータセットを球体として表現し,スカラーを球体の直径にマッピングします.

from mayavi import mlab
pts = mlab.points3d(x, y, z, s)

デフォルトでは,球体の直径は 'clamped' ではありません.つまり,スカラーデータの最小値はNull直径として表され,最大値はポイント間の距離に比例します.スケーリングは相対的なものにすぎません.結果の図を参照してください.

_images/clamping_on.jpg

この動作により,すべてのデータセットに可視ポイントが与えられますが,スカラーが指定された位置と同じ単位でグリフのサイズを表す場合には望ましくないことがあります.

この場合,希望のスケール係数を指定して,自動スケールをオフにする必要があります.

pts = mlab.points3d(x, y, z, s, scale_factor=1)
_images/clamping_off.jpg

警告

以前のバージョンのMayavi(最大3.1 .0を含む)では,グリフは自動スケールされず,その結果,グリフが非常に小さいため,表示が空に見えることがあります.また,記号の最小直径は0に固定されるため,次のように指定しない限り,記号は絶対的に尺度変更されません.

pts.glyph.glyph.clamping = False
付加されたスカラーまたはベクトルのより多くの表現:
 

データにアタッチされたスカラーまたはベクトル情報を表す方法は他にもたくさんあります.例えば,スカラーデータを,例えば, WarpScalar フィルタを用いて,変位を 歪める ことができます.あるいはスカラーデータのノルムを, ExtractVectorNorm フィルタを用いた等表面を用いて可視化することができるスカラー成分を抽出することができます.

複数の数量を表示する:

iso-contoursまたはelevationを使用しながら,1つのスカラー量に関連するカラーを表示することができます.これは可能ですが,少し作業が必要です 原子軌道の例 を見てください.

単に1つの量で指定されたサイズの点を表示し,1秒ごとに色を表示する場合は,ベクトルのノルムを使用してサイズ情報を追加し,スカラーを使用して色情報を追加し, quiver3d() を作成して,対称グリフを選択し,スカラーを使用して色を表現します.

x, y, z, s, c = np.random.random((5, 10))
pts = mlab.quiver3d(x, y, z, s, s, s, scalars=c, mode='sphere')
pts.glyph.color_mode = 'color_by_scalar'
# Finally, center the glyphs on the data point
pts.glyph.glyph_source.glyph_source.center = [0, 0, 0]

オブジェクトの尺度と位置を変更する

各mlab関数は, (x, y, z) の範囲を設定することができるキーワード引数を取ります.これにより,異なる方向のスケーリングと中心のディスプレイスメントの両方を制御できます.この機能を使用する場合は,同じデータを表示する他のモジュールに同じエクステントを渡すと便利です.そうしないと,ディスプレイスメントとスケールは共有されません.

高さの値を変換して2D配列を表示する surf(), contour_surf(), および barchart() 関数も,垂直スケーリングを制御するために warp_scale パラメータを取ります.

オブジェクトのプロパティをインタラクティブに変更する

Mayavi,つまりmlabを使用すると,表示をインタラクティブに変更できます.

Mayaviパイプラインツリーを表示するには,フィギュアのツールバーにあるmayaviアイコンをクリックするか, show_pipeline() mlabコマンドを使用します.このマニュアルの他の部分で説明しているように,このダイアログを使用して各オブジェクトをダブルクリックしてそのプロパティを編集することで表示を変更したり,パイプライン上のこのアイコンを使用するか,またはパイプライン内のオブジェクトを右クリックして表示されるメニューを使用して,新しいモジュールまたはフィルタを追加できます.

_images/pipeline_and_scene.jpg

レコード機能

このダイアログの 非常に便利な機能 は,パイプラインビューのツールバーにある赤い丸ボタンを押すと表示されます.これにより,ダイアログを介してビジュアル化に対してインタラクティブに行われた変更を追跡するレコーダが開き,Pythonコードの有効な行が生成されます.パイプラインのプログラムをナビゲートする方法については, Mayaviの視覚化の構成:パイプライン を参照してください.

さらに,mlab関数が返すすべてのオブジェクトに対して, this_object.edit_traits() と入力すると,オブジェクトのプロパティをインタラクティブに編集するためのダイアログが表示されます.このコマンドを入力してもダイアログが表示されない場合は, mlabスクリプトの実行 を参照してください.

Envisage UIで mlab を使う

mlabスクリプトを作成しても,メニューをクリックして他のモジュールを使用できるように完全な予測アプリケーションを使用すると便利な場合があります.これを行うには,mlabの図を作成する前に次の操作を実行します.

from mayavi import mlab
mlab.options.backend = 'envisage'
f = mlab.figure()
# ...

これにより,デフォルトの単純なウィンドウではなく,完全なUIが得られます.

図,凡例,カメラ,デコレーション

複数の図を処理する

すべてのmlab関数は,matlabとpylabとの互換性を保つために, figure`とも呼ぶ現在のシーンで動作します.異なる図は,整数または文字列のキーによってインデックスが付けられます. :func:`figure() 関数を呼び出してキーを指定すると,対応する図が存在する場合はそれを返すか,新しい図を作成します.現在の図は, gcf() 関数で検索できます.これは:func:draw`関数を使ってリフレッシュでき, :func:`savefig を使って画像ファイルに保存し, clf() を使って消去できます.

図のデコレーション

軸は axes() 関数を使って可視化オブジェクトの周りに追加でき,ラベルは xlabel(), ylabel() zlabel() 関数を使って設定できます.同様に, outline() はオブジェクトの周りにアウトラインを作成します. title() は図形にタイトルを追加します.

カラーバーは,値の表示に使用されるカラーマップを反映するために使用できます(VTK用語でのLUTまたはルックアップテーブル). colorbar() は,最後に作成されたオブジェクトのカラーバーを作成し,ベクトルデータとスカラデータのカラーマップのどちらを使用するかを推測します. scalarbar() および vectorbar() 関数スキャンを使用して,スカラーまたはベクトルデータ専用のカラーバーを作成します.

小さな xyz 座標系を図形に追加するには, orientation_axes() を使用します.

警告

orientation_axes() はリリース3.2以前は orientationaxes という名前でした.

カメラを移動する

カメラの位置と方向は, view() 関数を使用して設定できます.オイラー角と焦点までの距離で記述した. view() 関数は,ビューを見やすくするためにカメラの右ロール角を推測しようとしますが,失敗することがあります. roll() は,カメラのロール角度を明示的に設定します(これは,コントロールキーを押しながらマウスをドラッグすることで,シーン内でインタラクティブに行うことができます. シーンとの相互作用 を参照してください.).

view()roll() 関数は,引数として取る角度と距離の現在値を返します.その結果,対話的に取得した視点は,以下を使用して保存およびリセットできます.

# Store the information
view = mlab.view()
roll = mlab.roll()

# Reposition the camera
mlab.view(*view)
mlab.roll(roll)

カメラの回転

また,カメラオブジェクトの rollyawpitch メソッドを使用して,カメラを自分自身の周りで回転させることもできます.これにより,焦点が移動します.

f = mlab.gcf()
camera = f.scene.camera
camera.yaw(45)

view() および roll() 関数とは異なり,角度は増分であり,絶対角度ではありません.

ズームとビュー角度を修正する

カメラは,その位置,焦点,ビュー角度( 'position' , 'focal_point' , 'view_angle' 属性)によって完全に定義されます.カメラを使用する方法 'zoom' では,指定した比率の分だけビュー角度が変化します.この方法 'dolly' では,焦点を一定に保ちながら,カメラが軸に沿って移動します. move() 関数もこれらの点で有用です.

注釈

カメラの平行スケール

mlab.view と mlab.roll によって返され設定される情報に加えて,ビューポイントを完全に定義するには,最後のパラメータはビュー角度を制御するカメラの平行スケールです.次のコードで読み取る(または設定する)ことができます.

f = mlab.gcf()
camera = f.scene.camera
cam.parallel_scale = 9

mlabスクリプトの実行

Mlabは他のMayavi同様,インタラクティブなアプリケーションです.インタラクティブ環境(次の段落を参照)に入っていない場合は, show() 関数を使用して,図形やその他の図形要素を操作する必要があります.例えば,スクリプトを作成している場合,1つまたは複数の図形を表示し,ユーザがそれらを操作できるようにするには,その都度 show() を呼び出す必要があります.

mlabを対話的に使用する

IPython を使用すると, mlab 命令をインタラクティブに実行できます.また, IPython's %run コマンドを使用してスクリプト内で実行することもできます.

In [1]: %run my_script

--gui=qt オプションを指定して IPython を起動する必要があります.この環境では,プロットコマンドはインタラクティブです.これらのコマンドは図形に即座に影響を与え, show() 関数を使用する必要性を軽減します.

mlabは,mayavi2アプリケーションのPythonシェル,またはwxPythonベースのアプリケーション(他のEnvisageベースのアプリケーションやSPEなど,Stani氏のPython Editor)の任意のインタラクティブPythonシェルで,インタラクティブに使用することもできます.

Matplotlibとの併用

IPythonでMatplotlibの対話型プロットをMayaviのmlabで使用する場合は,次の操作を実行します.

  • 次のコマンドでIPythonを起動します.

    $ ipython --matplotlib=qt
    
  • もしくは, --gui=qt オプションを指定してIPythonを起動します.

    $ ipython --gui=qt
    

    およびmatplotlibモジュールをインポートする に,次のPythonコマンドを入力します.

    >>> import matplotlib
    >>> matplotlib.use('Qt4Agg')
    >>> matplotlib.interactive(True)
    
  • 以下のようにIPythonに対して --pylab オプションを使うこともできます.

    $ ipython --pylab=qt
    

デフォルトでIPythonでmatplotlibとmlabを一緒に動作させるには,デフォルトのmatplotlibバックエンドを変更します. ~/matplotlib/matplotlibrc に次の行を追加します.

backend     : Qt4Agg

何らかの理由でQtバックエンドが動作しない場合は,wxバックエンドを使用します.これを行うには,次の操作を行います.

$ ETS_TOOLKIT=wx
$ ipython --gui=wx

Mayaviに関する限り, ETS_TOOLKIT 環境変数を使用して適切なツールキットを選択します.これが設定されていない場合,サポートされているツールキットは,成功するまでバージョン依存の順序で試行されます. traitsui の最近のリリースでは,デフォルトはQtです. ETS_TOOLKIT のオプションは以下のとおりです.

  • qt4: Qtバックエンドを使う場合(PySideまたはPyQt4),
  • wx: wxPythonを使うには
  • null:UI ツールキットを使用しない.

pylabに組み込むためのmlabプロットのキャプチャ

Mayaviバージョン3.4 .0以降,mlab:func:`screenshot`を使用して現在のフィギュアのスクリーンショットを撮り,matplotlibプロットに統合できます.

スクリプト内

mlabコマンドをファイルに書き込み,スクリプトを作成することができます.このスクリプトをMayaviアプリケーションにロードするには, File->Open file メニューエントリを使用し, File->Refresh code メニューエントリを使用するか,または Control-r キーを押します.また, -x コマンドラインスイッチを使用して,Mayaviアプリケーションの起動中に実行することもできます.

前述したように,インタラクティブ環境の外で実行する場合は,たとえば python myscript.py を使用します.スクリプトを一時停止し,ユーザが図を操作できるようにするには, show() 関数(上のデモに示されているように)を呼び出す必要があります.

次のように show() を使用して関数を修飾し,event-loopで実行させることもできます.これにより,柔軟性が増します.

from mayavi import mlab
from numpy import random

@mlab.show
def image():
   mlab.imshow(random.random((10, 10)))

このデコレータにより, image 関数が呼び出されるたびに, mlab は, image 関数を実行する前に対話環境が実行されていることを確認します.対話型環境が実行されていない場合は, mlab が起動し,イメージ関数は閉じられるまで戻りません.

データのアニメート

多くの場合,データをプロットするだけでは不十分です.また,アニメーションを実行したり,インタラクティブアプリケーションで表示全体を再作成しなくても,プロットのデータを変更してプロットを更新できます.実際,ビジュアライゼーション全体を再現するのは非常に非効率的で,非常にぎくしゃくしたアニメーションになります.これを行うために,mlabは既存のmlab可視化のデータを変更する非常に便利な方法を提供します.非常に簡単な例を考えてみましょう.mlab.test_simple_surf_anim 関数のコードは次の通りです.

import numpy as np
from mayavi import mlab
x, y = np.mgrid[0:3:1,0:3:1]
s = mlab.surf(x, y, np.asarray(x*0.1, 'd'))

for i in range(10):
    s.mlab_source.scalars = np.asarray(x*0.1*(i+1), 'd')

最初の2つの線分は単純な平面を定義し,それを表示します.次の3行は,原点を中心に回転する平面を生成するスカラを変更することによって,そのデータをアニメートします.ここで重要なのは,上記の s オブジェクトが mlab_source という特別な属性を持っていることです.このサブオブジェクトを使用すると,ポイントとスカラーを操作できます. x の値を変更したい場合は,以下のように設定します.

s.mlab_source.x = new_x

ここで注意しなければならないのは, x の形を変えてはならないということだけです.

ここで説明する例の多くは,まったくアニメートされていないように見え,アニメーションの最終的な状態を確認できる場合があります.アニメーションの各段階でイメージのスクリーンショットを保存すると,正しい結果が得られます.ただし,画面上での視覚効果は得られません. @animate デコレータ (mayavi.mlab.animate()) を使ってこれを実現する方法については, ビジュアル化のアニメーション化 の節を見てください.ここでは,アニメーションを適切に作成するために上記を書き直した小さな例を示します.

import numpy as np
from mayavi import mlab
x, y = np.mgrid[0:3:1,0:3:1]
s = mlab.surf(x, y, np.asarray(x*0.1, 'd'))

@mlab.animate
def anim():
    for i in range(10):
        s.mlab_source.scalars = np.asarray(x*0.1*(i+1), 'd')
        yield

anim()
mlab.show()

上記では,ジェネレーターである関数に繰り返しをラップし,それを @mlab.animate デコレータで装飾していることに注意してください.

複数の値を変更する必要がある場合は, mlab_sourceset メソッドを使用して,以下のより複雑な例のように値を設定できます.

# Produce some nice data.
n_mer, n_long = 6, 11
pi = np.pi
dphi = pi/1000.0
phi = np.arange(0.0, 2*pi + 0.5*dphi, dphi, 'd')
mu = phi*n_mer
x = np.cos(mu)*(1+np.cos(n_long*mu/n_mer)*0.5)
y = np.sin(mu)*(1+np.cos(n_long*mu/n_mer)*0.5)
z = np.sin(n_long*mu/n_mer)*0.5

# View it.
l = mlab.plot3d(x, y, z, np.sin(mu), tube_radius=0.025, colormap='Spectral')

# Now animate the data.
ms = l.mlab_source
for i in range(10):
    x = np.cos(mu)*(1+np.cos(n_long*mu/n_mer +
                                      np.pi*(i+1)/5.)*0.5)
    scalars = np.sin(mu + np.pi*(i+1)/5)
    ms.trait_set(x=x, scalars=scalars)

上記の set メソッドの使用に注意してください.この方法では,表示は1回だけ再計算されます.この場合,新しい配列の形は変更されず,値だけが変更されます.配列の形状を変化させる場合は,次に示すように reset メソッドを使用する必要があります.

x, y = np.mgrid[0:3:1,0:3:1]
s = mlab.surf(x, y, np.asarray(x*0.1, 'd'),
              representation='wireframe')
# Animate the data.
fig = mlab.gcf()
ms = s.mlab_source
for i in range(5):
    x, y = np.mgrid[0:3:1.0/(i+2),0:3:1.0/(i+2)]
    sc = np.asarray(x*x*0.05*(i+1), 'd')
    ms.reset(x=x, y=y, scalars=sc)
    fig.scene.reset_zoom()

mlabには,データをアニメートするための標準的なサンプルが多数用意されています. mlab.test_<name>_anim という名前のサンプルを試してみてください.例えば,名前の最後に _anim を付けて,これらがどのように動作するかを確認します.

注釈

setreset の区別を覚えておくことが重要です.データの形を変更せずに値だけを変更する場合は, set を使用するか,属性を直接設定します( x, y, scalars など).配列の形や大きさが変化している場合は reset を使用してください.通常,resetはすべてのデータを再生成するので, set やtraitを直接設定する場合に比べて効率が悪い場合があります.

警告

Mayaviパイプラインを作成する場合,次のサブセクションで説明するように,既製のプロット関数を使用する代わりに, mlab_source アトリビュートは mlab を使用して作成されたソース上にのみ作成されます. mlab を使用して完全に作成されたパイプラインは,この属性を表示します.

注釈

複数のプロットオブジェクトをアニメートする場合, mlab_source アトリビュートを使用してデータを変更するたびに,Mayaviはシーンのリフレッシュをトリガします.この操作には時間がかかる場合があるため,アニメーションが遅くなります.この場合, Mayaviスクリプトの高速化 が役に立つでしょう.

mlab によるパイプラインの組み立て

上でレビューしたプロット関数は,Mayaviの視覚化の可能性のほんの一部です.Mayavi の力は,パイプライン自体の制御を通じてのみ発揮されます. Mayaviの概要 セクションで説明されているように,Mayaviのビジュアライゼーションは, data source オブジェクトを使用してMayaviのデータをロードし, Filters を使用してオプションでデータを変換し, モジュール を使用してビジュアライゼーションします.mlab関数は,1つの関数で複雑なパイプラインを構築し,ソース,フィルタ,モジュールを適切に選択しますが,可能なすべての組み合わせを調べることはできません.

Mlabは,スクリプトからパイプラインを容易に生成する関数を含むサブモジュール pipeline を提供します.このモジュールは mlab: mlab.pipeline でアクセスできます.または mayavi.tools.pipeline からインポートできます.ツール.

mlab プロット関数を使用すると,パイプラインが作成されます.最初に numpy 配列からソースが作成され,次にモジュール,場合によってはフィルタが追加されます.結果のパイプラインは,例えば mlab.show_pipeline で見ることができます.パイプラインの各ステップを作成するために必要な関数の名前は,パイプライン上の mlab によって作成されたオブジェクトのデフォルト名に直接リンクされているので,この情報を使用して, pipeline スクリプトモジュールを使用して,まったく同じパイプラインを直接作成することができます.例として, surf() を示します.

import numpy as np
a = np.random.random((4, 4))
from mayavi import mlab
mlab.surf(a)
mlab.show_pipeline()

次のパイプラインが作成されます.

Array2DSource
    \__ WarpScalar
            \__ PolyDataNormals
                    \__ Colors and legends
                            \__ Surface

次のコードを使用して,同じパイプラインを作成できます.

src = mlab.pipeline.array2d_source(a)
warp = mlab.pipeline.warp_scalar(src)
normals = mlab.pipeline.poly_data_normals(warp)
surf = mlab.pipeline.surface(normals)

データソース

mlab.pipeline モジュールには,配列からさまざまなデータソースを作成するための関数が含まれています.詳細については, mlabパイプライン制御リファレンス に完全に文書化されています.ここでは,その可能性について簡単に説明します.

Mayaviは, スカラーデータ を持つソースと ベクトルデータ を持つソースを区別しますが,より重要なのは, 接続されていないポイント のセットを作成してデータをアタッチする機能と, 接続されたデータポイント を作成してデータポイント間で補間できる連続的に変化する量を記述する機能です.

接続されていないソース:
暗黙的に接続されたソース:
明示的に接続されたソース:
  • triangle_mesh_source() ( PolyData を作成)

    _images/poly_data.jpg

すべての mlab.pipline のソースファクトリは,numpy配列を取り,パイプラインに追加されたMayaviソースオブジェクトを返す関数です.ただし,暗黙に接続されたソースは引数として整形式の配列を必要とします.つまり,データは入力配列の形状と同じ形状の規則的な直交グリッド上に存在することになります.つまり,配列は3次元のイメージを表します.

注釈

不規則格子または非直交格子のような,より複雑なデータ構造を作成することができる.関連項目 the section on data structures

モジュールとフィルタ

各Mayaviモジュールまたはフィルタ( モジュール および Filters )には,対応する mlab.pipeline 関数.この関数の名前は,モジュールまたはフィルタ名の大文字と小文字が交互に入れ替わることによって作成されます.したがって, ScalarCutPlanescalar_cut_plane に相当します.

一般的には mlab.pipeline モジュールとフィルタファクトリー関数は,対応するオブジェクトを作成して接続するだけです.ただし,キーワード引数として公開される追加ロジックを含めることもできます.たとえば,必要に応じて,簡単にカラーマップを設定したり,モジュールの色を指定したりできます.頻繁な操作を簡単にするための mlab インタフェースの目的に従って,キーワード引数を使用して,作成されたオブジェクトのプロパティを要件に合うように選択します.したがって,作成されたオブジェクトの属性を設定するよりも,キーワード引数を使用する方が簡単です.詳細については,docstringsを参照してください.完全で詳細な使用例については,次のサブセクションで説明します.

視覚化の事例

ボリュームスカラーデータの視覚化

3Dスカラーフィールドを可視化するには,主に3つの方法があります.次のフィールドを指定します.

import numpy as np
x, y, z = np.ogrid[-10:10:20j, -10:10:20j, -10:10:20j]
s = np.sin(x*y*z)/(x*y*z)
等値面:

フィールドの等値面を表示する最も簡単な方法は mlab contour3d() 関数を使用することです.

mlab.contour3d(s)

volumetric_contour3d

この方法の問題は,外側の等値面が内側の等値面を隠す傾向があることです.その結果,1つの等値面しか表示されないことがよくあります.

ボリュームレンダリング:

ボリュームレンダリングは,各ボクセルに部分的に透明なカラーを与える高度なテクニックです.これは mlab.pipeline で実現できます. scalar_field() ソースと volume モジュールを使用します.

mlab.pipeline.volume(mlab.pipeline.scalar_field(s))

volumetric_volume

このような視覚化では,良好な効果を得るために不透明度の転送関数を微調整することが重要です.通常,ボリュームの透過性を適切な割合にするには,下限値と上限値をデータの80パーセンタイルと20パーセンタイルに制限すると便利です.

mlab.pipeline.volume(mlab.pipeline.scalar_field(s), vmin=0, vmax=0.8)

volumetric_volume_tweaked

モジュールのダイアログボックス(例えば,パイプラインインターフェースを使ったり, edit_traits() メソッドを使ったりします.)を開き,カラー転送関数を調整してイメージの透明で低強度の領域をレンダリングすると便利です. このモジュール では,** Colors and Legends ** ノードで定義されているLUTは使用されません.**

ボリュームレンダリングの限界は,多くの場合非常にきれいですが,それを使用してフィールドの詳細を分析することが難しいことです.

切断面:

あまり印象的ではありませんが,断面はスカラーフィールドの詳細を視覚化するための非常に有益な方法です.

mlab.pipeline.image_plane_widget(mlab.pipeline.scalar_field(s),
                            plane_orientation='x_axes',
                            slice_index=10,
                        )
mlab.pipeline.image_plane_widget(mlab.pipeline.scalar_field(s),
                            plane_orientation='y_axes',
                            slice_index=10,
                        )
mlab.outline()

イメージプレーンウィジェットは, mlab volume_slice() 関数を使用してNumPy配列から作成することもできます.

mlab.volume_slice(s, plane_orientation='x_axes', slice_index=10)

volumetric_cut_plane

イメージプレーンウィジェットは, mlab.pipeline.scalar_field によって作成された正規の間隔のデータでのみ使用できます.したがって,可能な場合はスカラー切断面を優先する必要があります.

切断面をクリックしてドラッグすると,フィールドを効率的に表示できます.

技術の組み合わせ:

最後に,切断面を等値面と組み合わせて,等値面を使用してピーク領域のビューを表示したり,切断面を使用してフィールドの詳細を視覚化したり,等値面が大きいグローバル質量を表示したりすることもできます.

src = mlab.pipeline.scalar_field(s)
mlab.pipeline.iso_surface(src, contours=[s.min()+0.1*s.ptp(), ], opacity=0.1)
mlab.pipeline.iso_surface(src, contours=[s.max()-0.1*s.ptp(), ],)
mlab.pipeline.image_plane_widget(src,
                            plane_orientation='z_axes',
                            slice_index=10,
                        )

volumetric_combination

上記の例では,データソースとして単一のスカラーフィールドを使用するために, contour3d()volume_slice() の代わりにmayaviのパイプライン構文を使用しています.

この例では使用しませんが,場合によっては,切断面の前にしきい値フィルタを挿入して,たとえば,の値より小さい領域を削除することができます. 's.min()+0.1*s.ptp()' となります.この場合,切断面は mlab.pipeline.scalar_cut_plane で実装する必要があります.しきい値を設定した後でデータの構造体が失われた場合に使用されます.

ベクトルフィールドの視覚化

ベクトルフィールド,すなわちボリューム内で連続的に定義されたベクトルは,多くの情報を含んでいるため,視覚化が困難な場合があります.グリッド , u, v, w でサンプリングされた構成要素によって定義される,流体力学における多軸対流セル [1], の速度場について,異なる可視化を検討します.

import numpy as np
x, y, z = np.mgrid[0:1:20j, 0:1:20j, 0:1:20j]

u =    np.sin(np.pi*x) * np.cos(np.pi*z)
v = -2*np.sin(np.pi*y) * np.cos(2*np.pi*z)
w = np.cos(np.pi*x)*np.sin(np.pi*z) + np.cos(np.pi*y)*np.sin(2*np.pi*z)
Quiver:

ベクトルの集合を最も簡単に視覚化するには, mlab 関数 quiver3d を使用します.

mlab.quiver3d(u, v, w)
mlab.outline()
_images/vector_field_quiver.jpg

この視覚化の主な制限は,グリッド上のサンプリングポイントごとに矢印を配置することです.その結果,ビジュアライゼーションは非常にビジーになります.

マスクベクトル:

表示される矢印の数を減らすために,ベクトルの束だけでなく,ベクトルフィールドを視覚化しているということを利用できます.このためには, vector_field ソースを構築し,いくつかのマスキングパラメータ(ここでは,私たちは20のうちの一つの点だけをとっておく)を使用して vectors モジュールを適用する必要があります.

src = mlab.pipeline.vector_field(u, v, w)
mlab.pipeline.vectors(src, mask_points=20, scale_factor=3.)
_images/vector_field_vectors.jpg
切断面:

カットに沿ってベクトルを表示する場合は,カット平面を使用できます.特に,切断面を移動してベクトルフィールドをインタラクティブに検査できます.ベクトルフィールドをクリックしてドラッグすると,ベクトルフィールドを非常に明確に理解できます.

mlab.pipeline.vector_cut_plane(src, mask_points=2, scale_factor=3)
_images/vector_field_cut_plane.jpg
大きさの等値面:

ベクトルフィールドの重要なパラメータは,その大きさです.ベクトルの法線のアイソサーフェスを表示すると,面白いことがあります.このために,ExtractVectorNormフィルタを使用してベクトルフィールドからスカラフィールドを作成し,その上でIso-Surfaceモジュールを使用します.インタラクティブに作業する場合,オブジェクトのプロパティダイアログで輪郭の値を変更すると,フィールドの大きさを十分に理解できます.

magnitude = mlab.pipeline.extract_vector_norm(src)
mlab.pipeline.iso_surface(magnitude, contours=[1.9, 0.5])
_images/vector_field_isosurface.jpg
フローまたはフィールドライン:

特定のベクトルフィールドでは,フィールドに沿ったフローラインに興味深い意味があります.たとえば,これは流体力学の軌跡,あるいは電磁界の磁力線として解釈することができる. streamline モジュール,または mlab flow() 関数を使用して,特定のシードサーフェスで生成されたフローラインを表示できます.

flow = mlab.flow(u, v, w, seed_scale=1,
                          seed_resolution=5,
                          integration_direction='both')
_images/vector_field_flow.jpg
技術の組み合わせ:

ベクトルフィールドを意味のある形で視覚化するのは困難な作業であり,手元にあるすべてのツールを使用して目的を説明する必要があります.伝えるメッセージを選ぶことが大切です.ベクトルフィールドのすべてを視覚化することはできません.上のさまざまなツールを組み合わせて作成したビジュアライゼーションの例を次に示します.

mlab.figure(fgcolor=(0., 0., 0.), bgcolor=(1, 1, 1))
src = mlab.pipeline.vector_field(u, v, w)
magnitude = mlab.pipeline.extract_vector_norm(src)

# We apply the following modules on the magnitude object, in order to
# be able to display the norm of the vectors, eg as the color.
iso = mlab.pipeline.iso_surface(magnitude, contours=[1.9, ], opacity=0.3)

vec = mlab.pipeline.vectors(magnitude, mask_points=40,
                                    line_width=1,
                                    color=(.8, .8, .8),
                                    scale_factor=4.)

flow = mlab.pipeline.streamline(magnitude, seedtype='plane',
                                        seed_visible=False,
                                        seed_scale=0.5,
                                        seed_resolution=1,
                                        linetype='ribbon',)

vcp = mlab.pipeline.vector_cut_plane(magnitude, mask_points=2,
                                        scale_factor=4,
                                        colormap='jet',
                                        plane_orientation='x_axes')
_images/vector_field_combination.jpg

注釈

このセクションの大部分は,ビジュアル化オブジェクトを作成するためのコードの断片に集中していますが,Mayaviはインタラクティブなプログラムであり,これらのオブジェクトのプロパティはインタラクティブに変更できることを覚えておくことが重要です. オブジェクトのプロパティをインタラクティブに変更する を参照.視覚化に最適なパラメータを事前に選択することは,多くの場合不可能です.カラー,輪郭値,カラーマップ,ビュー角度など.対話的に選択する必要があります.再現性が必要な場合は,選択した値を元のスクリプトに追加できます.

さらに, mlab 関数は,可視化オブジェクトの可能性のほんの一部しか公開しません.ダイアログには,mlab関数によって返されるオブジェクトの属性によって完全に制御される,これらの機能の多くが表示されます.これらのオブジェクトはVTKオブジェクトから作成されているため,非常に豊富です.これらのファイルを表示しているときや,VTKのドキュメントでは,修正すべき適切な属性を見つけるのが難しいかもしれません.ですから,パイプラインビューダイアログを使って対話的に変更し, record feature を使って対応するコード行を見つけるのが最も簡単な方法です. Mayaviの視覚化の構成:パイプライン を参照して,レコード機能によって生成されたコード行と mlab の間のリンクをよりよく理解してください..


[1]Toussaint, V.; Carriere, P. & Raynal, F. A numerical Eulerian approach to mixing by chaotic advection Phys. Fluids, 1995, 7, 2587