10. アノテーション
特定のデータ値の明示的なラベル付けと注釈付けは、多くの場合、データの可視化と分析において重要な要素です。ParaViewには、レンダリングで注釈を付けるためのさまざまなメカニズムが用意されており、レンダービュー内の他の視覚要素と一緒にレンダリングされたフリーの浮動テキストから、特定の点またはセルに関連付けられたデータ値まであります。
10.1. アノテーションソース
いくつかのタイプのテキスト注釈 (アノテーション、Annotation)は、Sources > Alphabetical メニューから追加できます。これらのソースからのテキストは、レンダリングビューの3D要素の上に描画されます。すべての注釈ソースは、 Properties
パネルの Display
セクションでいくつかの共通プロパティを共有します。これには、使用するフォント、テキストのサイズ、色、不透明度、位置合わせなどの Font Properties
や、太字、斜体、影付きなどの適用するテキスト効果が含まれます。

図 10.1 アノテーションソースおよびフィルタのフォントプロパティコントロール
ParaView では、Arial、Courier、Timesの3種類のフォントを使用できます。 また、ポップアップメニューの Font Properties
の下の File
エントリを選択し、フォントファイルテキストフィールドの右にある ...
ボタンをクリックして、任意のTrueTypeフォントファイル(*.ttf)を指定することもできます。ファイル選択ダイアログが表示され、paraview
(又は pvpython
)が実行されているファイルシステムからフォントファイルを選択できます。
残りの表示プロパティは、テキストをレンダービューのどこに配置するかをコントロールします。配置モードには、レンダービューに対する定義済みの位置を使用するモードと、レンダービューでの任意のインタラクティブな配置を可能にするモードの2つがあります。最初のモードは、 Use Window Location
チェックボックスが選択されている場合にアクティブになります。これにより、注釈をレンダービューの4つのコーナーのいずれかに配置したり、レンダービューの上部または下部の水平方向の中央に配置することができます。位置を表すアイコン付きのボタンが Pipeline
ブラウザに表示されます。これらのボタンは、図 10.2 に示すように、レンダービュー内の位置に対応します。

図 10.2 アノテーション配置ボタンとアノテーションを配置する場所
2番目のモードは Lower Left Corner
チェックボックスをクリックするとアクティブになり、注釈を自由に配置できます。 Interactivity
プロパティが有効な場合は、レンダービューで注釈をクリックしてドラッグして配置するか、注釈の境界ボックスの左下コーナーを配置する位置を手動で入力できます。座標は、x次元とy次元の[0, 1]からの範囲の分数座標で定義されます。レンダービューの座標系の原点は左下であるため、 Lower Left Corner
の値[0、0]を指定すると、注釈はレンダービューの左下コーナーに配置されます。
10.1.1. Text
ソース
Text
ソースを使用すると、レンダービューにテキスト注釈を追加できます。表示されるテキストを定義するプロパティが1つあります。テキストは複数行にすることができ、数字とUnicode文字を含めることができます。また、開始と終了のドル記号の間にMathtex式を含めることもできます。数式は、TeXの数式 [dt] のサブセットです。Mathtextを使用する場合、テキストは1行のみにすることができます。

