SCS0009 ハンドトラッキング（公式 dora Demo）

本ページでは SCS0009 バスサーボ版の公式ハンドトラッキング経路を説明します：カメラ → MediaPipe → MuJoCo IK → AHControl（Rust）→ SCS0009。PWM 版のトラッキングは PWM ハンドトラッキング を参照してください。

以下のスクリプト 1 → 4 は Windows のワンクリックスクリプトを例にしています。スクリプトは AmazingHand-main/Demo/Windows_Deploy_Scripts/ にあり、Linux と macOS のスクリプトの場所と違いは末尾を参照してください。番号順に実行すれば完了します。

---

ハードウェアの準備

ハードウェア	要件
多指ハンド本体	右手 / 左手 / 両手
サーボドライバ基板	外部接続、USB で PC へ接続
電源	外部電源、少なくとも 5V 4A（またはドライバ基板の要件どおり 7–12V 入力）。USB 給電では不足
カメラ	PC 内蔵または USB カメラ

モデルファイルは Onshape で表示またはダウンロードできます（URDF を含む）。

多指ハンドの MuJoCo モデル

---

環境インストール（スクリプト 1）

1-Install_Env.bat をダブルクリックすると、以下が自動で行われます：

1. MSVC ビルドツール（cl.exe）の確認 —— Rust のコンパイルに必須。無い場合は Visual Studio 2022 Build Tools のインストールを促し、「C++ によるデスクトップ開発」を選択してインストールし、ターミナルを開き直します。

2. Rust のインストール（rustup + stable-msvc ツールチェーン）

3. cargo の清華（Tsinghua）ミラー設定（C:\Users\<ユーザー名>\.cargo\config.toml）で crate のダウンロードを高速化

4. uv のインストール（Python パッケージマネージャー）

5. dora-cli 0.5.0 のインストール（cargo install、初回コンパイルは約 10〜20 分かかるので気長に待ってください）

6. dora-rs pip パッケージのインストール（任意、仮想環境へインストールされます）

重要：スクリプト終了後はターミナルを閉じて開き直し、環境変数を反映させてください。ネットワークが遅い場合はインストールに時間がかかることがあるので、途中で閉じずに待ってください。

環境インストールの代替手段（スクリプトが使えない場合）

• Rust：https://www.rust-lang.org/tools/install

  • Windows では rustup-init.exe を使い、デフォルトの MSVC ツールチェーンを選択

  • 環境変数：%USERPROFILE%\.cargo\bin を PATH に追加

• uv：PowerShell で irm https://astral.sh/uv/install.ps1 | iex を実行。

  • 環境変数：%USERPROFILE%\.local\bin を PATH に追加

• dora-cli：cargo install dora-cli --version 0.5.0

cargo の清華ミラー設定（~/.cargo/config.toml）

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[registries.tuna]
index = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[http]
check-revoke = false

sparse スパースインデックス（上記）を使用し、git リポジトリのミラーは使わないでください。git 方式は初回に約 1GB のインデックスをダウンロードするため、Updating 'tuna' index で止まりやすくなります。

---

配線方法

• サーボドライバ基板の USB を PC へ接続し、外部電源を接続します（少なくとも 5V 4A、またはドライバ基板の要件どおり 7–12V）

• PC 側でポート番号を確認：デバイスマネージャー → ポート（COM と LPT）、例：COM11

---

シリアルポートの設定（スクリプト 2）

2-Setup_Serial.bat をダブルクリックします（実際の処理は 2-Setup_Serial.ps1）：

1. 「サーボドライバ基板を PC に接続してください」と表示 → Enter で検出開始

2. 検出した COM ポートを自動で一覧表示（デバイス名付き）

3. ポートが 1 つの場合は Enter で確定、複数の場合は番号を入力

4. 3 つの dataflow yml の --serialport と AHControl\src\main.rs のデフォルトポートを自動で書き込み

5. 元のファイルは自動的に .bak としてバックアップ

USB を挿し直すとポート番号が変わることがあるため、その場合はこのスクリプトを再実行してください。

---

コードのデプロイ（スクリプト 3）

3-Deploy_Demo.bat をダブルクリックすると、以下が自動で行われます：

1. dora デーモンを起動（dora up）

2. Python 3.12 の仮想環境を作成（uv venv --python 3.12）

3. 仮想環境を有効化

4. AHControl Rust ノードをビルド（cargo build --release、初回は約 10 分）

5. AHSimulation、HandTracking の依存関係を同期（uv sync）

6. mediapipe==0.10.14 を強制インストール

デプロイは 1 回だけで済みます。再実行すると仮想環境を再作成するか確認されます。

---

コードの実行（スクリプト 4）

4-Run_Demo.bat をダブルクリックすると、対話メニューが表示されます：

============================================
   请选择运行模式：
============================================
    1 - 模拟仿真（摄像头手势追踪）
    2 - 真实硬件
    q - 退出
============================================
  请输入序号 [1/2/q]:

• 1 を選択：シミュレーション環境。カメラのジェスチャーで 2 つのシミュレーションハンドを駆動します

• 2 を選択：サブメニューへ進み、右手／左手／両手を選択します

