# OmniRobCtrl_Mjlab

**Repository Path**: tinymal/omni-rob-ctrl_-mjlab

## Basic Information

- **Project Name**: OmniRobCtrl_Mjlab
- **Description**: 基于Mjlab的Tinker系列机器人训练项目
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-31
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![Project banner](https://raw.githubusercontent.com/mujocolab/mjlab/main/docs/source/_static/mjlab-banner.jpg)

# mjlab

[![GitHub Actions](https://img.shields.io/github/actions/workflow/status/mujocolab/mjlab/ci.yml?branch=main)](https://github.com/mujocolab/mjlab/actions/workflows/ci.yml?query=branch%3Amain)
[![Documentation](https://github.com/mujocolab/mjlab/actions/workflows/docs.yml/badge.svg)](https://mujocolab.github.io/mjlab/)
[![License](https://img.shields.io/github/license/mujocolab/mjlab)](https://github.com/mujocolab/mjlab/blob/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/mjlab)](https://pypi.org/project/mjlab/)

mjlab 将 [Isaac Lab](https://github.com/isaac-sim/IsaacLab) 的 manager-based API 与 [MuJoCo Warp](https://github.com/google-deepmind/mujoco_warp)（[MuJoCo](https://github.com/google-deepmind/mujoco) 的 GPU 加速版本）相结合，提供可组合的环境构建模块，依赖最小化，并直接访问 MuJoCo 原生数据结构。

## 快速开始

mjlab 训练需要 NVIDIA GPU。macOS 仅支持评估。

**在线体验**（无需安装）：

```bash
uvx --from mjlab --refresh demo
```

或在 [Google Colab](https://colab.research.google.com/github/mujocolab/mjlab/blob/main/notebooks/demo.ipynb) 中运行。

**从源码安装**：

```bash
git clone https://github.com/mujocolab/mjlab.git && cd mjlab
uv run demo
```

其他安装方式（PyPI、Docker）见[安装指南](https://mujocolab.github.io/mjlab/main/source/installation.html)。

## 训练示例

### 1. 速度跟踪

训练人形机器人跟踪速度指令：

```bash
# Unitree G1
uv run train Mjlab-Velocity-Flat-Unitree-G1 --env.scene.num-envs 1024

# TinkerV32
uv run train Mjlab-Velocity-Flat-TinkerV32 --env.scene.num-envs 4096

# TinkerV3（粗糙地形）
uv run train Mjlab-Velocity-Rough-TinkerV3 --env.scene.num-envs 4096

# Microban
uv run train Mjlab-Velocity-Microban --env.scene.num-envs 2048
```

多 GPU 训练：

```bash
uv run train Mjlab-Velocity-Flat-TinkerV32 \
  --gpu-ids "[0, 1]" \
  --env.scene.num-envs 4096
```

### 2. 策略回放与可视化
tensorboard --logdir logs/rsl_rl/tinkerv21_velocity --port 6006
```bash
# 使用训练好的策略
uv run play Mjlab-Velocity-Flat-TinkerV32 \
  --checkpoint-file logs/rsl_rl/tinkerv32_velocity/<timestamp>/model_5000.pt \
  --viewer native --num-envs 10

# 零动作测试（检查 MDP）
uv run play Mjlab-Velocity-Flat-TinkerV32 --agent zero --viewer native

# 随机动作测试
uv run play Mjlab-Velocity-Flat-TinkerV32 --agent random --viewer native

# Viser 可视化
uv run play Mjlab-Velocity-Flat-TinkerV32 --agent zero --viewer viser
```

### 3. Sim2Sim / Sim2Real 部署

```bash
# Sim2Sim 仿真验证（MuJoCo 原生 viewer）
.venv/bin/python scripts/sim2sim/sim2sim_tinkerv32.py \
  --load_model logs/rsl_rl/tinkerv32_velocity/<timestamp>/exported/policy.onnx

# 无界面模式（快速验证）
.venv/bin/python scripts/sim2sim/sim2sim_tinkerv32.py \
  --load_model logs/rsl_rl/tinkerv32_velocity/<timestamp>/exported/policy.onnx \
  --headless --duration 30

# Sim2Real 真机部署
.venv/bin/python scripts/sim2sim/sim2real_tinkerv32.py \
  --load_model logs/rsl_rl/tinkerv32_velocity/<timestamp>/exported/policy.onnx \
  --duration 60
```

### 4. TensorBoard 监控

```bash
tensorboard --logdir logs/rsl_rl --port 6006 --bind_all
# 访问 http://localhost:6006
```

# WebBed

http://localhost:8080

## 支持的机器人

| 机器人 | 类型 | 任务 |
|---|---|---|
| Unitree G1 | 人形（双足） | 速度跟踪、运动模仿 |
| TinkerV32 | 小型人形（双足，0.37m） | 速度跟踪（平地/粗糙地形） |
| TinkerV3 | 小型人形（双足） | 速度跟踪（平地/粗糙地形） |
| Microban | 小型人形（双足） | 速度跟踪 |

## 核心特性

- **GPU 加速仿真**：基于 MuJoCo Warp，支持数千个并行环境
- **Manager-based API**：观测、奖励、终止、课程均可组合配置
- **域随机化**：编码器偏差、惯量、摩擦、延迟、负载等
- **Sim2Real 工具链**：ONNX 导出、sim2sim 验证、真机部署脚本
- **步态控制**：步态相位信号、步态跟踪奖励、交替步态
- **零速站立**：stand_still 惩罚、feet_contact 接触激励、pose 姿态约束

## 开发

```bash
make test          # 运行所有测试
make test-fast     # 跳过慢测试
make format        # 格式化和 lint
make docs          # 本地构建文档
uvx pre-commit install  # 安装 git hooks
```

## 文档

完整文档：**[mujocolab.github.io/mjlab](https://mujocolab.github.io/mjlab/)**

## 引用

```bibtex
@misc{zakka2026mjlablightweightframeworkgpuaccelerated,
  title={mjlab: A Lightweight Framework for GPU-Accelerated Robot Learning},
  author={Kevin Zakka and Qiayuan Liao and Brent Yi and Louis Le Lay and Koushil Sreenath and Pieter Abbeel},
  year={2026},
  eprint={2601.22074},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2601.22074},
}
```

## 许可证

[Apache License 2.0](LICENSE)

### 第三方代码

部分代码来源于外部项目：
- **`src/mjlab/utils/lab_api/`** — 来自 [NVIDIA Isaac Lab](https://github.com/isaac-sim/IsaacLab)（BSD-3-Clause）

## 致谢

感谢 Isaac Lab 团队的 API 设计和抽象层，以及 MuJoCo Warp 团队（特别是 Erik Frey 和 Taylor Howell）的支持。