本页面向已具备基础机器人学知识的中级开发者，说明如何在 MuJoCo 物理引擎中加载并运行 Atom01 双足人形机器人的仿真模型。内容涵盖 MJCF 文件结构、平地与地形两种仿真场景的差异、Python 加载流程，以及核心物理参数的含义与调整边界。阅读前建议先了解 仓库结构与文件组织 和 三维网格资源说明，以便快速定位网格与配置文件之间的引用关系。

Sources: README.md, atom01.xml

MJCF 模型架构概览

Atom01 的 MuJoCo 模型采用原生 MJCF（MuJoCo XML）格式描述，未依赖 URDF 转换，从而直接利用了 MuJoCo 的高级特性，例如隐式网格碰撞、层级化的 default 参数类以及丰富的传感器接口。整个 MJCF 文件按功能划分为六大区块：编译器配置、物理选项、可视化资产、世界刚体树、执行器定义和传感器系统。这种分层结构使得物理参数、几何外观与控制接口相互解耦，便于独立维护。

graph TD
    A[MJCF 根节点<br/>mujoco model='atom01'] --> B[compiler<br/>编译器选项]
    A --> C[option / size / visual<br/>全局物理与渲染参数]
    A --> D[default<br/>参数默认值与类]
    A --> E[asset<br/>纹理/材质/网格/高程场]
    A --> F[worldbody<br/>世界体与机器人运动链]
    A --> G[actuator<br/>23 组力矩电机]
    A --> H[sensor<br/>69 路传感信号]

    D --> D1[geom 默认碰撞属性]
    D --> D2[leg_joint_param<br/>腿部关节动力学]
    D --> D3[arm_joint_param<br/>臂部关节动力学]
    D --> D4[waist_joint_param<br/>腰部关节动力学]

    F --> F1[灯光与地面]
    F --> F2[base_link<br/>浮动基座 + IMU Site]
    F --> F3[左/右腿运动链]
    F --> F4[躯干 + 左/右臂运动链]

    H --> H1[actuatorpos / actuatorvel<br/>关节位置/速度]
    H --> H2[actuatorfrc<br/>关节力矩]
    H --> H3[framequat / framepos / gyro<br/>IMU 姿态/位置/角速度]
    H --> H4[velocimeter / accelerometer<br/>线速度/线加速度]

Sources: atom01.xml

双场景配置文件对比

仓库提供了两套功能完整且结构高度一致的 MJCF 文件，分别对应平地行走与复杂地形穿越两种研发需求。两者的机器人本体定义、执行器和传感器配置完全相同，仅在环境地面与机器人初始高度上存在差异，这种设计允许你在两种场景间无缝切换，而无需修改控制代码。

高程场的尺寸参数为 size="10.0 10.0 3.4 2.0"，表示水平范围 10 m × 10 m，最大高度 3.4 m，基础偏移 2.0 m；配合初始高度 2.75 m 可确保机器人足端不会直接插入地面以下。平地场景则采用棋盘格纹理地面，便于直观观察足端滑动与落点。

Sources: atom01.xml, atom01_terrain.xml

加载仿真模型的标准流程

以下流程适用于已安装 mujoco Python 包（≥ 3.0）的环境。整个过程无需编译 C++ 源码，也无需额外下载 MuJoCo 二进制库，因为现代 Python 绑定已内置渲染与物理引擎。

flowchart LR
    A[安装依赖<br/>pip install mujoco] --> B[克隆仓库]
    B --> C{选择场景}
    C -->|平地| D[加载 mjcf/atom01.xml]
    C -->|地形| E[加载 mjcf/atom01_terrain.xml]
    D --> F[实例化 MjModel + MjData]
    E --> F
    F --> G[启动被动 Viewer<br/>或接入 RL 训练循环]
    G --> H[调用 mj_step<br/>推进仿真]

最小可运行的 Python 示例代码如下。该脚本以被动模式启动交互式 Viewer，物理步进与渲染解耦，适合在仿真循环中插入自定义控制器：

import mujoco
import mujoco.viewer
import time

# 根据场景需要切换路径
MODEL_PATH = "mjcf/atom01.xml"          # 平地
# MODEL_PATH = "mjcf/atom01_terrain.xml"  # 地形

model = mujoco.MjModel.from_xml_path(MODEL_PATH)
data = mujoco.MjData(model)

