02 · シミュレーションモデル検証（MJCF の読み込みと駆動）
前提：01 環境準備 を完了してください。本章はすべてシミュレーション検証で、ハードウェアの接続は不要です。
モデルの出所
SO-ARM101 の公開 MJCF モデル 3 種は、本プロジェクトですべて動作確認済みです：
| 略称 | ファイル | 出所 |
|---|---|---|
| 公式-新キャリブ | SO101/so101_new_calib.xml | TheRobotStudio/SO-ARM100 公式リポジトリ（本チュートリアルの比較検証はここから取得。本リポジトリに元の zip は同梱していません） |
| 公式-旧キャリブ | SO101/so101_old_calib.xml | 同リポジトリ（zip には含まれず、ダウンロードが必要） |
| ROS2 記述パッケージ | so_arm101_description/mjcf/so_arm101.xml | 本リポジトリのチュートリアル添付 SO-ARM101_ROS2.zip |
注：zip の展開フローは初期版の so101_assets.py が提供したもので、参照できる形で残しています。2026-10-16 以降、シミュレーションロボットは mujoco_menagerie の SO-ARM100 モデルに移行済みです（assets/menagerie_so_arm100/ に vendored、移行理由と要点は 07 の設計説明を参照）。
駆動とレンダリングの検証
bash
export UV_CACHE_DIR='C:\Users\admin\AppData\Local\Temp\uv-cache'
# 仓库自带、可直接运行的是 menagerie 模型（仿真机器人默认也用它）
uv run --frozen --with mujoco python examples/so101_mujoco/load_and_drive.py \
--model examples/so101_mujoco/assets/menagerie_so_arm100/so_arm100.xml \
--out-dir examples/so101_mujoco/outputs/renders/model_check| パラメータ | 説明 |
|---|---|
--model | MJCF モデルのパス。リポジトリに同梱されそのまま使えるのは examples/so101_mujoco/assets/menagerie_so_arm100/so_arm100.xml（上表の 3 つの歴史的モデルを再検証する場合は、まず「出所」列の該当リポジトリから取得し、パスを差し替えてください） |
--out-dir | 出力ディレクトリ：検証動画、静止画、構造サマリの txt はすべてここに書き出されます（デフォルト out） |
--tag | 出力ファイル名のプレフィックス。デフォルトはモデルのファイル名 |
--settle / --fps / --width / --height | 各姿勢の安定時間（秒）、動画フレームレート、レンダリング解像度；デフォルトは 25 fps、960×720 で、通常は変更不要 |
スクリプトは構造サマリ（関節／アクチュエータ／ゲイン／範囲）を出力し、「6 関節を 1 つずつスイープ + 協調サイン」の検証動画と静止画をレンダリングします。 構造サマリのサンプルは reports/ にあります（リポジトリに同梱）；比較用動画（media/）はサイズが大きいためリポジトリには含まれません——上記のコマンドでいつでも再生成できます。
3 モデルの主な差異（実測）
| 項目 | 公式-新キャリブ | 公式-旧キャリブ | ROS2 記述パッケージ |
|---|---|---|---|
| ゼロ位置の意味 | 関節ストローク中点 | 水平完全伸展位置 | ストローク中点 |
| 関節名 | shoulder_pan | 左に同じ | shoulder_pan_joint（サフィックス付き） |
| 位置ゲイン | kp=998.22, kv=2.731 | kp=17.8, kv=0 | kp=998.22 |
| グリッパ単位 | ラジアン hinge | ラジアン hinge | 0–1 正規化 |
| 自己衝突除外 | なし | なし | あり（6 ペア） |
追従誤差の実測：新キャリブと記述パッケージは静止保持誤差 0.0005 rad、旧キャリブは 0.03 rad（下垂約 1.7°、kp が 56 倍弱い）。 シミュレーションで同一ポリシーを評価しても、モデルを変えると動特性が変わります。どれで記録したかに注意してください。
必ず覚えておくべきモデル挙動
shoulder_liftの正方向は下向き：駆動トルクでは「下げ振り」に正の角度を使います。遠隔操作のマッピングやデータ換算の前に符号を確認してください。- 地面に当たれば止まる：下げ振りの限界で指先が地面に接触して止まります（スクリプトには 8cm の対地保護による自動振幅クリップを組み込み済み）。
- 公式モデルにはカメラも keyframe もありません。カメラ付きの変種
so101_new_calib_camera.xmlが存在し、将来の視覚データ録画に使えます。