本文档是 atom01_description 仓库的入口指南，面向初次接触本项目的开发者。我们将从宏观视角回答三个根本问题：Atom01 是什么、这个仓库提供了什么、以及它能帮助你做什么。理解这些基础后，你将能够判断本项目是否契合你的研发路径，并知道如何继续深入。

Sources: README.md

项目定位：Atom01 的数字孪生底座

atom01_description 是 Roboparty 旗下 Atom01 人形机器人 的官方描述文件仓库。它不包含控制算法，也不涉及硬件驱动，而是提供一套完整、精确且经过多生态验证的机器人运动学与动力学数字模型。简单来说，它是 Atom01 在仿真世界中的「身份证」和「骨架蓝图」。任何想要在 RViz 中可视化、在 MuJoCo 中训练强化学习策略、或在 Gazebo 中测试控制器的开发者，都需要以本仓库提供的模型文件为起点。

Sources: README.md

仓库交付物全景

本仓库采用「一模多态」的架构策略：同一台 Atom01 物理实体，被精心转换为两种行业标准格式，并辅以高质量三维网格与地形资源。下表展示了核心交付物的组成与用途：

Sources: README.md, urdf/atom01.urdf, mjcf/atom01.xml, mjcf/atom01_terrain.xml

机器人拓扑架构

Atom01 是一款具备 23 个主动自由度 + 6 自由度浮动基座 的人形机器人。其连杆与关节采用典型的人形分层布局，从基座向下延伸出双腿，向上延伸出躯干与双臂。下图展示了从 base_link 出发的主要运动学分支：

graph TD
    A[base_link<br/>浮动基座] --> B[torso_link<br/>躯干]
    A --> C[left_thigh_yaw_link<br/>左大腿偏航]
    A --> D[right_thigh_yaw_link<br/>右大腿偏航]
    
    B --> E[left_arm_pitch_link<br/>左臂俯仰]
    B --> F[right_arm_pitch_link<br/>右臂俯仰]
    
    C --> G[left_leg_chain<br/>左腿6自由度]
    D --> H[right_leg_chain<br/>右腿6自由度]
    E --> I[left_arm_chain<br/>左臂5自由度]
    F --> J[right_arm_chain<br/>右臂5自由度]
    
    style A fill:#e1f5fe
    style B fill:#e8f5e9
    style G fill:#fff3e0
    style H fill:#fff3e0
    style I fill:#fce4ec
    style J fill:#fce4ec

具体而言，腿部每侧包含 6 个旋转关节：大腿偏航（yaw）、大腿横滚（roll）、大腿俯仰（pitch）、膝盖俯仰（pitch）、脚踝俯仰（pitch）与脚踝横滚（roll）。手臂每侧包含 5 个旋转关节：肩部俯仰、肩部横滚、肩部偏航、肘部俯仰与肘部偏航。躯干与基座之间还有 1 个腰部旋转关节，用于上身姿态调节。这种布局使机器人能够完成双足行走、上肢操作以及全身协调运动。

Sources: urdf/atom01.urdf, mjcf/atom01.xml

双格式并行的核心价值

本仓库最显著的设计决策是同时维护 URDF 与 MJCF 两种模型格式。这不是简单的格式冗余，而是针对不同研发阶段的最优解：

URDF 的价值在于生态兼容性。 作为 ROS 生态的事实标准，URDF 文件可以直接被 RViz 加载进行三维可视化，也可以被 Gazebo 解析为物理仿真模型。对于从事 SLAM、导航、运动规划或 ROS 2 集成的开发者，URDF 是零摩擦的起点。文件内定义了每个连杆的质量、惯性张量、视觉网格以及简化碰撞几何（如大腿与小腿使用长方体近似，手臂关节使用圆柱近似），确保在标准物理引擎中既有良好的视觉表现，又兼顾计算效率。

MJCF 的价值在于仿真深度与训练友好性。 MuJoCo 的 MJCF 格式在 URDF 的基础上进行了显著的能力扩展。atom01.xml 不仅包含运动学树，还明确定义了 23 个力控电机执行器（ctrlrange ±200）、关节阻尼与摩擦损耗参数，以及一套完整的多模态传感器系统。传感器涵盖三类关节反馈（位置、速度、力矩）和五类 IMU 反馈（姿态四元数、位置、角速度、线速度、线加速度、磁强计），共计 78+ 路感知通道。这使得 MJCF 模型可以直接接入强化学习框架（如 mujoco_mjx 或 gymnasium），无需额外编写传感器插件。

Sources: urdf/atom01.urdf, mjcf/atom01.xml, mjcf/atom01.xml

平地与地形：两种仿真范式

仓库提供了两个 MJCF 文件，它们仅在地面定义上存在差异，其余机器人模型完全一致，这种设计便于快速切换训练场景：

对于从零开始的开发者，建议先在 atom01.xml 的平地场景中验证基本站立与行走控制，再迁移到 atom01_terrain.xml 进行地形泛化训练。

Sources: mjcf/atom01.xml, mjcf/atom01_terrain.xml

项目结构速览

下面是仓库顶层目录的直观结构，帮助你快速定位所需资源：

atom01_description/
├── meshes/                    # 24 个 STL 三维网格
│   ├── base_link.STL
│   ├── left_thigh_yaw_link.STL
│   ├── left_thigh_roll_link.STL
│   └── ...                    # 共 24 个连杆网格
├── urdf/
│   └── atom01.urdf            # ROS 标准描述文件
├── mjcf/
│   ├── atom01.xml             # MuJoCo 平地仿真模型
│   └── atom01_terrain.xml     # MuJoCo 地形仿真模型
├── terrain_assets/
│   └── terrain_hfield.png     # 地形高度场灰度图
├── atom01_urdf.png            # 模型预览图
└── README.md

Sources: README.md

推荐阅读路径

本 Wiki 按照「由浅入深、先总后分」的原则组织。如果你刚拿到本仓库，建议按以下顺序阅读：

1. 项目概述与核心价值（当前页面）—— 建立全局认知
2. 快速上手与运行 —— 在本地加载模型并看到可视化结果
3. 仓库结构与文件组织 —— 理解每个目录与文件的设计意图
4. 三维网格资源说明 —— 掌握 STL 文件与连杆的对应关系

完成「快速开始」篇后，你可以根据技术栈选择深入方向：

• ROS/Gazebo 用户：继续阅读 ROS URDF 加载与可视化 与 与 ROS 2 / Gazebo 的集成使用
• MuJoCo/强化学习用户：继续阅读 MuJoCo 仿真环境配置 与 强化学习训练集成要点
• 模型算法研究者：继续阅读 连杆与关节体系架构 与 URDF 到 MJCF 的映射与差异

总结

atom01_description 的核心价值可以概括为：一套经过精确标定、跨生态兼容、传感器完备的人形机器人数字模型。 它消除了从「有想法」到「能仿真」之间的模型准备门槛，让你可以把精力集中在控制算法、运动规划或强化学习策略本身。下一步，请前往 快速上手与运行，在五分钟内让 Atom01 出现在你的屏幕上。