with mujoco.viewer.launch_passive(model, data) as viewer:
    while viewer.is_running():
        # 在此处插入控制指令，例如：
        # data.ctrl[:] = policy(obs)
        
        mujoco.mj_step(model, data)
        viewer.sync()
        time.sleep(model.opt.timestep)

关键注意事项：MJCF 中网格目录以相对路径 ../meshes/ 声明，因此运行脚本的工作目录必须是仓库根目录，否则会导致网格加载失败。若需在其它目录运行，请通过 meshdir 的绝对路径或软链接修正资源定位。

Sources: atom01.xml, README.md

核心物理参数解析

理解以下参数是保障仿真稳定与控制迁移成功的先决条件。它们集中在 <compiler>、<option>、<size> 和 <default> 区块中，决定了积分精度、接触求解质量以及关节动力学特性。

在 <default> 层级中，项目定义了三类关节参数类，分别对应不同躯段的动力学特征：

踝部关节的 frictionloss 被显式提升至 0.05，用于增强站立阶段的静态稳定性，模拟真实关节减速器在低速时的粘滞阻力。armature 代表电机转子等效惯量，设置为 0.01 可在不显著增加总质量的前提下抑制高速指令下的数值振荡。

Sources: atom01.xml, atom01.xml

执行器与传感器配置

Atom01 的 MuJoCo 模型配备了 23 个力矩控制电机 和 69 路传感器，构成了完整的本体感知接口，可直接用于强化学习或模型预测控制（MPC）的状态反馈。

执行器模型

所有关节均采用 <motor> 类型执行器，表示理想力矩源，其输出被限制在 ±200 N·m 范围内。gear="1" 表明电机减速比为 1:1，力矩指令直接映射为关节力矩，不包含额外的传动模型。这种简化适用于算法验证阶段；若需模拟真实电机的电流环动态或减速器间隙，可在 执行器与控制接口 中进一步了解进阶配置。

graph LR
    subgraph 执行器层级
        M1[motor<br/>ctrlrange="-200 200"] --> J1[joint]
        M2[motor<br/>ctrlrange="-200 200"] --> J2[joint]
        M3[motor<br/>ctrlrange="-200 200"] --> J3[joint]
    end
    subgraph 传感器反馈
        J1 --> S1[actuatorpos<br/>关节位置]
        J1 --> S2[actuatorvel<br/>关节速度]
        J1 --> S3[actuatorfrc<br/>关节力矩<br/>noise=1e-3]
    end

传感器清单

传感器分为关节级和机体级两类：

所有 IMU 传感器均绑定在 base_link 上的 imu Site（尺寸 0.01 m，位于基座几何中心），该 Site 同时作为浮动基座的局部坐标参考点。cutoff 参数定义了传感器输出的低通截止频率（单位 Hz），用于抑制高频数值噪声，其中加速度计的 157 Hz 截止频率保留了冲击与足地碰撞的高频信息，而角速度的 34.9 Hz 更适合姿态估计算法。

Sources: atom01.xml

几何与碰撞默认策略

MJCF 中的 <geom> 默认属性对仿真行为有全局影响。项目将默认几何体的 condim 设为 4，表示使用摩擦锥的完整三维接触模型（法向 + 两个切向），contype="1" 与 conaffinity="0" 的组合意味着机器人连杆默认可与其他物体产生接触，但连杆之间不会发生自碰撞——这是人形机器人仿真的常见权衡，可避免膝盖弯曲时大腿与小腿因网格近似而产生虚假碰撞。若需要启用自碰撞进行精细干涉检查，请参阅 碰撞几何配置策略。

Sources: atom01.xml

常见问题排查

在首次加载或训练过程中，开发者可能遇到以下典型问题：

Sources: atom01.xml, atom01_terrain.xml

阅读延伸

完成 MuJoCo 环境配置并成功运行仿真后，建议按以下路径深入：

• 若需通过 RViz 可视化同一模型的 URDF 版本，请阅读 ROS URDF 加载与可视化。
• 若需交互式调试关节范围与坐标系方向，请阅读 模型检视与关节调试。
• 若希望理解 MJCF 中每条运动链的拓扑结构与自由度总数，请阅读 运动学链路与自由度分析。
• 若计划将本模型接入强化学习框架，后续请关注 强化学习训练集成要点。