メインコンテンツへ移動
AIチュートリアル

WonderSnapでGPUパーティクルモデルを構築・操作する

このチュートリアルでは、WonderSnapのインストールとローカル起動、ジェスチャーやキーボード入力によるインタラクティブなパーティクルモデルの操作、パフォーマンス設定の調整、高度な教育機能の活用、Playwrightテストスイートの実行方法を説明します。

約14分で読了
WonderSnapでGPUパーティクルモデルを構築・操作する

WonderSnapとは？

WonderSnapは、プロシージャルモデルを最大250,000個のGPU駆動パーティクルによる輝く雲へ変える、ブラウザベースの3D体験です。指を鳴らしてパーティクルを呼び出し、ランドマークや解剖学的構造に形成したり、手でモデルを回転させたり、アセンブリをラベル付きの分解図として開いたりできます。

このアプリケーションは、デバイス上でのハンドトラッキング、カスタムジェスチャー認識、プロシージャルモデル、手書きのWebGL2レンダラーを組み合わせています。Three.js、ゲームエンジン、フロントエンドフレームワークは使用していません。ウェブカメラの映像は端末内にとどまり、サーバーへ送信されることはありません。

ウェブカメラは任意です。すべての基本操作は、画面上のコントロール、キーボード、マウスでも利用できます。

主な機能

  • GPUパーティクルレンダリング：パーティクル物理演算はWebGL2のトランスフォームフィードバックで実行され、最大250,000個のパーティクルに対応します。
  • デバイス上のハンドトラッキング：MediaPipe Hand Landmarkerが、1つの手につき21個のランドマークを持つ最大2つの手を追跡します。
  • ジェスチャー認識：カスタム分類器が、指を鳴らす動作、握りこぶし、開いた手、指差し、つまむ動作、ピースサイン、手の回転、両手でのズームを認識します。
  • 33種類のプロシージャルモデル：ランドマーク、解剖学、生物学、エンジン、乗り物、機械を収録しています。
  • インタラクティブなパーツ：名前付きのコンポーネントを発光させ、分解図として分離し、ラベルを表示して、詳しく調べるために引き出せます。
  • アニメーションする解剖モデル：心臓は毎分72回拍動し、肺は4.5秒周期で呼吸します。
  • 学習ツール：クイズモードではパーツの識別問題が出題され、説明機能と音声機能でパーツを解説します。
  • 音声操作：ChromeとEdgeでは、show me the heart、zoom in、quizなどのコマンドを処理できます。
  • 切断表示と録画：発光する断面を表示し、シーンをWebM動画として保存できます。

必要条件

WonderSnapをインストールする前に、次の環境を用意してください。

  • Node.js 18以降。
  • 記載されているブラウザ体験に対応したChromeまたはEdge。
  • ジェスチャー操作を使用する場合はウェブカメラ。
  • WebGL2に対応したブラウザとデバイス。

カメラにはlocalhostまたはHTTPSアドレスからアクセスする必要があります。index.htmlをダブルクリックしてアプリケーションを起動せず、付属のローカルサーバーを使用してください。

WonderSnapのインストールと起動

1. リポジトリをクローンする

git clone https://github.com/AkbarSheikh-debug/wondersnap.git
cd wondersnap

2. 依存関係をインストールする

npm install

この手順により、ハンドトラッキングのランタイムもnode_modulesから利用できるようになります。MediaPipeが読み込まれない場合は、インストールが正常に完了していることを確認してください。

3. ローカルサーバーを起動する

npm start

ChromeまたはEdgeでhttp://localhost:5173を開きます。カメラで開始を選択するとハンドトラッキングが有効になり、カメラなしで続行を選択するとマウス、キーボード、画面上のコントロールを使用できます。

4. 必要に応じて別のポートを使用する

ポート5173がすでに使用されている場合は、起動コマンドに別のポートを指定します。

npm start -- 8080

その後、http://localhost:8080を開きます。

基本的なジェスチャーワークフロー

