VRED Python API v2

これは、Qt for Python (以前の PySide 2) に基づく、新しい VRED Python API v2 のドキュメントです。VRED Python API v1 のドキュメントにはここからアクセスできます。VRED 2024 以降、VRED は Qt 6 (PySide6 および shiboken6)を使用します。

タイプ

新しいインタフェースの一部の関数は、パラメータまたは戻り値の型に Qt タイプを使用します。これらのタイプは Python ネームスペースに自動的に読み込まれるため、PySide2 モジュールから読み込まなくても使用できます。

その他の Qt クラスは、次のように読み込むことができます。

from PySide6.QtCore import QLine
from PySide6.QtGui import QBrush

line = QLine(0,0,100,100)
brush = QBrush()

オブジェクト

新しいインタフェースのシーン オブジェクトは vrdObject から派生します。これらのオブジェクトのクラス名は、プレフィックス vrd で開始します。たとえば、ノード オブジェクトの場合は vrdNode、マテリアル オブジェクトの場合は vrdMaterial のプレフィックスが付きます。

API 関数またはメソッドからこれらのオブジェクトが返されるたびに、クラス タイプが動的に決定されます。つまり、ドキュメントで指定されたベース クラス タイプまたは子孫クラスのいずれかになります。たとえば、vrMaterialService.findMaterial(Environments)を使用して既定の環境スイッチを取得する場合、返されるオブジェクトは、ドキュメント化された基本タイプ vrdMaterial ではなく、vrdEnvironmentSwitchMaterial タイプになります。

したがって、返されたオブジェクトは既に最も具体的なタイプを示しているため、ユーザがアップキャストする必要はありません。ただし、実行時エラーを回避するには、特定のタイプのメソッドまたはプロパティにアクセスする前に、vrdObject.isType() を使用して返されたオブジェクトのタイプを確認する必要があります。たとえば、ユーザが上記の findMaterial() の呼び出しによって返されたマテリアルの choice プロパティにアクセスする場合は、material.getChoice() を呼び出す前に material.isType(vrdSwitchMaterial) を使用してマテリアル タイプをチェックする必要があります。ドキュメントに記載されているベース タイプのメソッドまたはプロパティにのみアクセスする場合、この操作は不要です。

サービス

オブジェクトにはプロパティを照会および変更する関数が多数ありますが、主なエントリ ポイントとして、サービスを通じて使用するオブジェクトを取得します。

サービスを使用して、既存のシーン オブジェクトの検索、新しいオブジェクトの作成、オブジェクトの削除、関連する VRED モジュールで使用できるその他の機能へのアクセスを行うことができます。

サービス クラスと同じ名前を持つオブジェクトを通じてサービス関数を呼び出します。次に例を示します。

camNode = vrCameraService.createCamera("new camera")

関数呼び出し

VRED API V2 において、関数呼び出し内でキーワード引数(名前付き引数)として渡すことができるのは、オプションのパラメータのみです。このドキュメントでは、関数シグネチャの既定値と一緒にオプション パラメータを示しています。

すべての必須パラメータは、署名で指定された順序で、位置引数(名前なし)として渡す必要があります。

たとえば、vrNodeService.findNode には 1 つの必須パラメータ (name) があり、残りはオプションです。つまり、次の関数呼び出しは機能します(2 番目と 3 番目のパラメータは省略しています)。

trackNode = vrNodeService.findNode("track1", root=vrCameraService.getCameraRoot())

一方、次の関数呼び出しはエラーになります。

trackNode = vrNodeService.findNode(name="track1", root=vrCameraService.getCameraRoot())

サードパーティ モジュールをインストールする

VRED は Python 3 に移行しましたが、サードパーティ モジュールは簡単にインストールできます。Python のインストール全体は、lib/python のインストール フォルダ内にあります。pip を使用して、公式の Python リポジトリからインストールできます。「numpy」をインストールする場合は、次の手順を実行します。

python.exe -m pip install numpy

pip は Python とは別に開発されています。pip を新しいバージョンにアップグレードする場合は、次の手順を実行します。

python.exe -m pip install --upgrade pip

追加された pip が動作を停止した場合は、Python のブートストラップ メカニズムを使用して復元できます。

python.exe -m ensurepip

また、モジュールを Lib/site-packages に手動でインストールすることもできます。Python API を使用して独自の C または C++ 拡張機能をコンパイルする場合は、必ず互換性のあるコンパイラを使用してください。オートデスクは、公式の Python 3 バイナリを再コンパイルしないで、VRED に使用しています。そのため、VRED 付属のディストリビューションと同じバージョン番号を持つ Python ディストリビューションを python.org から取得してコンパイルすると、機能します。

Web インタフェースを介して Python API を使用する

このインタフェースは、Python または Web インタフェースを介して使用できます。アクセスするには、JavaScript を使用します。関数の呼び出しは非同期で実行されます。次の例では、このような呼び出しが Web ページからどのように見えるのかを示します。すべてのパラメータと戻り値のタイプは、JavaScript タイプにマッピングされます。たとえば、QVector3D と QMatrix4x4 は 3 個または 16 個の数値からなる配列にマッピングされます。

<script type="module">
  import {api} from '/api.js';

  // reacting on a signal
  api.vrClusterService.started.connect(() => {console.log('Started')});
  // calling a function
  api.vrClusterService.start();
  // changing the position of the camera
  api.vrNodeService.findNode("Perspective")
      .then((node) => node.setTranslation([10,20,30]));
</script&gt>

API v1 と v2 を一緒に使用する

API v1 と v2 の両方の関数を同じスクリプトで使用できます。

API v1 では、ノード オブジェクトのタイプは vrNodePtr です。パラメータとして vrNodePtr を取る API v1 の関数で vrdNode オブジェクトを使用できます。同様に、vrdNode をパラメータとして取る API v2 の関数で vrNodePtr オブジェクトを使用できます。これらは自動的に変換されます。

vrdNode を明示的に vrNodePtr オブジェクトに変換するには :

oldNodePtr = toNode(newVRDObject.getObjectId())

vrNodePtr を vrdNode に変換することもできます。

newVRDObject = vrNodeService.getNodeFromId(oldNodePtr.getID())

シーングラフの用語

このドキュメントでのシーングラフの参照方法については、「VRED のノード グラフ」を参照してください。

Python サンプル スクリプト

VRED Python API のさまざまな機能を紹介するサンプル スクリプトのコレクションです。

このセクションのページ
親ページ: Python マニュアル