図 10.3 Mathtext [dt] 式からレンダリングされた数式を使用した、左上隅にある Text
ソース・アノテーションの例
10.1.2. Annotate Time
ソース
The Annotate Time
source is nearly identical to the Text
source, but
it also offers access to the current time value set in ParaView. Control
over the format of the time display is available through the
Format
property. This property takes a string with optional formatting sections
understood by the fmt
library. By default, the value is "Time: {time:f}" where the "time" term
inside the curly braces is replaced with ParaView's current time value, and the ":f" specifies that
it should be formatted as a float with six decimal digits. For other formatting
possibilities, please see the fmt
syntax description at https://fmt.dev/dev/syntax/.
Examples are near the bottom of that page.
10.2. アノテーションフィルタ
前節で説明したアノテーションソースは、読み込まれたデータセットに依存しないテキストアノテーションを追加するために利用できます。パイプラインブラウザで利用可能なデータソースの値を表示するアノテーションを作成するために、いくつかのアノテーションフィルタが利用可能です。テキストフォントやアノテーションの場所を変更するためのプロパティは、前のセクションで説明したアノテーションソースで利用できるものと全く同じです。
10.2.1. Annotate Attribute Data
フィルタ
Annotate Attribute Data
を使用すると、データセット内の配列(または属性)からのデータ値を使用して注釈を作成できます。フィルタを使用するには、まず Select Input Array
で目的のデータを含むデータ配列を選択します。これらの配列は、点、セル、またはフィールドのデータ配列です。 Element Id
プロパティは、注釈に値を表示する点またはセルのインデックスを指定します。選択した入力配列がフィールド配列(点またはセルに関連付けられていない)の場合、 Element Id
は表示する配列のタプルを指定します。並列に実行している場合、 Process Id
は値を取得する配列を保持しているプロセスを表します。

