Metadata-Version: 2.4
Name: gaitlab
Version: 0.1.0
Summary: Drive real robots (MuJoCo Menagerie quadrupeds & industrial arms) on CPU — robot sumo, a fighting game, and production-line demos
Author: furuse-kazufumi
License: Apache-2.0
Project-URL: Homepage, https://github.com/furuse-kazufumi/gaitlab-arena
Project-URL: Repository, https://github.com/furuse-kazufumi/gaitlab-arena
Project-URL: Issues, https://github.com/furuse-kazufumi/gaitlab-arena/issues
Keywords: mujoco,robotics,menagerie,simulation,quadruped,manipulator,robot-arm,sumo
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: mujoco>=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: imageio>=2.30
Requires-Dist: pillow>=10.0
Dynamic: license-file

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

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

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

![全機種ロスター](assets/robot_roster.png)

| ロボット相撲 (Go2 vs Go2) | 産業用アームの生産ライン |
|---|---|
| ![sumo](assets/sumo_go2_ringout.gif) | ![production line](assets/production_line.gif) |

---

## Install (動く手順)

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

```bash
# 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` を指定します。

### 動かす

```bash
# ロボット相撲 (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
```

### ライブラリとして

```python
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](https://github.com/google-deepmind/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.

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

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