gaitlab 0.1.0

Drive real robots (MuJoCo Menagerie quadrupeds & industrial arms) on CPU — robot sumo, a fighting game, and production-line demos

gaitlab — 実在ロボットを CPU で動かすサンドボックス

実在ロボット (MuJoCo Menagerie) を CPU だけ で読み込み・駆動・描画するフレームワーク。 四足歩行ロボ (Unitree Go2 等) と産業用アーム (Franka / UR5e / KUKA iiwa / Kinova) を、 同じ 1 つのエンジンで動かせます。ロボット相撲・格闘ゲーム・生産ラインのデモつき。

実機は高価で危険。でもシミュなら只。GPU も要りません。 開ループ制御まで(学習・タスク計画・把持は今後)。狙いは「生産ラインのロボを AI で動かす」土台。

ロボット相撲 (Go2 vs Go2)	産業用アームの生産ライン

---

Install (動く手順)

動作確認済み: Python 3.11.3 / mujoco 3.10.0 / numpy 2.4.4 / imageio 2.37.3 (Windows 11)。 対応: Python 3.10 – 3.12。

# 1) このリポジトリを取得
git clone https://github.com/furuse-kazufumi/gaitlab-arena
cd gaitlab-arena

# 2) 依存ごとインストール (mujoco>=3.10 / numpy / imageio / pillow)
pip install -e .

# 3) 実在ロボの 3D モデル集 (MuJoCo Menagerie, Apache-2.0) を隣に clone
#    (cwd / ホーム / リポジトリの隣 を自動探索。別の場所なら MENAGERIE_DIR で指定)
git clone https://github.com/google-deepmind/mujoco_menagerie

Windows は描画に MUJOCO_GL=glfw を付けてください (offscreen 描画。osmesa/egl は不可)。 Menagerie を別の場所に置いた場合は MENAGERIE_DIR=/path/to/mujoco_menagerie を指定します。

動かす

# ロボット相撲 (Go2 vs Go2) を GIF 化
MUJOCO_GL=glfw python scripts/sumo_match.py --a go2 --b go2 --out sumo.gif

# 産業用アームの生産ライン (4 機種) を GIF 化
MUJOCO_GL=glfw python scripts/production_line.py --arms franka ur5e iiwa14 kinova --out line.gif

# 全機種ロスター (集合写真) / 単体歩行
MUJOCO_GL=glfw python scripts/robot_roster.py --out roster.gif

# ロボット格闘ゲーム (要ディスプレイ)   W/S=前後  A/D=旋回  Space=しゃがみ  X=停止
python scripts/robot_fight.py --player go2 --ai go2
#   ↑ ヘッドレスで動作確認だけしたいとき:
MUJOCO_GL=glfw python scripts/robot_fight.py --demo --out fight.gif

# 描画なし (速い・結果だけ)
python scripts/sumo_match.py --a go2 --b go2 --headless

# 使える機体の一覧
python scripts/sumo_match.py --list

ライブラリとして

from gaitlab.arena import robots
from gaitlab.arena.build import build_arena
from gaitlab.arena.gaits import SumoDriveController
from gaitlab.arena.match import MatchEngine
from gaitlab.arena.pd_control import PDController

go2 = robots.get("go2")
_, arena = build_arena([(go2, "A_", -0.45, 0, 0), (go2, "B_", 0.45, 0, 180)], ring_radius=1.0)
eng = MatchEngine(arena, controllers={
    "A_": SumoDriveController(aggression=1.4),
    "B_": SumoDriveController(aggression=0.7),
}, pd=PDController(kp=60, kd=1.5))
print(eng.run(max_time=15))   # MatchResult(winner='A_', reason='B__ringout', ...)

---

使える機体

すべて MuJoCo Menagerie(実機メーカー監修)から。

機体	種別	メーカー	関節	現状
Unitree Go2	四足	Unitree	12 (トルク)	歩く・相撲 ◎
Unitree Go1	四足	Unitree	12 (位置)	歩く ◎
Unitree A1	四足	Unitree	12 (位置)	歩く ◎
ANYbotics ANYmal C	四足	ANYbotics	12 (位置)	歩く ○ (背高で不安定)
Boston Dynamics Spot	四足	Boston Dynamics	12 (位置)	立つ ○ / 歩行は要調整
Franka Emika Panda	アーム	Franka	7+グリッパ	作業動作 ◎
Universal Robots UR5e	アーム	UR	6	作業動作 ◎
KUKA iiwa 14	アーム	KUKA	7	作業動作 ◎
Kinova Gen3	アーム	Kinova	7	作業動作 ◎

四足は足先の動きから前進符号を自動較正して歩容を合わせ込み、アームは位置制御で駆動。 四足 (浮遊ベース・一部トルク制御) もアーム (固定ベース・位置制御) も同じ MatchEngine の上に載ります。

---

仕組み (要点)

• 合成: MjSpec.attach で N 体のロボ + 土俵/床を 1 つの MjModel へ。名前を prefix で解決。
• 制御分岐: トルク型 (Go2) は PD、位置型 (アーム等) は目標角をそのまま。PD は毎物理ステップ計算。
• 歩容符号較正: 各脚の足 Jacobian (有限差分) から前進符号を導出し、機体差 (例: ANYmal の 後脚 X 字膝) を吸収して全脚の足先を同じ方向へ。
• 勝敗判定: 場外 (ringout) / 転倒 / 時間切れは判定。土俵際で腰が沈む「腰砕け」も負けに。
• 描画: mujoco.Renderer + カメラ + imageio/pillow で最適化 GIF。
• 積分器: スティフな位置サーボ (アーム) の発散を避けるため implicitfast。

テスト: pip install pytest && MENAGERIE_DIR=/path/to/mujoco_menagerie pytest tests/(Menagerie が要）。

---

Quick start (English)

Drive real robots (MuJoCo Menagerie quadrupeds & industrial arms) on CPU only — no GPU, no physical robot needed. Tested on Python 3.11.3 (supports 3.10–3.12), mujoco 3.10.

git clone https://github.com/furuse-kazufumi/gaitlab-arena && cd gaitlab-arena
pip install -e .                                                   # mujoco>=3.10, numpy, imageio, pillow
git clone https://github.com/google-deepmind/mujoco_menagerie      # or set MENAGERIE_DIR
MUJOCO_GL=glfw python scripts/sumo_match.py --a go2 --b go2 --out sumo.gif   # 'glfw' on Windows
MUJOCO_GL=glfw python scripts/production_line.py --arms franka ur5e iiwa14 kinova --out line.gif

Open-loop control for now (learning / task planning / grasping are next). The goal: a base for driving production-line robots with AI, entirely on-prem.

---

License

Apache-2.0 (see LICENSE)。商用利用可。個別の商用ライセンス/サポートは相談可 (FullSense)。ロボットモデルは同梱しておらず、各自 MuJoCo Menagerie (Apache-2.0) を取得します。

Part of FullSense — 自宅 PC で動く、責任感のある AI エコシステム。 経緯の記事: https://qiita.com/furuse-kazufumi/items/44508c48f38a68abad35