============================================
   真实硬件 - 请选择灵巧手：
============================================
    1 - 右手
    2 - 左手
    3 - 左右双手
    b - 返回上级菜单
============================================

選択すると dora build + dora run が自動実行されます。カメラウィンドウが開き、カメラに向かってジェスチャーすると多指ハンドがリアルタイムに追従します。Ctrl+C で停止し、データフローの終了後に Enter を押すとメインメニューへ戻り、別のモードを選ぶか q で終了できます。

初回実行時に Windows がカメラの権限を確認する場合があるので、「許可」をクリックしてください。

---

プロジェクトのクリーンアップ（スクリプト 0）

0-Cleanup_Project.bat をダブルクリックし、Y を入力して確定すると自動でクリーンアップします：

1. dora デーモンを停止

2. 3 つの仮想環境（.venv）を削除

3. Rust のビルド成果物（AmazingHand-main/Demo/target）を削除

4. pycache、.bak バックアップ、ログ、AmazingHand-main/Demo/out（dora のログディレクトリ）を削除

5. デフォルトポートを復元（--serialport /dev/ttyACM0）し、本機のシリアルポートの残留設定を除去

クリーンアップ後は AmazingHand-main フォルダー全体を他人へコピーでき、残留物がありません。新しいマシンでは 1 → 2 → 3 → 4 の順に実行します。

---

Linux と macOS の違い

ワンクリックスクリプトには Linux と macOS 版もあり、ディレクトリはそれぞれ AmazingHand-main/Demo/Linux_Deploy_Scripts/ と AmazingHand-main/Demo/Mac_Deploy_Scripts/ です。手順 1–4 の流れは Windows と同じで、以下ではシステムごとの違いだけを挙げます。

スクリプトの実行権限（Linux / macOS）

Windows や圧縮アーカイブからコピーすると、スクリプトの +x 実行ビットが失われます。初回実行前に次を実行してください：

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # macOS では Mac_Deploy_Scripts に変更
chmod +x *.sh

その後は ./スクリプト名 で実行します。bash スクリプト名 は使わないでください。スクリプト内の対話プロンプトがスキップされます。

Linux（Ubuntu）

• シリアルポートの権限：sudo usermod -aG dialout $USER を実行し、ログアウトして再ログインします。一時的な方法として sudo chmod 666 /dev/ttyACM* も使えます。
• デバイス名：/dev/ttyUSB*（CH340 / CP2102）または /dev/ttyACM*（オンボード USB シリアル）。
• カメラ：設定 → プライバシー → カメラでアプリのアクセスを許可します。他のプログラムがカメラを占有していないことを確認してください。
• 仮想マシン：まず USB カメラを仮想マシンへ接続します。OpenCV が can't open camera by index または select() timeout を出す場合は、仮想マシンの設定で USB コントローラーを 2.0 / 3.1 に切り替えて再起動します。必要に応じて sudo usermod -aG video $USER を実行します。
• 中国語パス：プロジェクトのパスはできるだけ英語にし、MuJoCo / MediaPipe のモデル読み込み失敗を避けてください。

macOS

• シリアルポート：/dev/cu.* を使用し、/dev/tty.* は使わないでください。ls /dev/cu.* でデバイス名を確認します。
• シリアルポートの権限：sudo chmod 666 /dev/cu.usbmodem* を実行するか、「システム設定 → プライバシーとセキュリティ → 入力監視」でターミナルを許可します。
• カメラ：初回実行時にターミナルのカメラアクセスを許可します。「システム設定 → プライバシーとセキュリティ → カメラ」で変更することもできます。
• Apple Silicon：初回の cargo build で dora の依存関係のコンパイルが遅いのは正常です。「開発元を検証できません」と表示された場合は、「プライバシーとセキュリティ」で「このまま開く」をクリックします。

手動インストール（ワンクリックスクリプトを使わない場合）

スクリプトが使えない場合は、公式 Demo に従って手動でデプロイできます：

1. コードの取得：リポジトリをクローンするか AmazingHand.zip をダウンロードし、AmazingHand-main/Demo/ へ移動します。

   

2. 環境のインストール：Rust（rustup）、uv、dora-cli。PowerShell/Bash を開き直して PATH を反映させます。インストールの詳細は上記の環境インストール（スクリプト 1）を参照してください。

3. 環境の作成と依存関係のインストール：

   uv venv --python 3.12
   # Windows: .venv\Scripts\activate
   # Linux/macOS: source .venv/bin/activate
   
   cd AHControl
   cargo build --release
   cd ..
   cd AHSimulation
   uv sync
   cd ..
   cd HandTracking
   uv sync
   cd ..

   

4. シリアルポートの設定：dataflow_tracking_real_right.yml / _left.yml / _2hands.yml の --serialport を、実際の COM ポートまたは /dev/ttyUSB0、/dev/cu.usbserial-* に変更します。

   

   

