mjswan – 浏览器中的实时交互式 MuJoCo

这是什么

mjswan 是一个 Python/JavaScript 库，让您完全在网页浏览器中运行 MuJoCo 物理模拟。它集成了 MuJoCo‑WASM 引擎、用于神经网络策略的 ONNX 运行时，以及用于 3‑D 渲染的 Three.js，因此强化学习（RL）演示可以作为静态网页（例如 GitHub Pages）分享，无需服务器端计算。

核心功能

功能	对您的意义
实时模拟与策略控制	加载 MuJoCo 模型、附加 ONNX 策略，并在浏览器中逐帧观察智能体的动作。
交互式操作	用户可以通过鼠标、触摸或 VR 控制器对物体施力，让您实时探索“如果…会怎样”的场景。
跨平台（桌面、移动设备、WebXR）	可在普通浏览器及通过 WebXR 的 VR/AR 头戴设备上运行，并支持手部追踪。
仅客户端	所有物理、渲染和推理都在本地进行；不需要后端服务器。
适合静态网站	整个演示可编译为静态资源，非常适合 GitHub Pages 或嵌入笔记本。
mjlab‑原生	内置技能（`mjlab-to-mjswan`）可将 `mjlab` 基准套件中的任何任务转换为网页演示。
可自定义可视化	您可以插入自己的 Three.js 着色器、更改相机控制，或叠加额外的 UI 小部件。

如何开始

安装 – 通过 pip（pip install mjswan）或 npm（npm install mjswan）。
运行演示 – 克隆仓库后，安装示例额外包并使用 CLI 启动演示：
```
mjswan demo simple
```

编写您自己的应用 – 一个最小脚本如下：

import os, mujoco, mjswan
model_path = os.path.join(os.path.dirname(mujoco.__file__), "testdata", "model.xml")
spec = mujoco.MjSpec.from_file(model_path)

builder = mjswan.Builder()
builder.add_project(name="Sanity Check")\n          .add_scene(name="Test Model", spec=spec)
app = builder.build()
app.launch()   # 打开包含模拟的浏览器窗口

替换模型，并可选择附加 ONNX 策略以观察 RL 智能体的动作。

适用场景

教学与演示 – 向学生展示 RL 概念，无需他们安装繁重的原生二进制文件。
研究可复现性 – 将论文的 MuJoCo 实验发布为单一 URL，任何人都可以运行。
快速原型开发 – 迭代策略或环境调整，并立即在浏览器中查看效果。

生态系统与扩展

mjswan Cloud – 托管服务（测试版），让您上传演示并分享，无需自行构建静态网站。
mjswan_playground – 精选的现成演示集合，从简单的单摆到人形机器人运动。
mjlab‑to‑mjswan 技能 – 将 mjlab 基准套件中的任务转换为网页就绪的模拟。

文档与社区

完整文档：https://mjswan.readthedocs.io
演示网站：https://ttktjmt.github.io/mjswan/
CI 徽章显示项目已积极测试（GitHub Actions、PyTest、ReadTheDocs）。

许可证

Apache‑2.0 – 您可以自由使用、修改和重新分发代码，但需保留署名声明。

要点总结： 如果您需要一种轻量级方式在浏览器中展示基于 MuJoCo 的 RL 环境——无论是教学、分享研究演示，还是构建交互式网页应用——mjswan 提供了一个现成的技术栈，处理物理、推理和 3‑D 渲染，且无需任何服务器组件。

ttktjmt/mjswan