Fix portable paths, optional dependencies and project documentation

This commit is contained in:
2026-10-27 15:06:02 +08:00
parent aed6e20a90
commit da6e9b8599
6 changed files with 62 additions and 67 deletions
+4
View File
@@ -4,3 +4,7 @@ __pycache__/
MUJOCO_LOG.TXT
.DS_Store
release/
.venv/
external/
__pycache__/
+21 -60
View File
@@ -1,77 +1,38 @@
# 双臂操作沙盒(浏览器 WASM 版)
# 双臂操作沙盒
从 `~/mujoco-web-spike` 抽出来的**自包含**子集:只含 `manip.html` 跑起来需要的文件。
物理引擎是 MuJoCo 的 WASM 构建,全部在浏览器里运行,服务器只负责发静态文件。
版本快照:2026-08-31 最后一次改动(自动抓取规划 `autograsp.js` 落地那一版)。
在浏览器中运行 MuJoCo WASM 双臂抓取仿真,支持物体拖动、可达性判断、末端手动控制、自动抓取与放置记录。
## 启动
```bash
tar xzf wasm-bimanual-grasp-20260901.tar.gz
cd wasm-bimanual-grasp-20260901
python3 serve.py 8000 # 或 ./start.sh 8000
```
克隆仓库后,在仓库目录运行:
然后用 **Chrome / Edge** 打开:
~~~bash
python3 serve.py 8000
# 或 bash start.sh 8000
~~~
| 场景 | 地址 |
|---|---|
| 默认:桌面上并排两台 SO-101(5 自由度臂 + 二指夹爪) | http://127.0.0.1:8000/manip.html |
| P7 双臂工作站,末端换成 SO-101 夹爪(7 自由度臂) | http://127.0.0.1:8000/manip.html?scene=p7_bimanual |
| --- | --- |
| 双 SO-101 | http://127.0.0.1:8000/manip.html |
| P7 双臂与 SO-101 夹爪 | http://127.0.0.1:8000/manip.html?scene=p7_bimanual |
首屏会依次显示「载入 MuJoCo WASM → 下载场景 → 编译 MJCF」,编译要几秒(网格已内联,
so101_pair 1.8 MB / p7_bimanual 5.3 MB)。
需要 Python 3、桌面 Chrome/Edge 和可访问 jsDelivr 的网络。服务器仅使用 Python 标准库。浏览器依赖固定为 three.js 0.170.0、MuJoCo WASM 3.12.0。
### 环境要求
serve.py 提供 SharedArrayBuffer 所需的 COOP/COEP 响应头,不能直接替换为普通 python -m http.server。
- **Python 3**(只用标准库 `http.server`,不需要 venv、不需要 pip 装任何东西)
- **能上网**:three.js 0.170.0 和 `@mujoco/mujoco` WASM 都从 jsDelivr CDN 拉,断网会白屏
- **桌面版 Chrome / Edge**:页面用到 SharedArrayBuffer(多线程 WASM),
`serve.py` 已经发好 `Cross-Origin-Opener-Policy` / `Cross-Origin-Embedder-Policy` 两个头
## 操作
### 为什么不能直接 `python3 -m http.server`
- 拖动物体后,查看选臂、下爪方向与 IK 判定。
- 自动抓取依次执行接近、预收爪口、下探、合爪与抬升,可随时中止。
- 手动模式支持末端 XYZ 移动、朝向约束和夹爪开合。
- 物体面板支持位置与重量调整;抓放记录显示抓取、放置和掉落结果。
可以起来,但页面会**卡在「初始化 MuJoCo…」不报错也不动**——
`@mujoco/mujoco` 是 pthread 构建,浏览器只在"跨源隔离"页面里放开 SharedArrayBuffer,
而 `http.server` 不发那两个头。`serve.py` 就是 `http.server` + 这两个头 + `Cache-Control: no-store`
(ES 模块缓存极死,改了 `src/*.js` 普通刷新照样跑旧代码,所以开发期一律不缓存)。
## 验证与限制
## 页面怎么用
- **拖动物体**(鼠标直接拖桌上的易拉罐/瓶子/罐子/玩具琴/玩偶)→ 右侧实时出**判定卡**:
自动选哪只臂、下爪方向罗盘、左右两臂 IK 残差并排;两臂都够不着会明确给出「不可抓」
- **自动抓取** 按钮:按判定结果执行 抵近 → 预收爪口 → 下探 → 合爪 → 抬升;**中止** 随时停
- **手动模式**:选 左臂/右臂 → `X± Y± Z±` 步进末端 → 朝向约束(朝下/朝前/不约束)→ 张开/夹紧
- 物体面板可改**位置和重量**,点 **应用** 生效(运行时改 `body_mass`,不重编译)
- **抓放记录**:物体离抓取点 < 9 cm 且高于原位 5 cm 并保持 0.5 s = 抓取成功;
松手后静止落在台面 = 放置成功;掉到台下 = 失败
## 已知状态(08-31 实测)
- 判定侧 6/6 准确(含正确拒绝够不着的情况)
- 执行侧 **3/5**:立着的易拉罐、罐子、玩偶稳定成功;**躺倒的瓶子和玩具琴还抓不住**。
根因是二指爪全开时爪尖比爪中点低 2.6 cm,下探先顶到桌面;已加「按物体宽度预收爪口」
但仍不够,尝试过的三种夹持点选择策略都没救回来,细节见 `src/autograsp.js` 顶部注释
- **切到别的标签页仿真会暂停**(浏览器对后台标签的 rAF 节流),抓取过程中别切走
- `@mujoco/mujoco` 走的是 CDN 上的 `+esm` 最新版(打包时 jsDelivr latest = 3.12.0),
没有钉版本;如果哪天 CDN 升级后页面报 `xxx is not a function`,先把 `manip.html` 里的
`@mujoco/mujoco/+esm` 改成 `@mujoco/mujoco@3.12.0/+esm` 试
历史场景检查中,可达性判定 6/6,抓取执行 3/5;立放易拉罐、罐子、玩偶成功,躺倒瓶子和玩具琴未成功。该记录不表示任意物体的成功率。浏览器后台标签会暂停或降低仿真刷新,执行中保持页面前台。
## 文件
```
manip.html 页面 + 启动编排(渲染、UI、事件)
serve.py 静态服务器(COOP/COEP + no-store)
start.sh python3 serve.py 的包装,顺带打印地址
src/manip.js ArmController(阻尼最小二乘 IK、零空间次要目标)、GraspMonitor(抓放判定)
src/autograsp.js GraspPlanner:拖动后实时判定选臂/下爪方向,自动抓取状态机
src/scene-bridge.js MuJoCo mjModel/mjData → three.js 网格与每帧位姿
src/math.js 旋转矩阵 → 四元数
scenes/so101_pair/ 默认场景:model.xml(自包含 MJCF)+ meta.json(臂/爪/物体索引)
scenes/p7_bimanual/ P7 双臂场景,同上
tools/export_manip_scene.py ★ 仅供参考:生成上面两个场景的脚本,
依赖 ~/unitree_rl_mjlab/.venv(mujoco、numpy、tyro)+
linker-sim 资产库 + SO-101 MJCF,跑页面不需要它
```
manip.html 为页面入口,src/ 为 IK、自动抓取和渲染逻辑,scenes/ 为可直接加载的场景。
完整项目(其它页面 arm/sort/policy/urdf 等)仍在 `~/mujoco-web-spike`,本包只是双臂抓取这一条线。
重新生成场景需要外部模型及额外 Python 依赖,见 [场景导出](docs/EXPORT.md)。
+17
View File
@@ -0,0 +1,17 @@
# 重新导出场景
现有浏览器场景可直接运行,不需要 Python 仿真包。重新生成场景时:
~~~bash
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-export.txt
.venv/bin/python tools/export_manip_scene.py --help
~~~
用 --objects-root 指定 DexGraspBench example_object 目录,用 --so101-xml 指定带相邻 assets 的 SO-101 MJCF。P7 模式还需要 --workstation-root 指向 linker-robot-assets 的 workstations 目录。默认分别为 external/example_object、external/so101/so101.xml、external/workstations。
~~~bash
.venv/bin/python tools/export_manip_scene.py --rig so101_pair --name so101_pair --objects-root external/example_object --so101-xml external/so101/so101.xml
~~~
外部资产需从对应项目取得。导出会更新 scenes 下的目标场景;没有这些输入时使用仓库中的已导出场景即可。
+1 -1
View File
@@ -362,7 +362,7 @@ const $$ = (s) => document.querySelectorAll(s);
const SCENE = new URLSearchParams(location.search).get('scene') || 'so101_pair';
$('boot-msg').textContent = '载入 MuJoCo WASM…';
const loadMujoco = (await import('https://cdn.jsdelivr.net/npm/@mujoco/mujoco/+esm')).default;
const loadMujoco = (await import('https://cdn.jsdelivr.net/npm/@mujoco/mujoco@3.12.0/+esm')).default;
const mujoco = await loadMujoco();
$('boot-msg').textContent = '下载场景…';
+4
View File
@@ -0,0 +1,4 @@
mujoco==3.13.0
numpy==2.5.3
scipy==1.18.1
tyro==1.0.16
+15 -6
View File
@@ -1,6 +1,6 @@
"""把双臂工作站 + 操作台 + 测试物体导出成浏览器能直接跑的自包含 MJCF。
~/unitree_rl_mjlab/.venv/bin/python tools/export_manip_scene.py
.venv/bin/python tools/export_manip_scene.py
产出 scenes/<name>/:
model.xml 自包含 MJCF(网格内联 + 视觉网格抽稀,不依赖任何外部文件)
@@ -25,12 +25,14 @@ import numpy as np
import tyro
HERE = Path(__file__).resolve().parent.parent
WS_ROOT = (Path.home() / "linker-sim/packages/linker-robot-assets/src"
/ "linker_robot_assets/assets/workstations")
WS_ROOT = HERE / "external/workstations"
@dataclass
class Cfg:
workstation_root: Path = HERE / "external/workstations"
objects_root: Path = HERE / "external/example_object"
so101_xml: Path = HERE / "external/so101/so101.xml"
workstation: str = "p7_i1_l6_bimanual"
"""linker-robot-assets 里的工作站名。"""
name: str = "p7_bimanual"
@@ -157,7 +159,7 @@ def inline_meshes(spec: mujoco.MjSpec, m: mujoco.MjModel, cells: int) -> None:
# DexGraspBench example 数据集里的五个物体(灵巧手抓取那套方案用的就是这五个)。
# 目录名很长,这里给一组短名和中文标签。
DGB_ROOT = Path.home() / "DexGraspBench/assets/example_object"
DGB_ROOT = HERE / "external/example_object"
OBJECTS = [
# 短名, 中文, 目录, 抓握截面 m, 质量 kg, rgba
# 抓握截面按手来定:L6 手张开 13.4cm、**合拢只剩 4cm**,截面超过 4~5cm 就夹不住
@@ -277,8 +279,7 @@ def add_scene(spec: mujoco.MjSpec, cfg: Cfg):
# ---------------------------------------------------------------- 换末端
SO101_XML = (Path.home() / "unitree_rl_mjlab/src/assets/robots/unitree_go2_so101"
/ "xmls/so101/so101.xml")
SO101_XML = HERE / "external/so101/so101.xml"
SO101_KP, SO101_KV, SO101_FRC = 998.22, 2.731, 2.94
@@ -492,7 +493,15 @@ def build_p7(cfg: Cfg):
def main() -> None:
global WS_ROOT, DGB_ROOT, SO101_XML
cfg = tyro.cli(Cfg)
WS_ROOT = cfg.workstation_root.expanduser().resolve()
DGB_ROOT = cfg.objects_root.expanduser().resolve()
SO101_XML = cfg.so101_xml.expanduser().resolve()
required = [DGB_ROOT, SO101_XML]
if cfg.rig == "p7": required.append(WS_ROOT / cfg.workstation / "workstation.mjcf")
for path in required:
if not path.exists(): raise FileNotFoundError(f"Missing export asset: {path}; see docs/EXPORT.md")
out = HERE / "scenes" / cfg.name
out.mkdir(parents=True, exist_ok=True)