5. ビルドと実行：

   # シミュレーション
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # 実機（右手。左手／両手はファイル名を置き換え）
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # 簡単な角度の例
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. よくある問題：mediapipe は 0.10.14（Python 3.12）が必要です。dora のバージョンが合わない場合は pyproject.toml／ログに合わせてください。OpenCV が無い場合は opencv-contrib-python をインストールしてください。カメラの権限、仮想マシンの USB パススルー、中国語パスはいずれもモデルの読み込みに影響します。具体的な対処はよくある問題と注意事項を参照してください。

より詳しい公式 Demo の説明は AmazingHand-main/Demo/README.md を参照してください。各システムのワンクリックデプロイ手順は本ページへ統合済みです。

コード構成の説明

Demo ディレクトリ

AmazingHand-main/Demo/
├── AHControl/                Rust ノード：シリアルでサーボを制御、config/ にサーボ ID とオフセット
├── AHSimulation/             Python ノード：MuJoCo シミュレーションと逆運動学
├── HandTracking/             Python ノード：MediaPipe ハンドランドマーク認識
├── dataflow_*.yml            dora データフローの編成
├── Windows_Deploy_Scripts/   Windows ワンクリックデプロイスクリプト
├── Linux_Deploy_Scripts/     Linux ワンクリックデプロイスクリプト
├── Mac_Deploy_Scripts/       macOS ワンクリックデプロイスクリプト
└── docs/                     公式の多言語デプロイチュートリアル

各 dataflow の対応関係

データフローファイル	用途
dataflow_tracking_simu.yml	カメラのジェスチャートラッキング。MuJoCo のシミュレーションハンドのみを駆動
dataflow_tracking_real_right.yml	カメラのジェスチャートラッキング。実機の右手を駆動
dataflow_tracking_real_left.yml	カメラのジェスチャートラッキング。実機の左手を駆動
dataflow_tracking_real_2hands.yml	カメラのジェスチャートラッキング。左右手を同時に駆動
dataflow_angle_simu.yml	関節角度を直接与え、シミュレーションと逆運動学を検証

データフローの原理

カメラ → HandTracking（MediaPipe でジェスチャー認識）
              ↓ 手のランドマーク座標
         AHSimulation（MuJoCo シミュレーション + 逆運動学）
              ↓ 関節の目標角度
         AHControl（シリアル → サーボドライバ基板 → 多指ハンド）

ポート設定の場所

• 3 つの dataflow_tracking_real_*.yml の args: 行：--serialport COMxx

• AHControl\src\main.rs の default_value = "COMxx"（シリアルパラメータのデフォルト値）

• AHControl\config\*.toml：サーボ型番、ID、オフセット（通常は変更不要）

---

よくある問題と注意事項

1. cargo が Updating 'tuna' index で止まる

• 原因：ミラー設定が git リポジトリ方式（.../git/crates.io-index.git）で、初回に 1GB 以上のインデックスをダウンロードするため

• 解決：C:\Users\<ユーザー名>\.cargo\config.toml を sparse スパースインデックスに変更する（上記「cargo の清華ミラー設定」を参照）、または 1-Install_Env.bat を再実行する

2. mediapipe に solutions サブモジュールが無い／インストールが壊れている

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• 仮想環境を有効化した状態（Demo ディレクトリ内）で実行する必要があります

• 3-Deploy_Demo.bat がこの処理を自動でフォールバック実行します

3. dora のバージョンが合わない（message v0.8.0 vs v0.7.0）

• 症状：version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0

• 原因：dora-cli のバージョンと dora-node-api が一致していない。0.5.0 に統一する必要があります

  • 確認：dora --version が dora-cli 0.5.0、dora-message: 0.8.0 を出力するはず

  • 修正：cargo install dora-cli --version 0.5.0 --force

  • PATH に複数の dora がある場合（例：C:\Users\<ユーザー名>\.dora\bin の旧版）、.cargo\bin が先に来るようにするか、旧版を削除する

  

  

4. MuJoCo / mediapipe のモデル読み込み失敗（中国語パス）

• 症状：ParseXML: Error opening file '...\scene.xml' または Can't find file: ....tflite

• 原因：MuJoCo 3.x / mediapipe の C++ ローダーは Windows で中国語を含む絶対パスを開けません（例：D:\中文目录...）

• 本プロジェクトには修正が組み込み済みです：

  • AHSimulation\AHSimulation\mj_mink_*.py はモデル読み込み前に作業ディレクトリを切り替えます

  • HandTracking\mediapipe_patch.py は 8.3 短縮パス + 相対パスで回避します

• これらの修正コードは削除しないでください

5. カメラの権限

• 初回実行時のダイアログで「許可」を選択

• 設定 → プライバシー → カメラ → デスクトップアプリのアクセスを許可

  

  

  

6. ポート番号が毎回変わる

• USB を挿し直すと COM 番号が変わることがあるので、2-Setup_Serial.bat を再実行します

7. OpenCV が無い

python -m pip install opencv-contrib-python numpy mediapipe -i https://mirrors.aliyun.com/pypi/simple/

（HandTracking ディレクトリで、仮想環境を有効化した後に実行します）

---

関連ページ

• SCS0009 クイックスタート
• SCS0009 ウェブコントロール
• SCS0009 サーボ調整とキャリブレーション
• PWM ハンドトラッキング