図 10.4 Annotate Attribute Data
フィルタのプロパティ
Prefix
テキストプロパティは、レンダリングされた注釈の属性値の前に配置されます。書式設定文字列がありません。接頭辞の後に番号が追加されます。選択した配列値がスカラー値の場合、注釈には数値のみが含まれます。一方、配列の値がマルチコンポーネント配列の場合、個々のコンポーネントは括弧で囲まれたスペース区切りのリストで注釈ラベルに追加されます。
10.2.2. Annotate Global Data
フィルタ
ファイルフォーマットによっては、タイムステップごとにデータ配列に格納される単一のデータ値である global data`
という概念を含むものもあります。ParaView はこのようなデータ値のセットを、タイムステップと同じ数の値を持つデータセットに関連付けられたフィールドデータ配列として保存します。レンダリングビューにこれらのグローバルな値を表示するには、Annotate Global Data
フィルタを使用します。配列選択 Select Arrays
ポップアップメニューには、利用可能なフィールドデータ配列が表示されます。Prefix
と Suffix
プロパティは、それぞれアノテーション内のデータ値の前と後にきます。Format
プロパティは、 printf 関数呼び出しで使用するような、C 言語の数値フォーマット指定子です。このフォーマットが global data
型に対して無効な場合は、フィルタが警告を表示します。
10.2.3. Annotate Time Filter
フィルタ
ParaView の優れた機能は、異なる時刻に異なるデータを生成するデータソースをサポートすることです。たとえば、要求されたタイムステップのデータを読み込むファイルリーダーや、特定の時間フィルタなどがあります。各データソースは、データを生成できる時間値を ParaView に伝達します。ParaViewで生成および表示されるデータは、ParaView VCR Controls
または Time Inspector
パネルで設定した時間によって異なります。
さらに素晴らしいのは、複数のデータソースを持ち、それぞれが情報を出して、おそらく固有の時間のセットに応答できることです。つまり、利用可能なソースは、同じ時点のセットをサポートしていることを伝達する必要はありません。実際、まったく異なる時点でデータを定義することがあります。要求された時間が与えられると、各データソースは、要求された時間に最も近いサポート時間に対応するデータを生成します。この機能により、たとえば、異なる時間解像度で変化する複数のデータセットからアニメーションを作成できます。
前述の Annotate Time
ソースは ParaView が現在要求している時間を表示するために使用できますが、特定のデータソースが応答している時間値を表示するわけではありません。例えば、ParaView は時間5.0のデータを要求しているかもしれませんが、ソースが時間値10.0以上のデータを生成する場合、時間5.0が要求されていても、時間10.0のデータを生産データソースがデータを生成している時間を表示するには、代わりに Annotate Time Filter
を使用することができます。このフィルタを目的のデータソースにアタッチするだけです。複数のデータソースが存在する場合、このフィルタの個別のインスタンスをそれぞれのデータソースにアタッチすることができます。
時刻の表示形式は Format
プロパティで制御することができます。このフォーマット文字列は fmt
ライブラリでサポートされている文字列で、デフォルトは "Time: {time:f}" です。中括弧内の "time" は、このフィルタが接続されているデータソースの現在ロードされている時刻の値に置き換えられます。このフィルタには Shift
と Scale
プロパティも含まれており、表示される時刻を線形に変換するために使用されます。時間の値にはまずスケールが掛けられ、次にシフトが加えられます。
10.2.4. Environment Annotation
フィルタ
可視化が生成された環境に関する情報を表示する場合は、 Environment Annotation
フィルタを使用します。このフィルタをデータソースにアタッチすると、ParaView を実行しているシステム上のユーザ名を自動的に表示したり、ユーザ名の生成に使用されたオペレーティングシステムを表示したり、ビジュアル化が生成された日時を表示したり、ソースデータのファイル名を表示することができます(該当する場合)。これらの各項目は、このフィルタの Properties
パネルのチェックボックスで有効または無効にできます。
このフィルタの入力ソースがファイルリーダの場合、 File Name
プロパティはファイル名に初期化されます。ファイルのフルパスを表示するには、 Display Full Path
チェックボックスを使用できますが、オフにした場合はファイル名のみが表示されます。このデフォルトのファイルパスは、 File Name
プロパティのテキストを変更することでオーバーライドできます。このフィルタがリーダーではなくフィルタにアタッチされている場合、ファイルパスは空の文字列に初期化されます。元のファイル名に手動で変更することも、必要に応じて任意の文字列に変更することもできます。
10.2.5. Python Annotation
フィルタ
最も汎用性の高い注釈フィルタである Python Annotation
フィルタは、データセットに関する情報を含む注釈を生成する最も一般的な方法を提供します。点、セル、フィールド、および行のデータ配列から値にアクセスし、 Expression
プロパティで定義された短いPython式の算術演算と組み合わせることができます。 Expression
で使用可能なデータ配列のタイプは、 Array Association
プロパティで設定されます。
先に進む前に、 Python Annotation
フィルタの使用例を見てみましょう。点インデックス22の Pressure
という名前の点配列のデータ値を表示するとします。まず、 Array Association
を Point Data
に設定して、点データ配列がPythonの注釈式で参照できるようにします。点22の圧力値を表示するには、 Expression
プロパティを次のように設定します。
Pressure[22]

図 10.5 点22の Pressure
配列の値を示している、基本的な Python Annotation
フィルタの例
Pythonの式を拡張して、注釈により多くの意味を持たせることができます。プレフィックスを追加するには、 Expression
を次のように設定します。
'Pressure: %f' % (Pressure[22])
noindent 選択した関連付けのすべてのデータ配列は、名前が有効なPython変数である限り、式で参照できる変数として提供されます。無効なPython変数名である配列名は、配列名を修正して使用できます。この配列名のサニタイズされたバージョンは、文字、数字、アンダースコア (_
) である配列名の文字のサブセットが、元の配列名に現れる順にスペースなしで結合されたものです。たとえば、Velocity X
という名前の配列は、変数 VelocityX
で使用できます。
マルチブロックデータセットなどの複合データセット内の点データおよびセルデータへのアクセスは、非複合データセット内の点データまたはセルデータへのアクセスとは多少異なります。 式
Pressure[22]
は、非複合データセット内の点配列から単一のスカラー値を取得し、同じ式は各ブロック内の Pressure
配列の22番目の要素を取得します。これらの値は、データセット内の各ブロックに関連付けられた配列を保持するデータ構造であるVTKCompositeDataArrayに保持されます。 したがって、次の式
Pressure[22]
は複合データセット上で評価され、返されて表示される値は、実際には各ブロックからの配列値の集合です。単一のブロックから値にアクセスするには、そのブロックの配列を、結果VTKCompositeDataArrayの Arrays
メンバから選択する必要があります。たとえば、ブロック2の22番目の点に関連付けられた Pressure
値を表示するには以下のようになります。
Pressure[22].Arrays[2]
この式は、 Pressure
配列が単一のコンポーネントを持つと仮定して、レンダリングされた注釈に単一のデータ値を生成します。配列の値の範囲を表示するには、インデックスの Pressure
フィールドでPythonの範囲式を使用します。例えば、以下のようになります。
Pressure[22:24].Arrays[2]
これにより、ブロック2の点22と23の Pressure
値が表示されます。また、Arrays
メンバにインデックス範囲を指定して、複数の配列を取得することもできます。例えば、以下のようになります。
Pressure[22:24].Arrays[2:5]
この式は、ブロック2、3、および4の点22および23に対して Pressure
と評価されます。
Array Association
は、指定した関連付けのデータ配列のセットを、 Expression
で使用できる変数として使用できるようにするための便利な機能です。これらの配列名を使用する欠点は、一度に1つの配列の関連付けしか使用できないことです。つまり、たとえば、セルデータ配列と点データ配列の組み合わせを必要とする注釈は、これらの便利なPython変数だけでは表現できません。
幸いなことに、少し冗長な式を使用すると、このフィルタの入力内の任意の配列にアクセスできます。たとえば、次の式は、セルのデータ値に点のデータ値を乗算します。
inputs[0].CellData['Volume'][0] * inputs[0].PointData['Pressure'][0]
上記の例では、入力内の配列は元の配列名を使用してアクセスされることに注意してください。
上記の例では、式 inputs[0]
はフィルタへの最初の入力を参照します。このフィルタは1つの入力しか取ることができませんが、 Python Calculator
(5.9.3 章 で説明されています)が使用するのと同じコードに基づいています。このコードは、このフィルタの複数の入力をPythonリストに入れます。したがって、 Python Annotation
フィルタへの入力は inputs[0]
として参照されます。
このフィルタは、現在の配列の関連付けの変数を式で使用できるようにするだけでなく、注釈値を計算するときに便利なその他の変数を提供します。
points
: 点の位置(明示的な点を持つデータセットで使用可能)。time_value
,t_value
: ParaView に設定された現在の時刻の値。time_steps
,t_steps
: 入力で使用可能なタイムステップ数。time_range
,t_range
: 入力のタイムステップの範囲。time_index
,t_index
: ParaView の現在のタイムステップのインデックス。
上記の変数が定義されていない場合があります。イメージデータなど、入力に明示的に定義された点がない場合、points
変数は定義されません。入力がタイムステップを定義しない場合、time_*
変数と t_*
変数は定義されません。
- 最後に、
Python Calculator
のすべての機能が利用可能であり(5.9.3 章 を参照) 、 NumPyの統合、NumPyメソッドとSciPyメソッドへのアクセスなどを含みます。
Common Errors
時間関連の変数は、点データ配列またはセルデータ配列にインデックスを付けるために必要ではありません。フィルタで使用できるのは、現在のタイムステップ用にロードされた点配列とセル配列のみです。このフィルタ内から、任意のタイムステップの点またはセルデータにアクセスすることはできません。
このフィルタの機能を使用すると、次に示すように、その他のアノテーションソースとフィルタを再現できます。
Text
source: テキストMy annotation
を生成するには、"My annotation"
と書きます。Annotate Time
source:Time: {time:f}
と同じ内容を表示するには、"Time: %f" % time_value
と記述してください。Annotate Attribute Data
filter:Select Input Array
をEQPS
に、Element Id
を0に、Process Id
を0に、Prefix
をValue is:
にそれぞれ設定するのと同じ結果を得るには、'Value is: %.12f' % (inputs[0].CellData['EQPS'][0])
と書きます。Annotate Global Data
filter: To produce the same annotation as settingSelect Arrays
toKE
,Prefix
toValue is:
,Format
to%7.5g
, and empty suffix, write"Value is: %7.5g" % (inputs[0].GlobalData['KE'][time_index])
Annotate Time Filter
:Format
をTime: %f
に、Shift
を3に、Scale
を2に設定するのと同じ結果を得るには、"Time: %f" % (2*time_value + 3)
と書きます。
上記の例は、 Python Annotation
フィルタの汎用性を示すためのものです。特殊な注釈ソースとフィルタを使用する方が、例のように式を入力するよりも便利です。