mjswan – 브라우저에서 실시간 인터랙티브 MuJoCo

개요

mjswan은 완전히 웹 브라우저 내에서 MuJoCo 물리 시뮬레이션을 실행할 수 있는 Python/JavaScript 라이브러리입니다. 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