diff --git a/.gitignore b/.gitignore index 90f279a..0494cfa 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,7 @@ __pycache__/ MUJOCO_LOG.TXT .DS_Store release/ + +.venv/ +external/ +__pycache__/ diff --git a/README.md b/README.md index c386de5..fb42313 100644 --- a/README.md +++ b/README.md @@ -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)。 diff --git a/docs/EXPORT.md b/docs/EXPORT.md new file mode 100644 index 0000000..19e1a5e --- /dev/null +++ b/docs/EXPORT.md @@ -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 下的目标场景;没有这些输入时使用仓库中的已导出场景即可。 diff --git a/manip.html b/manip.html index ce505be..532e2eb 100644 --- a/manip.html +++ b/manip.html @@ -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 = '下载场景…'; diff --git a/requirements-export.txt b/requirements-export.txt new file mode 100644 index 0000000..a8c288f --- /dev/null +++ b/requirements-export.txt @@ -0,0 +1,4 @@ +mujoco==3.13.0 +numpy==2.5.3 +scipy==1.18.1 +tyro==1.0.16 diff --git a/tools/export_manip_scene.py b/tools/export_manip_scene.py index 23aaa80..005730c 100644 --- a/tools/export_manip_scene.py +++ b/tools/export_manip_scene.py @@ -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//: 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)