カメラへのアクセスを許可したら、ウェブカメラにはっきり映る位置に手を置きます。基本的な操作手順は次のとおりです。

  1. 指を鳴らすとパーティクルが呼び出されます。もう一度指を鳴らすと、現在のモデルが溶けるように消えます。
  2. 握りこぶしを作ると、選択したワンダー、臓器、乗り物、エンジン、機械が形成されます。
  3. 手を上げたり、ひねったり、傾けたりすると、形成されたモデルを回転・傾斜させられます。
  4. 手を開くと、ワンダーが次のモデルへ移動します。臓器、エンジン、乗り物では、手を開くことでパーツが外側へ分解する距離を調整でき、手を閉じると再びまとまります。
  5. パーツを指差し、その上に指を置いたままにすると選択できます。パーツが発光し、役割を説明する情報カードが表示されます。
  6. つまむと、選択したパーツを手前に引き寄せられます。もう一度つまむと元の位置に戻ります。
  7. 両手を使い、両手の間隔を変えるとズームインまたはズームアウトできます。
  8. ピースサインを作ると、次のモデルへ移動します。

キーボードとマウスの使用

ウェブカメラがない場合や、より正確に操作したい場合は、キーボードとマウスを使用してください。パーツをクリックして選択し、シーンをドラッグして回転させます。

  • Space：指を鳴らす動作を再現します。
  • F、O、V：握りこぶし、開いた手、ピースサインの動作を実行します。
  • Left Arrow、Right Arrow：前または次のモデルを選択します。
  • E、Up Arrow、Down Arrow、またはマウスホイール：分解表示を調整します。
  • +、-、0：ズームを変更またはリセットします。Controlキーとマウスホイールも使用できます。
  • C：カメラのオン・オフを切り替えます。
  • L：パーツラベルの表示・非表示を切り替えます。
  • R：自動回転のオン・オフを切り替えます。
  • G：手による回転を有効または無効にします。
  • X：断面表示を有効にします。,と.で切断面を少しずつ動かせます。
  • Q：クイズモードを開始します。
  • M：音声コマンドと読み上げ機能を使用します。
  • K：動画を録画します。
  • D：組み込みデモを再生します。
  • I：選択したパーツを説明します。
  • Esc：現在のパーツの選択を解除します。
  • H：ヘルプを表示します。

モデルコレクションを探索する

WonderSnapには、実際の計測値を基に作成した33種類の手続き型モデルが、6つのグループに分けて収録されています。

  • 驚異：エッフェル塔、ギザの大ピラミッド、タージ・マハル、ビッグ・ベン、シドニー・オペラハウスなど、11のランドマーク。
  • 解剖学：脳、鼓動する心臓、呼吸する肺、骨格、層構造の人体など、10種類のモデル。
  • 生物学：ほどくことができるDNA二重らせんと動物細胞。
  • エンジン：直列4気筒、スーパーチャージャー付きHEMI V8、ターボファンジェット、9気筒星型エンジン。
  • 乗り物：スポーツカー、オートバイ、旅客機、段階分離に対応したサターンV。
  • 機械：機械式腕時計と、セル、バスバー、冷却機構、バッテリーマネジメントシステムを備えたEVバッテリーパック。

教育機能を使う

ラベル付きパーツを確認する

コンポーネントを指すかクリックして選択します。選択したパーツが光り、その役割をカードで説明します。Lでラベルを有効にすると、名称と各パーツを結ぶ引き出し線が表示されます。

クイズを始める

Qを押してクイズモードに入ります。WonderSnapは検索：海馬などの問題を表示します。指定されたコンポーネントを指すかクリックしてください。クイズは5問で構成され、スコアが表示されます。

音声でシーンを操作する

Mを押すと、音声コマンドと読み上げ機能を利用できます。対応例には、show me the heart、open it up、where is the right atrium、zoom in、quizがあります。音声合成はChromeとEdgeで動作確認されています。

断面を作成する

Xを押して断面表示を有効にします。切断面は手の動きに追従し、光る断面を表示します。ジェスチャー入力を使わない場合は、,と.で切断面を少しずつ移動できます。

結果を録画する

