PhysXプラグイン¶
概要¶
PhysXについて¶
PhysXはNVIDIA社が開発している物理エンジンです。もともとは同社のGPU上で動作する高速な物理計算エンジンとして登場しましたが、現在はCPU上で動作する部分もオープンソース化されており、 GitHub上 でBSD 3-Clauseライセンスのもと公開されています。剛体、関節機構、接触計算に加え、布や軟体、粒子などのシミュレーションにも対応する汎用物理エンジンであり、ゲームやロボティクス、CGなど幅広い分野で利用されています。
PhysXの特徴として、まず計算の高速性が挙げられます。PhysXはリアルタイム性を重視する用途において長年磨かれてきた実装を持ち、SIMD命令の活用や並列化、接触計算の効率化などにより高速に動作します。またシーン内の物体数が増えた際のスケーラビリティにも優れており、多数の剛体が接触しあう場面においても実用的な速度で計算を進められる設計となっています。
関節をもつ多体系ロボットのシミュレーションについては、 Articulation Reduced Coordinate と呼ばれる縮約座標系に基づく手法が用いられています。これはChoreonoid標準の物理エンジンであるAISTシミュレータと同じく、ロボットの関節空間上で運動方程式を解く方式であり、多関節ロボットをAISTシミュレータと同様に安定に処理することができます。
PhysXプラグインについて¶
ChoreonoidのPhysXプラグインは、PhysXをChoreonoidの物理エンジンとして利用するためのプラグインです。シミュレータアイテムとして「PhysXシミュレータ」を提供し、他の物理エンジンのシミュレータアイテムと同様の手順で利用することができます。
本プラグインでは、剛体・関節をもつロボットモデルのシミュレーションを主な対象としています。Choreonoidで扱う標準的なモデルをそのまま利用でき、位置制御・速度制御・トルク制御いずれの方式にも対応しています。
また本プラグインでは、履帯(クローラ)機構を実現するためのデバイスである PiecewiseRigidContinuousTrack （区分剛体無限軌道）に対応しています。これは履帯を構成する多数のシューを個別の剛体として扱うのではなく、駆動輪や従動輪の周囲に巻き回された連続的な帯として扱い、車輪の回転に応じて履帯のシューが実際に周回して地面を捉える挙動を再現するものです。シューを1つ1つ剛体として扱う方式と比較して計算コストを大幅に抑えつつ、履帯特有の接地挙動を安定にシミュレーションすることができます。クローラ型ロボットのシミュレーションにおいて特に有用な機能です。なおこのデバイスはBulletプラグインでも利用可能となっています。詳細は 無限軌道（クローラ）の区分剛体シミュレーション を参照してください。
PhysXはChoreonoidにおける準標準の物理エンジンとして位置付けられており、ソースコードがChoreonoid本体のリポジトリに同梱されています。これによりPhysXを別途ダウンロード・ビルドする必要がなく、Choreonoidをビルドするだけで自動的に利用できる状態になります。
セットアップ¶
基本的なビルド方法¶
PhysXプラグインはChoreonoid本体にソースコードが同梱されており、デフォルトで有効になっています。そのため通常のChoreonoidのビルド手順に従うだけで、PhysXプラグインも一緒にビルドされ、すぐに利用できる状態となります。
CMakeのオプションとしては次の2つが用意されていますが、通常は特に変更する必要はありません。
ENABLE_PHYSX: 同梱のPhysXライブラリをビルドします。デフォルトはONです。BUILD_PHYSX_PLUGIN: PhysXプラグイン本体をビルドします。デフォルトはENABLE_PHYSXの値(つまり通常はON)です。
PhysXを使いたくない場合は、CMakeの設定で ENABLE_PHYSX と BUILD_PHYSX_PLUGIN の両方を OFF にしてください。
注釈
BUILD_PHYSX_PLUGIN のデフォルト値は ENABLE_PHYSX の値に連動しますが、これはCMakeの仕様により「キャッシュに値が保存されていない場合のみ」有効です。そのため、一度 ENABLE_PHYSX=ON でCMake設定を行った後に ENABLE_PHYSX のみを OFF に変更すると、 BUILD_PHYSX_PLUGIN はキャッシュ値の ON のままとなり、外部PhysXを使う経路としてエラーになります。両方を明示的に OFF に設定するか、ビルドディレクトリを作り直してから設定してください。
補足：外部ビルドのPhysXを使用する場合¶
同梱のPhysXではなく、ユーザが独自にビルドしたPhysXライブラリを利用したい場合は、以下の手順でまず外部のPhysX SDKをビルドし、そのうえでChoreonoid側のCMake設定を行います。同梱のPhysXに不具合があった場合や、新しいバージョンのPhysXを試したい場合などに利用できます。
PhysX SDKのソースコードは NVIDIA-Omniverse/PhysX (GitHub) で公開されています。
なお、ここではLinux環境(Ubuntu 24.04にて動作確認)での手順を説明します。
依存パッケージのインストール
PhysX SDKのビルドには以下のパッケージが必要です。
sudo apt install cmake build-essential python3 curl
PhysX SDKのソース取得
GitHubからPhysX SDKのソースコードを取得します。
git clone https://github.com/NVIDIA-Omniverse/PhysX.git
特定のバージョンを使用したい場合は、そのリリースタグに切り替えてください。例えば同梱のPhysXと同じバージョンを使用したい場合は、以下のようにします。
cd PhysX
git checkout 107.3-physx-5.6.1
Snippetsビルドの無効化
デフォルトの設定ではPhysXのサンプル(Snippets)もビルドされますが、ビルドエラーになる場合があります。Choreonoidで使用するライブラリのビルドには不要なので、無効化しておきます。
以下のファイルをテキストエディタで開いてください。
physx/buildtools/presets/public/linux-gcc-cpu-only.xml
PX_BUILDSNIPPETS の value を "True" から "False" に変更します。
変更前: <cmakeSwitch name="PX_BUILDSNIPPETS" value="True" .../>
変更後: <cmakeSwitch name="PX_BUILDSNIPPETS" value="False" .../>
PhysX SDKのビルド
physxディレクトリに移動し、ビルドプロジェクトを生成します。
cd physx
以下のいずれかの方法でプリセットを指定します。
方法A: コマンドライン引数で直接指定する場合:
./generate_projects.sh linux-gcc-cpu-only
方法B: 対話メニューで選択する場合:
./generate_projects.sh
この場合はプリセットの一覧が表示されるので、 linux-gcc-cpu-only を選択してください。
続いて、生成されたreleaseビルドディレクトリに移動してビルドします。
cd compiler/linux-gcc-cpu-only-release
make -j$(nproc)
ビルドが完了すると、 PhysX/physx/bin/linux.x86_64/release/ 以下に静的ライブラリファイルが生成されます。
ChoreonoidのCMake設定
Choreonoid側では、外部PhysXを使用するようCMake設定を行います。ビルドディレクトリでCMakeを呼び出す際に、以下のいずれかの方法で設定します。
方法A: コマンドラインで直接指定する場合:
cmake <choreonoidのソースディレクトリ> \
-DENABLE_PHYSX=OFF \
-DBUILD_PHYSX_PLUGIN=ON \
-DPHYSX_DIR=<PhysXのphysxディレクトリへのパス> \
-DPHYSX_BINARY_TYPE=release
PHYSX_DIR には上記手順でクローンしたPhysXリポジトリ内の physx ディレクトリの絶対パスを指定してください(例: -DPHYSX_DIR=$HOME/PhysX/physx )。
方法B: ccmake で対話的に設定する場合:
ccmake <choreonoidのソースディレクトリ>
ccmakeの画面で以下の項目を設定してください。
ENABLE_PHYSXをOFFに変更BUILD_PHYSX_PLUGINをONに変更PHYSX_DIRにPhysXのphysxディレクトリの絶対パスを入力PHYSX_BINARY_TYPEにreleaseを入力
設定後、 [c] キーで設定を適用し、 [g] キーでMakefileを生成します。
CMakeの設定が完了したら、通常どおりChoreonoidをビルドしてください。
PHYSX_BINARY_TYPE はPhysX SDKのビルド種別を指定する変数で、以下の4種類があります。
release: 通常利用向けの最適化ビルド。最も高速profile: 最適化 + プロファイリング機能 + PVD対応checked: 最適化 + API呼び出しの引数チェックdebug: 最適化なし + PhysX内部のデバッグ情報あり
特別な理由がなければ release を指定してください。指定する種別は事前にPhysX SDK側でビルドしておく必要があります。
PhysXシミュレータの利用¶
PhysXプラグインが読み込まれていると、シミュレータアイテムとして「PhysXシミュレータ」が利用可能となります。メインメニューの「ファイル」-「新規」-「PhysXシミュレータ」で生成し、 シミュレーションプロジェクトの作成 で解説されている手順でワールドアイテムの子アイテムとして配置することで使用できます。基本的な使い方は他のシミュレータアイテムと共通です。
対応機能¶
PhysXシミュレータは以下の機能に対応しています。
アクチュエーションモード: トルク指令（JointEffort）、速度指令（JointVelocity）、位置指令（JointDisplacement）
力センサ、加速度センサ、角速度センサ（レートジャイロ）のシミュレーション
リンクの速度・加速度・駆動トルク（力）の状態出力（対応するプロパティで有効化）
接触マテリアル による摩擦係数・反発係数等の設定
追加拘束（extra joint）。異なるボディ間にまたがる拘束にも対応（ 追加拘束の設定 ）
等価ロータ慣性（armature）の考慮（ ロータ慣性の設定 ）
表面速度（surface velocity）による疑似的なクローラやコンベアのシミュレーション
PiecewiseRigidContinuousTrackデバイスによる履帯シミュレーション（ 無限軌道（クローラ）の区分剛体シミュレーション ）
プロパティ¶
PhysXシミュレータアイテムでは、 シミュレータアイテム共通のプロパティ に加えて、以下の固有のプロパティが利用できます。
プロパティ |
デフォルト値 |
意味 |
|---|---|---|
重力加速度 |
0 0 -9.80665 |
重力加速度ベクトルです [m/s^2]。 |
シーン原点シフト |
0 0 0 |
PhysXの物理計算シーンの原点を、Choreonoidの仮想世界に対してシフトします。原点から大きく離れた場所でシミュレーションを行う際の数値誤差対策に使用できます。 |
スレッド数 |
0 |
PhysXの計算に使用するワーカースレッドの数です。0の場合は追加のワーカースレッドを使用しません。 |
許容スケール長さ |
1.0 |
シミュレーション対象の典型的な物体サイズの目安です [m]。PhysX内部の各種許容値の基準となります。 |
許容スケール速度 |
10.0 |
シミュレーション対象の典型的な速度の目安です [m/s]。PhysX内部の各種許容値の基準となります。 |
凸メッシュタイトバウンド |
false |
凸メッシュのバウンディングをよりタイトに計算します。精度が向上する場合がありますが、計算コストは増加します。 |
凸メッシュクリーンアップをスキップ |
false |
凸メッシュ生成時のクリーンアップ処理をスキップして、モデルの読み込みを高速化します。 |
動的オブジェクトに三角メッシュを使用 |
false |
動く物体の形状にも三角メッシュをそのまま使用します。有効時はSDF（符号付距離場）による接触計算が併用されます。無効時は、動く物体のメッシュ形状は凸形状に変換されます。 |
三角メッシュ前処理 |
true |
三角メッシュ生成時にアクティブエッジの事前計算等の前処理を行います。 |
メッシュクリーニング |
true |
三角メッシュ生成時に重複頂点の統合等のクリーニング処理を行います。 |
SDF間隔 |
0.01 [m] |
SDFのサンプリング間隔です。「動的オブジェクトに三角メッシュを使用」が有効なときに使用されます。 |
SDFサブグリッドサイズ |
6 |
SDFのサブグリッドのサイズです。 |
SDFピクセルあたりビット数 |
16 |
SDFのサブグリッドピクセルあたりのビット数です。 |
SDF構築スレッド数 |
4 |
SDFの構築に使用するスレッド数です。 |
ソルバタイプ |
TGS |
PhysXの拘束ソルバを「PGS」「TGS」から選択します。 |
位置反復回数 |
8 |
ソルバの位置反復の回数です。 |
速度反復回数 |
2 |
ソルバの速度反復の回数です。 |
TGS反復毎に外力を適用 |
false |
TGSソルバの反復ごとに外力を適用します。 |
線形ダンピング |
0.0 |
剛体の並進運動に適用するダンピング係数です。 |
角度ダンピング |
0.0 |
剛体の回転運動に適用するダンピング係数です。 |
駆動剛性 |
1.0e8 |
位置指令・速度指令で関節を駆動する際のジョイントドライブの剛性です。 |
駆動ダンピング |
1.0e5 |
ジョイントドライブのダンピングです。 |
速度出力 |
false |
リンクの速度をシミュレーション結果として出力します。 |
加速度出力 |
false |
リンクの加速度をシミュレーション結果として出力します。 |
駆動トルク／力出力 |
false |
関節の駆動に実際に使用されたトルク（直動関節の場合は力）を、関節のエフォート値として書き戻します。 |
エラー出力 |
true |
PhysX内部のエラー・警告メッセージをメッセージビューに出力します。 |
サンプル¶
PhysXプラグインを利用できるサンプルプロジェクトとして、履帯シミュレーションのサンプルが choreonoid/sample/PiecewiseRigidContinuousTrack/ ディレクトリに用意されています。いずれのサンプルも、PhysXシミュレータとBulletシミュレータの両方のシミュレータアイテムを含んでおり、使用するシミュレータを選択してシミュレーションを実行できます。
PRCTrackTank¶
sample/PiecewiseRigidContinuousTrack/PRCTrackTank.cnoid は、戦車型のロボットモデルを用いた履帯シミュレーションのサンプルです。PiecewiseRigidContinuousTrackデバイスによる履帯を備えたタンクモデルを、ゲームパッド等のジョイスティック（または仮想ジョイスティックビュー）で操縦できます。
PRCTrackVehicle¶
sample/PiecewiseRigidContinuousTrack/PRCTrackVehicle.cnoid は、クローラ型の走行車両を起伏のある地形上で走行させるサンプルです。こちらもジョイスティックで操縦でき、履帯特有の接地挙動を確認できます。
また、これら以外の一般のシミュレーションサンプル（ sample/SimpleController/ 等）についても、プロジェクト内のシミュレータアイテムをPhysXシミュレータに差し替えることで、多くのものをPhysXでシミュレーションすることができます。