本页面向初次接触 Atom01 机器人描述包的开发者，提供从环境准备、仓库获取到首次成功运行模型可视化的完整快速上手指引。Atom01 是 Roboparty 推出的双足人形机器人平台，本仓库以纯资源形式提供其 URDF 与 MuJoCo 两种格式的运动学与动力学描述，不依赖特定中间件编译，可直接用于 ROS 生态集成或独立物理仿真。阅读本页后，你将能够在 RViz 中检视三维模型外观，并在 MuJoCo 交互式视窗中观察机器人受重力影响的物理行为。

Sources: README.md

环境准备

在开始之前，请确保本地环境已安装以下工具链。若你计划将模型接入机器人软件栈，推荐安装 ROS 2 Humble 或 ROS Noetic，以便使用 robot_state_publisher 与 RViz 进行可视化；若你的目标是物理仿真或强化学习预研，则需 Python 3.8 以上版本，并通过 pip install mujoco 安装 MuJoCo 3.x 的 Python 绑定与内置查看器。Git 用于克隆仓库，如果仅需本地浏览，也可直接下载源码压缩包。

Sources: README.md

仓库获取与目录结构

通过 Git 将仓库克隆到本地工作空间，并进入项目根目录。项目根目录同时作为 URDF 与 MJCF 的基准路径，因为模型文件内部使用相对路径引用 ../meshes/ 目录下的 STL 网格，若在错误的工作目录中启动仿真，将导致网格加载失败。项目采用双格式并行的扁平化资源架构，核心资产按功能归入四个目录：urdf/ 存放 ROS 标准的机器人描述文件；mjcf/ 提供两套 MuJoCo 仿真场景定义；meshes/ 包含 24 个连杆的 STL 可视化与碰撞网格；terrain_assets/ 则存储地形仿真所需的高度场纹理。两种格式共享同一套网格资源，确保视觉与几何一致性。

atom01_description/
├── urdf/
│   └── atom01.urdf              # ROS 标准机器人描述
├── mjcf/
│   ├── atom01.xml               # 平地仿真场景
│   └── atom01_terrain.xml       # 地形仿真场景
├── meshes/                      # 24 个 STL 网格（视觉与碰撞共用）
│   ├── base_link.STL
│   ├── left_thigh_yaw_link.STL
│   └── ...
└── terrain_assets/
    └── terrain_hfield.png       # 高度场地形纹理

下图为资源架构与数据流向概览：

graph TD
    A[Atom01 描述仓库] --> B[URDF 格式]
    A --> C[MJCF 格式]
    B --> D[urdf/atom01.urdf]
    C --> E[mjcf/atom01.xml<br/>平地仿真]
    C --> F[mjcf/atom01_terrain.xml<br/>地形仿真]
    D --> G[meshes/ 24×STL]
    E --> G
    F --> G
    F --> H[terrain_assets/高度场纹理]

Sources: atom01.urdf atom01.xml atom01_terrain.xml

路径一：URDF 可视化快速体验

若你的目标是机器人系统集成或运动学验证，选择 URDF 路径最为直接。由于本仓库为纯描述包，未附带 launch 文件，需手动启动 ROS 工具链发布机器人状态，再在 RViz2 中添加 RobotModel 显示插件并订阅 /robot_description 话题。对于无 ROS 环境的用户，也可使用 check_urdf 命令验证文件语法正确性。以下命令以 ROS 2 为例：

# 终端 1：发布机器人描述
ros2 run robot_state_publisher robot_state_publisher urdf/atom01.urdf

# 终端 2：启动可视化
ros2 run rviz2 rviz2
# 在 RViz 中添加 RobotModel，将 Fixed Frame 设为 base_link

该 URDF 定义了 24 个连杆与 23 个旋转关节（revolute），涵盖左右腿六自由度链、腰关节、左右臂五自由度链以及头部基座。部分连杆的 collision 标签被注释，在深度集成时可根据需要恢复。

Sources: atom01.urdf atom01.urdf

路径二：MuJoCo 物理仿真快速体验

若你需要观察物理动力学行为或开展控制算法预研，MuJoCo 路径提供了开箱即用的交互体验。在项目根目录执行 Python 单行命令即可启动内置查看器。mjcf/atom01.xml 配置了平面地台与标准重力环境，机器人在浮动基座（free joint）支持下从 0.75 米高度开始坠落并稳定触地。如需测试非平坦地形，将路径替换为 mjcf/atom01_terrain.xml，该场景使用高度场加载 terrain_assets/terrain_hfield.png，并将初始高度提升至 2.75 米以适应地形起伏。

# 安装 MuJoCo（如未安装）
pip install mujoco

# 平地场景
python -c "import mujoco.viewer; mujoco.viewer.launch_from_path('mjcf/atom01.xml')"

# 地形场景
python -c "import mujoco.viewer; mujoco.viewer.launch_from_path('mjcf/atom01_terrain.xml')"

MJCF 模型为 23 个关节各配置了一组电机执行器，控制力矩范围为 ±200 Nm，并为每个执行器输出位置、速度、力矩三组传感数据；同时在躯干处布置了包含姿态四元数、位置、角速度、线速度、线加速度与磁力计的完整 IMU 传感器组，总计 75 组仿真传感器可直接读取。

Sources: atom01.xml atom01.xml atom01.xml atom01_terrain.xml

模型核心能力一览

两种格式针对不同生态设计，下表从结构参数与内置能力维度进行对比，帮助你根据当前阶段选择入口。

Sources: atom01.urdf atom01.xml atom01.xml

常见问题速查

首次运行时可能遇到的典型问题主要集中在路径与显示两类。若 MuJoCo 报错找不到网格文件，绝大多数情况下是因为启动命令的工作目录不是仓库根目录，导致 ../meshes/ 相对路径解析失败；若 RViz 中模型材质显示为纯白，这是因为 URDF 中 material 标签的 name 属性留空，不影响几何加载，可通过 RViz 显示设置手动调整颜色。此外，MJCF 场景中机器人从空中自由坠落属于预期行为，浮动基座与重力设置会使其自然触地并趋于稳定。

Sources: atom01.urdf atom01.xml atom01.xml

下一步阅读指引

完成首次可视化后，建议按照以下顺序深入阅读文档。如需理解项目设计哲学与核心价值，请前往 项目概述与核心价值；如需掌握每个目录与文件的详细职责，请阅读 仓库结构与文件组织；若已确定使用 ROS 路线，继续阅读 ROS URDF 加载与可视化 获取 launch 文件编写与坐标系调试技巧；若选择 MuJoCo 仿真路线，则进入 MuJoCo 仿真环境配置 以深入理解 timestep、solver 与接触参数的含义。