Kを押してシーンを録画し、WebM動画として保存します。

URLオプションでWonderSnapを設定する

クエリ文字列のオプションを使うと、ソースファイルを編集せずに起動時の動作を変更し、レンダリングを調整できます。

  • ?n=250000：パーティクル数を設定します。
  • ?model=12：指定したモデル番号で開始します。
  • ?autostart=camera：開始画面を省略し、カメラモードを要求します。
  • ?autostart=nocamera：開始画面を省略し、カメラなしで実行します。
  • ?trails=0：パーティクルの軌跡を無効にします。
  • ?dpr=1：デバイスピクセル比を1に固定します。低速なGPUで役立つ場合があります。

オプションは組み合わせて使用できます。たとえば、次のアドレスはカメラなし、パーティクル数100,000、デバイスピクセル比1、軌跡無効で起動します。

http://localhost:5173/?autostart=nocamera&n=100000&dpr=1&trails=0

高度なヒント

低速なハードウェアでパフォーマンスを改善する

パーティクル数とデバイスピクセル比は、レンダリング負荷に直接影響します。まずはREADME推奨の低フレームレート設定から始めてください。

http://localhost:5173/?n=100000&dpr=1

必要に応じてtrails=0も追加し、パーティクルの軌跡を無効にします。

決定論的な起動リンクを使う

デモや再現可能なテストでは、modelとautostartモードを組み合わせます。これにより、毎回開始画面やモデル一覧を手動で移動する必要がなくなります。

アプリケーションの構成を理解する

メインのレンダリングループ、ピッキング、ズーム、分解表示、ラベル、クイズ、断面表示、デモの動作はsrc/app.jsにあります。WebカメラとMediaPipeの統合はsrc/hands.jsに、音声操作、読み上げ、録画機能はsrc/features.jsに実装されています。

src/gl/ディレクトリにはWebGL2シェーダーとトランスフォームフィードバックレンダラーがあります。ジェスチャーロジック、ステートマシン、コントローラー、パーティクル物理のCPU版はsrc/logic/にあります。手続き型ジオメトリのユーティリティはsrc/lib/に、モデル定義はsrc/models/にまとめられています。

テストスイートを実行する

WonderSnapには、Playwrightで構築された36件のエンドツーエンドテストおよびユニットテストが含まれています。テストでは、合成した手のデータと決定論的な時計を使って実際のアプリケーションを操作します。

PlaywrightのChromiumブラウザを一度インストールします。

npx playwright install chromium

続いてテストを実行します。

npm test

このスイートでは、ジェスチャーの一連の流れ、すべてのモデル、分解図、キーボードとホイールによる操作、レスポンシブレイアウト、心拍と呼吸のアニメーション、両手ズーム、パーツ選択、ピンチ操作、クイズ、音声コマンド、カットアウェイモード、録画、カメラのフォールバック動作、ポーズ分類器、状態遷移、プロシージャルモデルの妥当性、GPU物理演算を網羅しています。GPUシェーダーはCPU版とも比較され、すべてのモードでおよそ1e-7の精度に収まることを確認します。

トラブルシューティング

  • カメラが起動しない: index.htmlを直接開くのではなく、http://localhost:5173からアプリケーションを開き、求められたらカメラのアクセスを許可してください。
  • ハンドトラッキングが読み込まれない: npm installを実行してください。トラッキングランタイムはnode_modulesから提供されます。
  • フレームレートが低い: http://localhost:5173/?n=100000&dpr=1を試してください。
  • ポート5173が使用中: npm start -- 8080を実行し、http://localhost:8080を開いてください。

まとめ

WonderSnapは、デバイス上のハンドトラッキング、カスタムジェスチャー分類器、プロシージャルモデリング、GPUパーティクル物理演算を組み合わせることで、ブラウザーだけでインタラクティブな教育体験を実現できることを示しています。標準的なローカルセットアップから始め、スナップ、握りこぶし、開いた手、指差し、ピンチの操作を覚えたら、URLによる調整、音声操作、クイズ、断面表示、録画、自動テストスイートを試してみてください。