pyvista.Plotter.add_volume

Plotter.add_volume(

volume: DataSet | MultiBlock | NumpyArray[float],

scalars: str | NumpyArray[float] | None = None,

clim: float | tuple[float, float] | None = None,

resolution: VectorLike[float] | None = None,

opacity: OpacityOptions | NumpyArray[float] = 'linear',

n_colors: int = 256,

cmap: ColormapOptions | LookupTable | None = None,

flip_scalars: bool = False,

reset_camera: bool | None = None,

name: str | None = None,

ambient: float | None = None,

categories: bool | int = False,

culling: CullingOptions | bool = False,

multi_colors: bool = False,

blending: Literal['additive', 'maximum', 'minimum', 'composite', 'average'] = 'composite',

mapper: Literal['fixed_point', 'gpu', 'open_gl', 'smart', 'ugrid'] | None = None,

scalar_bar_args: ScalarBarArgs | None = None,

show_scalar_bar: bool | None = None,

annotations: dict[float, str] | None = None,

pickable: bool = True,

preference: PointLiteral | CellLiteral = 'point',

opacity_unit_distance: float | None = None,

shade: bool = False,

diffuse: float = 0.7,

specular: float = 0.2,

specular_power: float = 10.0,

render: bool | None = True,

user_matrix: TransformLike | None = None,

log_scale: bool = False,

**kwargs,

) → Actor | list[Actor]

ボリュームを追加し，デフォルトではスマートマッパーを使用してレンダーします．

numpy.ndarray, pyvista.ImageData, pyvista.RectilinearGrid, pyvista.UnstructuredGrid などの3次元データ型が必要です．

パラメータ:

volume3D numpy.ndarray | DataSet

表示する入力ボリューム．3 Dの数値配列を使用できます．

警告

入力が numpy.ndarray や pyvista.ImageData ，あるいは pyvista.RectilinearGrid でない場合，ボリュームレンダリングのパフォーマンスは低くなることがあります．

scalarsstr | numpy.ndarray, optional

メッシュの "色" に使用されるスカラー．メッシュ上に存在する配列の文字列名，またはメッシュ内のセル数または点の数と等しい長さの配列を受け入れます． scalars が None の場合，アクティブスカラーが使用されます．

スカラーは1次元または2次元である．1 次元であれば，スカラーはルックアップテーブルにマップされます．2 次元の場合，スカラーは直接 RGBA の値にマッピングされます．配列は (N, 4) の形状でなければならず， N は点の個数，データ型は np.uint8 となります．

climsequence[float] | float, optional

スカラーのカラーバー範囲．例: [-1, 2] ．スカラの dtype が np.uint8 でない場合，デフォルトはスカラ配列の最小値と最大値です．また，このパラメータの別名として rng も利用できます．

スカラーのデータ型が np.uint8 である場合，このパラメータのデフォルトは [0, 256] です．

単一の値が与えられた場合，範囲 [-clim, clim] が使用されます．

resolutionlist, optional

ブロックの解像度．例えば [1, 1, 1] です．解像度は負であってはいけません．VTK は負のスペーシングを受け付けますが，これは予期しない動作になります． pyvista #1967 を参照してください．

opacitystr | numpy.ndarray, optional

スカラー配列の不透明度マッピング．

文字列を指定することで，スカラーの範囲をあらかじめ定義された不透明度伝達関数にマッピングすることも可能です．また，カスタムメイドの転送関数として，長さ n_colors または配列のいずれかを渡すこともできますし，組み込みの転送関数を選択するために文字列を渡すこともできます．文字列の場合は，以下のいずれかである必要があります：

• 'linear' - 線形

• 'linear_r' - 反転を除く線形

• 'geom' - 対数スケールで等間隔に配置される

• 'geom_r' - 対数スケールで等間隔に配置され，反転される

• 'sigmoid' - -10.0 から 10.0 の間の線形マップ

• 'sigmoid_1' - -1.0 から 1.0 の間の線形マップ

• 'sigmoid_2' - -2.0 から 2.0 の間の線形マップ

• 'sigmoid_3' - -3.0 から 3.0 の間の線形マップ

• 'sigmoid_4' - -4.0 から 4.0 の間の線形マップ

