hand-tracking

手のトラッキング

目的

このスキルは、コンピュータービジョンアルゴリズムを使用して AR/VR 環境で手のジェスチャーをリアルタイムに検出・追跡し、仮想的な操作やジェスチャーベースのコントロールなどのアプリケーションにシームレスに統合できるようにします。

使用する場面

ゲームのジェスチャー操作インターフェース、リモートコラボレーションツール、VR ヘッドセットのアクセシビリティ機能など、手のジェスチャー入力が必要な AR/VR アプリの構築時にこのスキルを使用してください。リアルタイムのオブジェクト操作など、低遅延のトラッキングが不可欠なライブカメラ映像を扱う場面で適用してください。

主な機能

• MediaPipe Hands などの事前学習済みモデルを使用し、片手あたり最大 21 個のキーポイントで手のポーズをリアルタイムに推定します。
• ピンチ、手を振る動作、スワイプなどの一般的な動作を、精度を調整できるしきい値で認識します。
• ウェブカメラのストリームや AR/VR デバイスのカメラなど、複数の入力ソースに対応し、最大 60 FPS のフレームレートで動作します。
• 手のランドマークを表す JSON や、検出したジェスチャーのイベントトリガーなどの出力形式に対応します。
• 設定ファイルでモデルをカスタマイズできます。たとえば、最小信頼度（検出の場合は 0.5 など）を指定できます。

使用パターン

入力ソースと認証を設定してから、必ずこのスキルを初期化してください。まず、API アクセス用の環境変数を設定します。例：export OPENCLAW_API_KEY=your_api_key。CLI を使用する場合は、カメラデバイスから入力をパイプします。コードでは、スキルをモジュールとしてインポートし、ループ内でトラッキング関数を呼び出します。メインスレッドをブロックしないよう、非同期処理を適切に扱ってください。AR/VR に統合する場合は、描画ループと組み合わせて、手の位置に基づいて仮想オブジェクトを更新します。

主なコマンド/API

迅速なプロトタイピングには CLI ツールを、プログラムからのアクセスには REST API を使用します。認証には $OPENCLAW_API_KEY 環境変数が必要です。

• CLI コマンド：

  • トラッキングを実行：claw hand-track --input /dev/video0 --model mediapipe --confidence 0.7
    • フラグ：--input はカメラデバイス（例：/dev/video0）を指定し、--model はトラッキングモデル（例：mediapipe または custom）を選択し、--confidence は検出のしきい値を設定します。
  • 出力を保存：claw hand-track --input file.mp4 --output results.json --gestures pinch,wave
    • 動画ファイルを処理し、検出したジェスチャーを JSON ファイルに出力します。

• API エンドポイント：

  • /api/hand-track に POST し、{ "input": "camera", "model": "mediapipe", "confidence": 0.7 } という JSON ペイロードを送信してトラッキングを開始します。
    • 応答例：{ "hand_landmarks": [ [x1,y1,z1], ... ], "gestures": ["pinch"] }。
  • GET /api/hand-track/status：現在のセッション状態を確認します。ヘッダー Authorization: Bearer $OPENCLAW_API_KEY が必要です。

• コードスニペット：

  • Python（OpenClaw SDK を使用）：

    import openclaw
    client = openclaw.Client(api_key=os.environ['OPENCLAW_API_KEY'])
    results = client.hand_track(input_source='camera', model='mediapipe')
    print(results['gestures'])
    

  • JavaScript（Node.js）：

    const openclaw = require('openclaw');
    const client = new openclaw.Client(process.env.OPENCLAW_API_KEY);
    client.handTrack({ input: 'camera', confidence: 0.7 }).then(data => console.log(data.hand_landmarks));
    

• 設定形式：

  • 設定には JSON を使用します：{ "model": "mediapipe", "gestures": ["pinch", "wave"], "confidence": 0.7 }。
  • CLI から読み込みます：claw hand-track --config path/to/config.json。

統合に関する注意事項

このスキルを AR/VR フレームワークのイベントループでラップして統合します。Unity では、OpenClaw Unity plugin を使用して手のイベントをサブスクライブします。Web アプリでは、カメラストリームに WebRTC を組み合わせます。入力ソースが互換性を持つことを必ず検証してください（例：カメラ解像度が少なくとも 640x480 であることを確認します）。カスタムモデルを使用する場合は、マルチパートフォームを使って API エンドポイント /api/hand-track/models からアップロードします。本番環境で使用する前にモックデータでテストし、さまざまな照明条件に対応できるようにしてください。

エラー処理

API キーが無効、カメラにアクセスできないなど、一般的なエラーを確認してください。コードスニペットでは try-catch ブロックを使用してください。CLI では、エラー時に終了コードが返されます（認証失敗の場合は 1 など）。具体的なケース：

• $OPENCLAW_API_KEY が設定されていない場合、API は 401 Unauthorized を返します。実行前に export OPENCLAW_API_KEY=your_key で設定してください。
• 入力エラー（利用できないカメラなど）が発生した場合は、InputNotFoundError などの例外を捕捉し、デフォルトのソースにフォールバックしてください。
• 最小しきい値を設定して低信頼度の検出を処理し、警告をログに記録してください。コード例：if results['confidence'] < 0.5: raise ValueError("Low confidence detection")。
• API 呼び出しでは、指数バックオフを使用して一時的なエラー（ネットワークの問題など）を再試行してください。

具体的な使用例

1. 例 1：AR アプリでのリアルタイムジェスチャー制御

   • シナリオ：手のジェスチャーで仮想オブジェクトを動かす AR アプリを構築します。
   • 手順：OPENCLAW_API_KEY をエクスポートし、claw hand-track --input camera --gestures pinch を実行してから、Python で次のコードを実行します。

     import openclaw
     client = openclaw.Client(os.environ['OPENCLAW_API_KEY'])
     while True: results = client.hand_track(); if 'pinch' in results['gestures']: move_object(results['hand_landmarks'])
     

     • これにより、つまむ動作を検出し、オブジェクトの位置をリアルタイムで更新します。

2. 例 2：ジェスチャー検出のための動画分析

   • シナリオ：録画済みの動画を分析し、トレーニングデータ用に手を振る動作を検出します。
   • 手順：CLI を使用します：claw hand-track --input video/sample.mp4 --output gestures.log --gestures wave。
   • コードでは、{ "input": "file.mp4", "gestures": ["wave"] } を指定して /api/hand-track に POST し、レスポンスを処理して、検出された手を振る動作のタイムスタンプを記録します。
     • コードスニペットの例：

       fetch('/api/hand-track', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.OPENCLAW_API_KEY}` }, body: JSON.stringify({ input: 'file.mp4' }) })
         .then(res => res.json()).then(data => console.log(data.gestures));
       

グラフの関係

• 関連項目：ar-vr（クラスター）、gesture-detection（タグ）、camera-access（入力処理用スキル）。
• 依存関係：computer-vision（コア技術）。API キーによる認証が必要です。
• 接続先：object-tracking（全身トラッキングへの拡張用）。rendering-engine（AR/VR の可視化用）と統合します。