MuJoCo 4.0에서 달라진 것
MuJoCo는 Multi-Joint dynamics with Contact의 줄임말로, 관절이 많은 물체가 바닥이나 다른 물체에 닿을 때 어떻게 움직이는지 계산하는 물리 엔진입니다. 구글 딥마인드가 공개 저장소로 관리하고 있고, 딥마인드의 강화학습 라이브러리 dm_control도 이 엔진 위에서 돌아갑니다. 실제 로봇을 넘어뜨리지 않고 화면 속에서 수천 번 넘어지게 해 볼 수 있어서 로봇 팔이나 걷는 로봇을 학습시킬 때 자주 쓰입니다.
11월 6일에 4.0.0이, 11월 11일에 4.0.1이 나왔습니다. 3.0 이후 처음으로 앞자리가 바뀐 판이라 바뀐 것이 많은데, 처음 설치하는 사람에게 영향이 큰 것은 세 가지입니다. 파이썬 패키지가 쪼개졌고, 기존 simulate 앱과 mujoco.viewer를 잇는 새 뷰어 MuJoCo Studio가 들어왔고, 그 Studio를 브라우저에서 띄우는 웹 뷰어가 생겼습니다.
엔진 쪽 새 기능도 있습니다. 빠르게 움직이는 물체가 한 스텝 사이에 얇은 벽을 뚫고 지나가는 문제를 막는 speculative 접촉 옵션, 관절이나 천처럼 휘는 물체가 힘을 받으면 원래 모양으로 돌아오지 않고 변형된 채로 남는 탄소성 모델이 대표적입니다. 다만 이번 글은 설치하고 첫 장면을 띄우는 데까지만 다룹니다.
4.0.1은 작은 수정판이지만 윈도우 사용자에게는 중요합니다. 4.0.0에서는 웹 뷰어가 윈도우에서 돌지 않았는데, 4.0.1부터 브라우저 쪽 파일을 운영체제와 상관없는 mujoco-studio-wasm 패키지로 따로 묶어 윈도우에서도 같은 명령으로 웹 뷰어를 띄울 수 있게 됐습니다. 4.0.0에서 생긴 희소 행렬 분해 버그 때문에 제약 조건이 성긴 일부 모델에서 가속도가 틀리게 나오던 문제도 이 판에서 고쳐졌으니, 지금 설치한다면 4.0.1 이상을 받으면 됩니다.
MuJoCo 설치 방법, pip 한 줄
공식 문서가 권하는 설치 방법은 PyPI에서 받는 것 하나입니다. pip install mujoco를 치면 MuJoCo C 라이브러리가 패키지 안에 같이 들어 있어서 따로 내려받아 경로를 잡아 줄 필요가 없습니다. 예전에 mujoco-py를 쓰던 시절처럼 라이선스 키 파일이나 별도 압축 파일을 챙기는 과정도 없습니다.
우분투 24.04(WSL), 파이썬 3.12.3 환경에서 직접 설치해 봤습니다. 이 환경에는 python3-venv 패키지가 없어 가상환경을 만들 수 없었기 때문에, 시스템 파이썬을 건드리지 않도록 --target 옵션으로 폴더 하나에 따로 받았습니다. 4코어 환경에서 설치에 154초, 받은 패키지는 모두 160MB였습니다. 4.0부터는 mujoco가 껍데기 패키지라서 실제로는 mujoco-core, mujoco-studio, mujoco-studio-wasm, glfw, PyOpenGL, numpy, websockets까지 여러 개가 함께 깔립니다.
평소 쓰는 컴퓨터라면 가상환경을 하나 만들고 그 안에서 설치하는 쪽이 낫습니다. 프로젝트마다 버전을 따로 둘 수 있고, 지울 때도 폴더 하나만 지우면 됩니다. 아래 명령은 리눅스, macOS와 윈도우 PowerShell을 나눠 적은 것입니다. 우분투에서 venv 오류가 나면 sudo apt install python3-venv로 먼저 패키지를 깔면 됩니다.
# 리눅스, macOS
python3 -m venv .venv
source .venv/bin/activate
pip install mujoco
python -c "import mujoco; print(mujoco.__version__)"
# 윈도우 PowerShell
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install mujoco근거 [2]
mujoco-core와 mujoco-studio 고르기
패키지가 나뉜 이유는 쓰는 곳이 다르기 때문입니다. 화면 없이 서버에서 강화학습만 돌릴 사람에게 3D 렌더러와 GUI는 짐이 됩니다. 그래서 4.0부터는 numpy 하나에만 기대는 최소 패키지 mujoco-core가 따로 있고, Studio 뷰어와 Filament 렌더러는 mujoco-studio에 들어갑니다. 그냥 mujoco를 설치하면 둘 다 받습니다.
옛날 방식 OpenGL 뷰어(mujoco.viewer)는 쓰고 싶은데 Studio는 필요 없다면 mujoco-core[rendering]을 설치하면 됩니다. 이 경우 glfw와 PyOpenGL만 추가로 들어옵니다. 처음 써 보는 사람이라면 고민하지 말고 mujoco를 설치하는 편이 편합니다. 아래 웹 뷰어도 mujoco-studio가 있어야 뜹니다.
| 설치 명령 | 들어오는 것 | 이럴 때 |
|---|---|---|
| pip install mujoco | core, studio, glfw, PyOpenGL | 처음 쓰거나 화면으로 봐야 할 때 |
| pip install mujoco-core | C 라이브러리와 파이썬 바인딩, numpy | 서버에서 학습만 돌릴 때 |
| pip install mujoco-core[rendering] | core와 glfw, PyOpenGL | 예전 mujoco.viewer만 쓸 때 |
| pip install mujoco-studio | Studio 뷰어, Filament 렌더러, wasm | Studio만 따로 넣을 때 |
MuJoCo 4.0 파이썬 설치 문서 기준.
첫 시뮬레이션, 상자와 공 떨어뜨리기
MuJoCo는 장면을 MJCF라는 XML 파일로 적습니다. 바닥 하나와, 1m 높이의 주황색 상자, 1.5m 높이의 파란 공을 놓은 짧은 장면을 만들었습니다. freejoint는 그 물체가 어느 방향으로든 자유롭게 움직이고 돌 수 있다는 뜻이라, 이것만 붙이면 중력을 받아 떨어집니다. 상자는 처음부터 조금 기울여 놓았습니다.
파이썬 쪽 코드는 더 짧습니다. 모델을 읽어 MjModel을 만들고, 움직이는 상태를 담는 MjData를 만든 뒤 mj_step을 반복해 부르면 한 스텝씩 시간이 흐릅니다. 한 스텝을 0.002초로 잡았으니 2초를 돌리려면 1000번 부르면 됩니다.
실행하니 1000스텝, 시뮬레이션 시간 2.0초를 계산하는 데 실제로는 0.9초가 걸렸습니다. 2초가 지난 뒤 상자 중심 높이는 0.0999m, 공은 0.0996m였는데, 상자 한 변의 절반과 공 반지름을 모두 0.1m로 잡았으니 둘 다 바닥에 내려앉아 멈췄다는 뜻입니다. 화면을 하나도 띄우지 않았기 때문에 이 정도 계산은 그래픽 카드가 없는 서버에서도 그대로 돕니다.
이 run.py는 렌더러를 하나도 쓰지 않기 때문에 앞에서 본 mujoco-core만 깔아도 그대로 돌아갑니다. 학습용 서버에는 core만 두고, 결과를 눈으로 볼 내 컴퓨터에만 mujoco 전체를 까는 식으로 나눠 쓰면 서버 쪽 설치가 가벼워집니다.
<!-- scene.xml -->
<mujoco model="drop">
<option timestep="0.002"/>
<worldbody>
<light pos="0 0 3" dir="0 0 -1"/>
<geom type="plane" size="2 2 .1"/>
<body name="box" pos="0 0 1" euler="20 30 0">
<freejoint/>
<geom type="box" size=".1 .1 .1" rgba=".9 .5 .2 1"/>
</body>
<body name="ball" pos="0.4 0 1.5">
<freejoint/>
<geom type="sphere" size=".1" rgba=".3 .7 .9 1"/>
</body>
</worldbody>
</mujoco>
# run.py
import mujoco
m = mujoco.MjModel.from_xml_path("scene.xml")
d = mujoco.MjData(m)
while d.time < 2.0:
mujoco.mj_step(m, d)
print(d.body("box").xpos[2], d.body("ball").xpos[2])근거 [2]
MuJoCo 웹 뷰어로 브라우저에서 보기
숫자만 보면 제대로 돌았는지 감이 오지 않습니다. 예전에는 화면으로 보려면 모니터가 달린 컴퓨터나 원격 데스크톱이 필요했는데, 4.0의 웹 뷰어는 시뮬레이션과 메뉴 화면을 서버에서 만들어 브라우저로 흘려보냅니다. 공식 문서 설명대로 서버 쪽에는 그래픽 카드도 디스플레이 서버도 필요 없습니다.
띄우는 방법은 mujoco-studio 명령에 장면 파일과 --gfx web을 붙이는 것입니다. 포트를 따로 주지 않으면 8080부터 비어 있는 첫 포트를 고르고, 여기서는 8093을 지정했습니다. 실행하면 접속 주소와 함께 경고가 하나 나옵니다. 인증도 암호화도 없어서 이 포트에 닿는 사람은 누구나 들어와 로그와 파일 경로를 볼 수 있다는 내용입니다. 주소 안내에도 localhost 말고 컴퓨터 이름으로 된 원격 주소가 같이 찍히니, 공용 와이파이나 클라우드 서버라면 방화벽에서 이 포트를 막아 두는 편이 안전합니다.
브라우저에서 localhost:8093을 열면 가운데에 3D 장면, 왼쪽에 Options, 오른쪽에 Inspector 창이 뜹니다. Pause를 누르고 Reset을 누르면 시간이 0.00초로 돌아가 상자와 공이 공중에 떠 있는 처음 상태가 보입니다.
# 장면 파일을 웹 뷰어로 띄우기
mujoco-studio scene.xml --gfx web --port 8093
# 같은 동작, 공식 문서 방식
python -m mujoco.studio.viewer --model=scene.xml --gfx=web
# 장면 파일을 저장할 때마다 다시 불러오기
mujoco-studio scene.xml --gfx web --hot_reload=model
# 원격 서버라면 포트를 열지 말고 SSH로 넘겨 받기
ssh -L 8093:localhost:8093 사용자@서버주소웹 뷰어 메뉴, 되감기와 단계 실행
Run을 누르면 실제 시간과 같은 속도로 장면이 움직이고, 1.47초쯤 멈춰 보면 상자와 공이 바닥에 내려앉아 있습니다. 시간 막대 아래 숫자 736은 그때까지 계산한 스텝 수입니다. Speed 칸으로 느리게 돌려 볼 수 있고, Step Fwd는 한 스텝씩 앞으로, Step Back은 한 스텝씩 뒤로 갑니다.
뒤로 가기가 되는 이유는 Studio가 지나온 상태를 기록해 두기 때문입니다. 공식 문서는 이 기능을 시뮬레이션 기록 되감기라고 부릅니다. 물체가 바닥을 뚫고 지나갔다거나 관절이 이상하게 튀었을 때 그 순간으로 돌아가 한 스텝씩 볼 수 있어서, 장면을 고칠 때 가장 손이 많이 가는 기능입니다.
오른쪽 Inspector 창에는 Noise, Joints, Controls, Sensors, Watch, State 항목이 있습니다. 모터나 센서가 있는 로봇 모델을 불러오면 여기서 관절 값을 직접 움직이거나 센서 숫자를 볼 수 있습니다. 상자와 공만 있는 이번 장면에서는 Joints 항목을 열어도 비어 있습니다. 띄울 때 --hot_reload=model 옵션을 붙이면 장면 파일을 저장할 때마다 뷰어를 끄지 않고 다시 불러오기 때문에, 편집기와 브라우저를 나란히 두고 고쳐 가며 보기에 좋습니다.
화면 맨 아래 상태 줄에는 Controlling, spectators 숫자, 초당 전송량, FPS가 나옵니다. 이번에는 60 FPS에 초당 16~19KiB 정도가 오갔습니다. 서버가 화면 영상을 통째로 보내는 대신 메뉴를 그리는 명령과 장면 정보를 보내고 실제 그림은 브라우저가 그리는 구조라 전송량이 작습니다.
근거 [3]
설치 없이 쓰는 MuJoCo Live와 기존 뷰어 차이
파이썬을 설치하기 번거롭다면 live.mujoco.org를 여는 방법도 있습니다. 브라우저 안에서 엔진이 통째로 도는 방식이라 서버가 필요 없고, xml이나 mjb, mjz 모델 파일을 화면에 끌어다 놓으면 바로 열립니다. 주소 뒤에 깃허브 저장소의 모델 경로를 붙여 다른 사람에게 장면을 공유하는 기능도 있습니다. 파이썬 코드로 장면을 움직이고 싶다면 이 글처럼 웹 뷰어를 쓰고, 남이 만든 모델을 잠깐 열어 볼 때는 Live가 빠릅니다.
데스크톱 프로그램이 편하다면 깃허브 릴리스에서 운영체제별 압축 파일을 받아 윈도우는 bin 폴더의 mujoco_studio.exe를, macOS는 MuJoCoStudio.app을 실행하면 됩니다. 파이썬 안에서 직접 창을 띄우는 기존 mujoco.viewer도 그대로 남아 있습니다. macOS에서 launch_passive로 창을 띄울 때는 python 대신 mjpython으로 스크립트를 실행해야 한다는 제약도 예전과 같습니다.
기존 뷰어와 Studio의 차이는 아래 표와 같습니다. 학습 코드에 이미 mujoco.viewer를 붙여 쓰고 있다면 당장 바꿀 필요는 없고, 새로 시작한다면 웹으로도 열리는 Studio 쪽이 할 수 있는 일이 많습니다.
| 구분 | 기존 mujoco.viewer | MuJoCo Studio |
|---|---|---|
| 화면 구성 | 고정된 패널 | 옮길 수 있는 창(Dear ImGui) |
| 렌더러 | 예전 방식 OpenGL | Filament(OpenGL, Vulkan, WebGL) |
| 브라우저 | 지원 안 함 | MuJoCo Live, 웹 뷰어 |
| 장면 수정 | 다시 불러오기만 | 파일 변화 감지, 플러그인 다시 불러오기 |
MuJoCo Studio 공식 문서의 비교표를 줄여 옮김.
3.x에서 4.0으로 올릴 때 주의할 점
이미 3.x를 쓰고 있다면 pip install -U mujoco만 치면 꼬일 수 있습니다. 4.0에서 파일 일부가 mujoco-core 쪽으로 옮겨졌는데, pip가 업그레이드하면서 옛 mujoco 패키지의 파일을 지우다 새로 옮겨 온 파일까지 지울 수 있기 때문입니다. 릴리스 노트는 먼저 지우고 다시 설치하거나, 업그레이드 뒤 세 패키지를 강제로 다시 설치하라고 안내합니다.
모델 파일 쪽에도 호환이 깨지는 변경이 있습니다. 밧줄이나 천을 만들 때 쓰던 composite 요소와 cable 플러그인이 없어졌고, 1차원 flexcomp로 옮겨야 합니다. 힘줄(tendon)이 sidesite를 감아 도는 방식도 바뀌었습니다. 오래된 로봇 모델을 그대로 불러오다 오류가 나면 이 두 가지부터 보면 됩니다.
문서를 찾을 때도 하나 기억해 둘 것이 있습니다. 패키지 분리에 맞춘 설치 문서는 4.0.0이 나온 직후에 고쳐졌기 때문에, 공식 사이트에서 stable이나 4.0.0 문서가 아니라 latest 문서를 봐야 지금 설명과 맞습니다.
# 3.x에서 올릴 때 (방법 1)
pip uninstall -y mujoco && pip install mujoco
# 이미 올렸다면 (방법 2)
pip install --force-reinstall --no-deps mujoco mujoco-core mujoco-studio
# core만 남기고 싶을 때
pip uninstall -y mujoco mujoco-studio && pip install --force-reinstall --no-deps mujoco-core