仓库结构与文件组织

本页面向初次接触 atom01_description 仓库的开发者，系统梳理仓库的顶层目录划分、各目录的职责边界，以及文件之间的引用关系。理解这些组织规则是后续加载模型、修改仿真参数或集成到其他框架的前提。

顶层目录全景

仓库采用按资源类型分层的组织策略：所有三维网格集中存放，机器人描述文件按格式（URDF / MJCF）分目录隔离，地形资源独立归档。这种布局使得不同工具链（ROS、MuJoCo）可以各取所需，避免路径混乱。

graph TD
    Root[atom01_description] --> README[README.md<br/>项目说明与预览图]
    Root --> IMG[atom01_urdf.png<br/>模型可视化快照]
    Root --> M[meshes/]
    Root --> U[urdf/]
    Root --> MJ[mjcf/]
    Root --> T[terrain_assets/]

    M --> M1[24 个 .STL 连杆网格]
    U --> U1[atom01.urdf<br/>ROS 标准描述文件]
    MJ --> MJ1[atom01.xml<br/>平地仿真场景]
    MJ --> MJ2[atom01_terrain.xml<br/>地形仿真场景]
    T --> T1[terrain_hfield.png<br/>高度场地形贴图]

    U1 -.引用.-> M1
    MJ1 -.引用.-> M1
    MJ2 -.引用.-> M1
    MJ2 -.引用.-> T1

下表汇总了各目录的核心用途与主要文件规模，便于你快速定位目标资源。

目录 / 文件	用途定位	关键文件数	目标工具链
`meshes/`	存储机器人各连杆的三维表面网格	24 个 `.STL`	RViz、MuJoCo、Gazebo
`urdf/`	ROS 生态标准机器人描述格式	1 个 `.urdf`	ROS / ROS 2、Gazebo
`mjcf/`	MuJoCo 原生仿真场景与模型定义	2 个 `.xml`	MuJoCo、MJX、Gymnasium
`terrain_assets/`	非结构化地形的高度场纹理	1 个 `.png`	MuJoCo `hfield` 地形
`README.md`	项目简介与模型预览	—	人工阅读
`atom01_urdf.png`	URDF 模型的可视化截图	—	文档、演示

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

核心目录详解

meshes — 连杆三维网格

meshes/ 目录收录了 Atom01 全身 24 个连杆的 STL 三角网格，包括躯干、左右腿（各 6 个连杆）和左右臂（各 5 个连杆）。文件名严格遵循 [side]_[part]_[dof]_link.STL 的命名模式，例如 left_thigh_pitch_link.STL 表示左腿大腿俯仰连杆。所有网格在 URDF 与 MJCF 中通过相对路径 ../meshes/ 统一引用，这种集中式存储避免了同一几何体在多个描述文件中重复定义，也便于后续用高精度网格替换低精度版本时一次性生效。

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

urdf — ROS 标准描述

urdf/atom01.urdf 是 ROS 生态系统的通用入口。文件以 <robot name="atom01urdf"> 为根节点，共定义了 24 个连杆（link）与 24 个旋转关节（joint，类型均为 revolute），总计约 750 行。每个连杆段包含惯性（inertial）、视觉（visual）和碰撞（collision）三个子块，其中视觉与碰撞几何默认指向 meshes/ 中的同名 STL 文件。值得注意的是，部分连杆的碰撞块被注释掉，这通常是出于简化物理计算或待调优的考虑，后续可在碰撞几何配置策略中深入了解。

Sources: urdf/atom01.urdf, urdf/atom01.urdf, urdf/atom01.urdf

mjcf — MuJoCo 仿真场景

mjcf/ 下包含两个高度同源但用途迥异的 XML 文件：atom01.xml 与 atom01_terrain.xml。二者共享完全相同的机器人本体定义、关节参数、执行器配置和视觉资产，差异仅体现在地面模型与机器人初始高度上。atom01.xml 使用无限平面（geom type="plane"）作为地面，并将 base_link 置于 z=0.75 m；而 atom01_terrain.xml 引用 terrain_assets/terrain_hfield.png 构建起伏高度场（geom type="hfield"），并将初始高度提升到 z=2.75 m 以避免陷入地形。这种场景分离的设计让你无需复制整份模型即可在平地实验与地形挑战之间快速切换。

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

terrain_assets — 地形高度场

该目录仅存放一张 terrain_hfield.png 灰度图，尺寸为 200×200 像素，在 MJCF 中被映射为 10 m × 10 m 的物理高度场，最大高差约 3.4 m。MuJoCo 通过像素亮度 interpreted 为地形高度，因此更换这张图片即可在不修改 XML 的情况下生成全新地形。该资源仅在 atom01_terrain.xml 中被引用，纯平地场景可完全忽略此目录。

Sources: terrain_assets/, mjcf/atom01_terrain.xml

根目录文件

README.md 提供一句话项目定位，并内嵌了 atom01_urdf.png 预览图，方便在 GitHub 或 GitLab 上直观确认模型外观。atom01_urdf.png 本身是一张静态渲染图，不参与任何仿真或加载流程，仅作文档展示之用。

Sources: README.md

文件命名规范与依赖关系

Atom01 的文件命名体现了一套清晰的解剖学+自由度编码体系：{left|right}_{body_part}_{dof_axis}_link.STL。以腿部为例，thigh 表示大腿、knee 表示小腿、ankle 表示脚踝；yaw、roll、pitch 分别对应绕 Z、X、Y 轴的旋转自由度。这种命名使得从文件名即可反推出连杆在 kinematic chain 中的位置，极大降低了维护成本。

graph LR
    subgraph 描述层
        URDF[urdf/atom01.urdf]
        MJCF1[mjcf/atom01.xml]
        MJCF2[mjcf/atom01_terrain.xml]
    end

    subgraph 几何层
        STL[meshes/*.STL<br/>24 个连杆网格]
    end

    subgraph 环境层
        TERR[terrain_assets/terrain_hfield.png]
    end

    URDF -- "../meshes/" --> STL
    MJCF1 -- "meshdir=../meshes/" --> STL
    MJCF2 -- "meshdir=../meshes/" --> STL
    MJCF2 -- "hfield file=" --> TERR

上图展示了仓库内三类核心资源的依赖流向。任何对网格文件的修改（如修复法线、减面优化）都会同时影响 URDF 与 MJCF 两个生态的呈现效果；而地形贴图仅影响 atom01_terrain.xml，保持了改动边界的清晰性。