Mujoco_WASM/wasm/web_platform/V0.1_CAPABILITIES.md

MuJoCo Web Platform V0.1 能力总结

1. 浏览器内模型导入

支持以下模型和资源格式：

• MJCF/XML
• URDF
• ZIP 工程包
• 文件夹工程
• OBJ、STL、DAE Mesh
• PNG、JPG 等纹理资源
• MJCF include 多文件工程
• URDF package:// 资源路径

导入工程仅保存在当前浏览器会话和 WASM 文件系统中，不会修改或删除本地文件。

2. 工程资源管理

• 按真实目录层级展示工程文件。
• 目录优先并按文件名排序。
• 标记和高亮当前模型入口。
• 导入 URDF 时，只自动展开选中 URDF 所在的目录路径。
• 其他目录默认折叠，仍可手动展开。
• 支持从当前会话中移除整个工程。

3. URDF 兼容处理

提供两种加载方式：

• 转换为 MJCF（推荐）
• MuJoCo 原生 URDF

自动兼容处理包括：

• 将 package:// 地址改写为工程相对路径。
• 在浏览器内将 DAE 转换为 OBJ。
• 保留 DAE 单位、坐标轴和节点变换。
• 保留 URDF visual mesh 和 Body 层级。
• 处理 MuJoCo 不支持的重复 material。
• DAE 转换失败时提供降级几何。
• 自动添加 z=0 物理地面。
• 计算模型最低几何点并对齐到地面。

4. 固定与浮动基座

URDF 转 MJCF 时可以选择：

• 浮动基座
  • 自动添加根 freejoint。
  • 支持重力、碰撞和外力运动。
• 固定基座
  • 根 Body 与世界固连。

切换基座类型后会自动重新转换并加载模型。

5. Three.js 模型可视化

• 渲染 MuJoCo Body、Geom 和 Mesh。
• 支持 Box、Sphere、Capsule、Cylinder、Ellipsoid、Plane 和 Mesh。
• 正确解析 MuJoCo mjvGeom.dataid 的 Mesh/凸包编码。
• 支持材质颜色、透明度和基础纹理。
• 默认显示 visual 并隐藏 collision。
• 可切换显示碰撞几何。
• 自动计算相机中心和观察范围。
• 无限地面不会影响相机包围范围。
• 支持相机旋转、缩放、平移和复位。

6. XYZ 方向指示器

• 右下角提供固定的 XYZ 方向指示器。
• X、Y、Z 分别使用红、绿、蓝色。
• 指示器随相机方向实时旋转。
• 不参与模型拾取和交互。

7. 模型结构树

左侧工程文件树下方显示 MuJoCo 模型结构：

• 按 Body 父子关系组织。
• 显示每个 Body 所属的 Joint。
• 支持层级展开和折叠。
• 鼠标悬停或键盘聚焦关节时：
  • 高亮关节所属 Body。
  • 在关节锚点显示黄色标记。
  • 标记随仿真运动实时更新。

8. 仿真控制

支持：

• 播放和暂停。
• 单步运行。
• 完整重置。
• 0.25×～4× 仿真速度。
• 实时仿真时间和物理耗时。
• 主线程步进预算及追帧限制。
• 播放中重置后仍可正常再次播放和暂停。

快捷键：

• Space：播放/暂停。
• R：重置。
• 1/2/3：切换交互模式。

9. 关节控制

• 使用滑块调整旋转和滑动关节。
• 只读显示 Free、Ball 等不适合单滑块编辑的关节。
• 调整关节时自动暂停仿真。
• 支持重置所有可编辑关节。
• 重置时恢复初始位置并清零对应速度。
• 支持忽略 MuJoCo 关节限位。
• 恢复限位时自动将超限值钳制回合法范围。
• 高级模式显示原始上下限和“已忽略”状态。
• 旋转关节支持弧度制和角度制切换。
• 滑动关节保持使用米制单位。

10. Actuator 与交互工具

• 显示模型 Actuator。
• 根据 ctrlrange 提供控制滑块。
• 提供三种视口交互模式：
  • 物体选择。
  • 关节拖动。
  • 外力施加。
• 外力强度可调。
• 松开鼠标后自动清除外力。
• 显示当前选中的 Body、Geom、类型和世界位置。

11. 界面与主题

• 中文用户界面。
• 左右面板支持显示、隐藏和宽度调整。
• 支持白天与黑夜主题切换。
• 主题选择保存到浏览器本地。
• UI、视口、网格和 XYZ 指示器同步换色。
• 使用约 420 ms 的平滑主题切换动画。
• 支持系统“减少动态效果”设置。

12. 状态与诊断

实时显示：

• 仿真时间。
• FPS。
• 物理步进耗时。
• 浏览器内存使用情况。
• WASM 加载状态。
• Body、Joint、Geom、Actuator、qpos 和 qvel 数量。

错误分类包括：

• 导入失败。
• ZIP 解析失败。
• 模型编译失败。
• 渲染失败。

URDF 自动兼容处理会以中文列出具体修改内容。

13. 当前限制

• DAE 转 OBJ 主要保留几何、单位和节点变换，内嵌材质及复杂贴图不能完全保留。
• 仿真和渲染目前运行在浏览器主线程。
• 关节滑块主要面向 Hinge 和 Slide，Free、Ball Joint 暂不提供完整的多自由度编辑器。
• 导入工程不会持久化，刷新页面后需要重新导入。