• 'sigmoid_5' - -5.0 から 5.0 の間の線形マップ

• 'sigmoid_6' - -6.0 から 6.0 の間の線形マップ

• 'sigmoid_7' - -7.0 から 7.0 の間の線形マップ

• 'sigmoid_8' - -8.0 から 8.0 の間の線形マップ

• 'sigmoid_9' - -9.0 から 9.0 の間の線形マップ

• 'sigmoid_10' - -10.0 から 10.0 の間の線形マップ

• 'sigmoid_15' - -15.0 から 15.0 の間の線形マップ

• 'sigmoid_20' - -20.0 から 20.0 の間の線形マップ

• 'foreground' - 背景は透明，前景は不透明．

  セグメンテーションラベルでの使用を意図しています．配列の最小スカラー値が背景値 (例えば0) であると仮定します．

RGBAスカラーが提供された場合，このパラメータは 'linear' に設定され，不透明度伝達関数が入力された不透明度の値に影響を与えないようにします．

n_colorsint, optional

スカラーを表示するときに使用するカラーの数．デフォルトは256です．スカラーバーにもこの数の色があります．

cmapstr | list | LookupTable, default: pyvista.plotting.themes.Theme.cmap

If a string, this is the name of the matplotlib colormap to use when mapping the scalars. See Named Colormaps for supported colormaps.

Only applicable for when displaying scalars. colormap is also an accepted alias for this. If colorcet or cmocean are installed, their colormaps can be specified by name.

また，色のリストを指定して，既存のカラーマップをカスタムカラーマップで上書きすることもできます．例えば，3色のカラーマップを作成するには， ['green', 'red', 'blue'] ．

このパラメータには pyvista.LookupTable を指定することもできます．このパラメータが設定されている場合， n_colors のようなカラーマップを制御するすべてのパラメータは無視されます．

flip_scalarsbool, optional

cmapの方向を反転します．ほとんどのカラーマップでは， *_r サフィックスも同様にこれを行うことができます．

reset_camerabool, optional

このメッシュをシーンに追加した後，カメラをリセットします．

namestr, optional

簡単に更新できるように，追加したアクターの名前．この名前のアクターがレンダリングウィンドウに既に存在する場合は，新しいアクターに置き換えられます．

ambientfloat, optional

照明が有効な場合，これは，ビューアから放射された光源に向けられていないときにアクターに到達する0から1の光の量です．デフォルトは0.0です．

categoriesbool, optional

True に設定すると，スカラー配列内の一意の値の数が n_colors 引数として使用されます．

cullingstr, optional

選択された面はレンダリングされません．オプションは 'front' または 'back' です．これは，高密度のサーフェイスメッシュ，特にエッジが表示されている場合に便利ですが，フラットメッシュが部分的に表示されることがあります．デフォルトは False です．

multi_colorsbool, optional

マルチブロックオブジェクトを印刷するときに複数の色を使用するかどうかを指定します．ブロックは 'Reds' ， 'Greens' ， 'Blues' ， 'Grays' の順に色付けされます．

blendingstr, optional

入力オブジェクト()を表示するための描画モード． 'additive' ， 'maximum' ， 'minimum' ， 'composite' ， 'average' のいずれかです．デフォルトは 'composite' です．

mapperstr, optional

Volume mapper to use given by name. Options include: 'fixed_point', 'gpu', 'open_gl', 'smart', and 'ugrid'. If None the "volume_mapper" in the self._theme is used. If using 'fixed_point', only ImageData types can be used.

注釈

If a pyvista.UnstructuredGrid is input, the 'ugrid' mapper (vtkUnstructuredGridVolumeRayCastMapper) will be used regardless.

注釈

'smart' マッパーはレンダリングパラメータと利用可能なハードウェアに基づいて，リストアップされた他のマッパーの中から一つを選択します．ほとんどの場合， 'smart' は GPU が利用可能かどうかを確認し，利用可能な場合は 'gpu' マッパーを，そうでない場合は 'fixed_point' マッパーを使用します．

警告

'fixed_point' マッパーは CPU ベースなので， 'gpu' や 'open_gl' マッパーよりも低いパフォーマンスとなります．

