90 lines
4.9 KiB
Markdown
90 lines
4.9 KiB
Markdown
# MuJoCo Web 仿真平台
|
||
|
||
以 WebAssembly 为运行核心的本地机器人仿真、控制与强化学习调试平台。浏览器直接加载 MJCF、URDF、文件夹或 ZIP 工程，使用 Three.js 渲染，并通过 MuJoCo WASM 在本地执行物理仿真。
|
||
|
||
> 本仓库是面向 Web 产品的应用仓库，不再镜像 MuJoCo 的原生 C++、Python、MJX、Unity、桌面模拟器和上游测试源码。MuJoCo 运行时由官方 npm 包 [`@mujoco/mujoco`](https://www.npmjs.com/package/@mujoco/mujoco) 提供。
|
||
|
||
## 功能概览
|
||
|
||
- MJCF/XML、URDF、文件夹和 ZIP 工程导入
|
||
- ROS `package://`、常见 URDF 兼容转换及 DAE 降级处理
|
||
- Three.js 模型、碰撞体、坐标系、关节轴、质心和惯量可视化
|
||
- 播放、暂停、单步、重置、变速、关节拖动与外力交互
|
||
- 内置平地、坡道、楼梯、随机障碍物及 9 类系统参数化地形（粗糙/波浪、金字塔阶梯、深坑、沟壑等）
|
||
- 工程地图包：静态 MJCF/OBJ/STL/高度场碰撞层、GLB 视觉层和机器人出生点
|
||
- V3 地图创作层：认证资产库支持点击添加、拖到画布落位和首个资产自动创建场景，并可通过表单与视口操纵器继续编辑、事务式应用及导出地图 ZIP
|
||
- 浏览器内 Python 控制器（Pyodide）
|
||
- ONNX 强化学习策略推理（ONNX Runtime Web）
|
||
- 内置 Go2 PPO 任务的本机 mjlab 训练桥接服务，以及 DeepSeek 驱动的奖励函数自调参、固定评估和 TensorBoard 风格独立工作台
|
||
- 响应式工作区、源码编辑、性能监控和中文诊断
|
||
|
||
## 快速开始
|
||
|
||
环境要求：Node.js 24（版本见 `.nvmrc`）和 npm 11.17；仅使用训练桥接服务或执行 Python 检查时需要 Python 3.12。
|
||
|
||
```bash
|
||
nvm use
|
||
npm install --global npm@11.17.0
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
打开 Vite 输出的地址，默认是 <http://localhost:5173/>。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
npm run dev # 启动开发服务器
|
||
npm run build # 生产构建到 web-platform-dist/
|
||
npm run preview # 预览生产构建
|
||
npm run typecheck # TypeScript 检查
|
||
npm run lint # ESLint
|
||
npm run check:format # Prettier 格式检查
|
||
npm test # Vitest 单元测试
|
||
npm run test:coverage # 核心模块覆盖率检查
|
||
npm run test:e2e # Playwright Chromium 浏览器测试
|
||
npm run test:training-server # Python 训练桥接服务测试
|
||
npm run check # 除 E2E 和 Ruff 外的完整检查
|
||
|
||
# 修改 training_server/ 时额外执行
|
||
python3 -m pip install -r requirements-dev.txt
|
||
npm run lint:python
|
||
```
|
||
|
||
## 仓库结构
|
||
|
||
```text
|
||
.
|
||
├── web_platform/ React、TypeScript、Three.js 前端与测试夹具
|
||
├── training_server/ 本机训练桥接服务及内置 Go2 PPO 训练代码/资产
|
||
├── controllers/ 可导入平台的 Python 控制器示例
|
||
├── package.json 根目录统一开发入口
|
||
└── LICENSE Apache License 2.0
|
||
```
|
||
|
||
核心前端采用“应用壳 + 业务域 + 共享组件”分层：
|
||
|
||
- `web_platform/src/app/`：工作区编排、侧栏外壳、工具栏和全局对话框
|
||
- `web_platform/src/components/ui/`：无业务依赖的共享 UI 基础组件
|
||
- `web_platform/src/project/`：工程导入、路径规范化、项目树和 MEMFS
|
||
- `web_platform/src/simulation/`：MuJoCo WASM 会话、仿真调度及执行器控制 UI
|
||
- `web_platform/src/viewer/`：Three.js 渲染、选择和物理交互
|
||
- `web_platform/src/map/`：地图加载、创作、校验及对应 UI
|
||
- `web_platform/src/controller/`：Pyodide 控制器运行时及控制面板
|
||
- `web_platform/src/rl/`：ONNX 策略运行时、任务绑定及策略面板
|
||
- `web_platform/src/training/`：本地训练服务客户端、类型及训练面板
|
||
- `web_platform/src/telemetry/`：遥测数据源、记录器、导出与数据面板
|
||
- `web_platform/src/stores/`：跨业务域的应用状态
|
||
|
||
组件和测试优先与所属业务域共置；`app/components/` 仅保留跨域编排和应用壳组件，避免业务逻辑继续集中到单一侧栏文件。
|
||
|
||
详细使用说明见 [`web_platform/README.md`](web_platform/README.md)，前端依赖边界见 [`web_platform/ARCHITECTURE.md`](web_platform/ARCHITECTURE.md)，训练服务说明见 [`training_server/README.md`](training_server/README.md)。
|
||
|
||
## 数据与安全边界
|
||
|
||
模型、资源、Python 控制器和 ONNX 策略默认只在当前浏览器会话中处理，不上传到服务器。训练桥接服务只监听本机回环地址，并仅执行服务端允许列表中的任务。启用自调参时，DeepSeek 只接收脱敏后的奖励参数、曲线摘要和评估数值；API key 仅存在训练服务环境中，不进入浏览器、URL、SQLite 或训练日志。
|
||
|
||
## 上游与许可证
|
||
|
||
本项目使用 Google DeepMind 的 MuJoCo WebAssembly npm 包，并保留 Apache License 2.0 许可证。MuJoCo 是 Google DeepMind 的开源项目；本仓库不是 Google 官方支持的产品。
|