企业官网建设流程全解析

MuJoCo Python 物理仿真实战指南：从方块落地到人体姿态的 5 分钟路径

【免费下载链接】mujocoMulti-Joint dynamics with Contact. A general purpose physics simulator.项目地址: https://gitcode.com/GitHub_Trending/mu/mujoco

MuJoCo 是一款通用物理仿真引擎，配合官方 Python 绑定，机器人碰撞、布料悬垂、人体平衡都能用几行代码模拟出来，接触力和关节动力学开箱即用。这篇指南不从手册讲起，而是直接带你跑通一次真实仿真。

一、先跑起来：2 分钟装好并落下第一个方块 ✅

官方包发布在 PyPI，wheel 里自带编译好的 MuJoCo 库，一条命令安装：

pip install mujoco

安装后验证一下：import mujoco不报错，且mujoco.MjModel.from_xml_string('<mujoco/>')能正常返回，就说明环境就绪。

接下来用一段 XML 字符串建第一个模型。先记住两个核心对象：MjModel是从 XML 编译出的静态模型，MjData是存放位置、速度等运行时状态的容器。

import mujoco xml = """ <mujoco> <worldbody> <geom name="red_box" type="box" size=".2 .2 .2" rgba="1 0 0 1"/> <geom name="green_sphere" pos=".2 .2 .2" size=".1" rgba="0 1 0 1"/> </worldbody> </mujoco> """ model = mujoco.MjModel.from_xml_string(xml) data = mujoco.MjData(model) mujoco.mj_step(model, data)

mj_step推进一步物理（默认步长 2 毫秒），上面的代码执行后红色方块和绿色小球已经受重力下落了一格。想看它们落下，打开被动查看器：

with mujoco.viewer.launch_passive(model, data) as viewer: while viewer.is_running(): mujoco.mj_step(model, data) viewer.sync()

运行后弹出窗口，两个物体弹跳、静止，你可以拖拽旋转相机，关闭窗口即结束脚本。

二、看懂 MjModel 与 MjData：蓝图与快照的关系

上一节已经用过两个核心对象，这里把心智模型说透：MjModel 是蓝图，MjData 是快照。

蓝图只写一次：几何体形状、关节结构、材质属性都在MjModel里，编译完成后固定不变。快照每步都变：MjData的qpos（位置）、qvel（速度）、ctrl（控制输入）等字段由mj_step逐次改写。

注意"改写"是原地的——Python 绑定返回的是 C 内存的直接视图，不做拷贝。好处是访问状态零额外开销；代价是，把某个字段直接append进列表记录时，存进去的其实是同一块内存的指针，仿真跑完你会发现整条记录全是最终值。解决办法放在文末速查表第 1 条。

三、三个高频操作：读状态、改参数、录视频

能跑起来之后，日常就是"看状态、调参数、出结果"的循环，下面各给一个最简做法。

按名字读状态

底层数组用整数 ID 索引，没人想手算偏移。绑定提供了命名访问，直接按 XML 里的名字查：

i = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_GEOM, "green_sphere") print(model.geom_rgba[i]) # 球的颜色 print(data.geom("green_sphere").xpos) # 当前坐标

运行后先打印出 RGBA 颜色数组，再打印三维坐标，坐标值会随仿真推进而变化。

用 MjSpec 在代码里改参数

参数经常要批量改，逐行编辑 XML 很痛苦。MjSpec是内存中可增删改的模型结构，改完调compile()重新得到MjModel：

spec = mujoco.MjSpec() body = spec.worldbody.add_body(pos=[1, 2, 3]) body.add_geom(type=mujoco.mjtGeom.mjGEOM_SPHERE, size=[0.1, 0, 0], rgba=[1, 0, 0, 1]) model = spec.compile()

编译后模型里 (1, 2, 3) 处多了一个红色小球；改完还可以用spec.encode("model.xml")把结果写回 XML 或二进制文件，方便复用。

逐帧渲染，把仿真录成视频

离屏渲染用mujoco.Renderer：每步update_scene再render()，得到 RGB 数组，攒够帧就是一段视频：

import numpy as np frames, n = [], 60 * 4 with mujoco.Renderer(model) as renderer: for i in range(n): mujoco.mj_step(model, data) renderer.update_scene(data) frames.append(renderer.render()) np.save("frames.npy", np.stack(frames))

运行完得到 60fps 约 4 秒的帧数组；要存成 mp4，安装mediapy后把帧数组交给media.write_video("out.mp4", frames, fps=60)即可。

四、从示例到你自己：换一个人体模型试试

demo 跑熟后，第一步是把示例变成你的：拿一个现成模型，改一个参数，看结果怎么变。仓库自带一批示例模型，其中人体模型很适合练手——关节、阻尼、关键帧配置完整，data.ctrl里每个执行器对应什么一目了然：

model = mujoco.MjModel.from_xml_path("model/humanoid/humanoid.xml") data = mujoco.MjData(model) mujoco.mj_resetDataKeyframe(model, data, 0)

mj_resetDataKeyframe把模型恢复到第一个关键帧（该模型里是蹲姿）。接着套用前面的被动查看器循环，把data.ctrl从零改成简单的 PD 规则，就能看到姿态跟着控制量变化。"加载 → 重置 → 控制循环 → 查看"这个模板固定下来后，换成你自己的模型，框架完全通用。

五、踩坑速查：5 个高频问题 ⚠️

• 症状：记录的轨迹全部是同一个值。→原因：xpos、qpos等是内存视图，直接 append 存的是指针。→修复：positions.append(data.body("torso").xpos.copy())，记得.copy()。
• 症状：物理循环慢，追不上真实时间。→原因：每帧从 Python 单步调用mj_step开销大。→修复：mujoco.mj_step(model, data, nstep=20)批量步进。
• 症状：无显示器的服务器上渲染崩溃或黑屏。→原因：默认走 OpenGL 窗口，没有可用显示。→修复：运行前设置环境变量MUJOCO_GL=egl（有 GPU）或osmesa（软件渲染）。
• 症状：模型姿态混乱，想回到初始状态。→原因：MjData里是上一次的残留状态。→修复：mujoco.mj_resetDataKeyframe(model, data, 0)回到关键帧。
• 症状：macOS 上launch_passive直接崩溃。→原因：该平台要求渲染在主线程。→修复：用包内自带的mjpython my_script.py运行脚本，可无缝替换python。

六、下一步去哪

• doc/python.rst：Python 绑定完整文档，查看器模式、命名访问、MjSpec 编辑的细节都在里面
• python/tutorial.ipynb：官方入门 notebook，从最简模型一直做到 LQR 平衡控制
• model/humanoid/humanoid.xml：本文用到的人体模型，关键帧和关节注释可直接对照阅读

打开 tutorial notebook 跟着把人体平衡 demo 跑一遍，你的第一个仿真项目就可以开工了。

【免费下载链接】mujocoMulti-Joint dynamics with Contact. A general purpose physics simulator.项目地址: https://gitcode.com/GitHub_Trending/mu/mujoco