scalar_bar_argsdict, optional

スカラーバーをシーンに追加するときに渡すキーワード引数のディクショナリ．オプションについては pyvista.Plotter.add_scalar_bar() を参照してください．

show_scalar_barbool

False の場合，スカラーバーはシーンに追加されません．デフォルトは True です．

annotationsdict, optional

注釈の辞書を渡します．キーはスカラー範囲のfloat値で，スカラーバーに注釈を付けます．値は文字列注釈です．

pickablebool, optional

このメッシュを選択可能にするかどうかを設定します．

preferencestr, optional

mesh.n_points == mesh.n_cells でスカラを設定した場合，このパラメータはスカラがどのようにメッシュにマッピングされるかを設定します． デフォルトの 'point' では，スカラーはメッシュのポイントに関連付けられます． これは 'point' または 'cell' のいずれかです．

opacity_unit_distancefloat, optional

スカラー不透明度転送関数が定義される単位距離を設定/返します．つまり，指定した距離にわたって，特定の不透明度(伝達関数から)が累積されます．これは，レンダリング中の実際のサンプリング距離に合わせて調整されます．既定では，体積の境界ボックスの対角線の長さを寸法で割った値です．

shadebool, default: False

デフォルトはオフです．シェーディングがオンの場合，マッパはシェーディング計算を実行できます - 場合によっては，シェーディングが適用されない(例えば，最大強度投影)ため，このフラグをオンにしてもシェーディングは実行されません．

diffusefloat, default: 0.7

拡散照明係数．

specularfloat, default: 0.2

鏡面反射光の係数．

specular_powerfloat, default: 10.0

鏡面パワー． 0.0 から 128.0 ．

renderbool, default: True

True のときに強制的にレンダーします．

user_matrixTransformLike, default: np.eye(4)

レンダリング前に Volume クラスに渡される行列．これはアクタ/レンダリングのみに影響し，入力ボリューム自体には影響しません．ユーザ行列は，レンダリング前にアクタに適用される最後の変換です．デフォルトは単位行列です．

log_scalebool, default: False

データを色にマッピングするときは，ログスケールを使用します．0未満のスカラーは，表現可能な最小の正のfloatにマップされます．

**kwargsdict, optional

オプションのキーワード引数．

戻り値:

pyvista.Actor

体積のアクター．

例

クールウォームのカラーマップを使って，内蔵されたボリュームの例を示します．

>>> from pyvista import examples
>>> import pyvista as pv
>>> bolt_nut = examples.download_bolt_nut()
>>> pl = pv.Plotter()
>>> _ = pl.add_volume(bolt_nut, cmap='coolwarm')
>>> pl.show()

スタティックシーン

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

ゼロからボリュームを作成し，スカラーの単一ベクトルを使用してプロットします．

>>> import pyvista as pv
>>> grid = pv.ImageData(dimensions=(9, 9, 9))
>>> grid['scalars'] = -grid.x
>>> pl = pv.Plotter()
>>> _ = pl.add_volume(grid, opacity='linear')
>>> pl.show()

スタティックシーン

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

RGBAスカラーを使用してゼロからボリュームをプロットする

>>> import pyvista as pv
>>> import numpy as np
>>> grid = pv.ImageData(dimensions=(5, 20, 20))
>>> scalars = grid.points - (grid.origin)
>>> scalars /= scalars.max()
>>> opacity = np.linalg.norm(grid.points - grid.center, axis=1).reshape(-1, 1)
>>> opacity /= opacity.max()
>>> scalars = np.hstack((scalars, opacity**3))
>>> scalars *= 255
>>> pl = pv.Plotter()
>>> vol = pl.add_volume(grid, scalars=scalars.astype(np.uint8))
>>> vol.prop.interpolation_type = 'linear'
>>> pl.show()

スタティックシーン

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

UnstructuredGridをプロットします．

>>> from pyvista import examples
>>> import pyvista as pv
>>> mesh = examples.download_letter_a()
>>> mesh['scalars'] = mesh.points[:, 1]
>>> pl = pv.Plotter()
>>> _ = pl.add_volume(mesh, opacity_unit_distance=0.1)
>>> pl.show()

スタティックシーン

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