三维网格资源说明

本文档面向初次接触 Atom01 机器人描述包的开发者，系统说明 meshes/ 目录下全部三维网格资源的组织结构、命名规则，以及这些资源在 URDF 与 MJCF 两类模型文件中的引用方式。理解网格资源的分布逻辑，是后续进行可视化调试、碰撞检测优化和仿真环境搭建的基础。

Sources: README.md

网格资源总览

meshes/ 目录以 STL（Stereolithography）格式 存储了 Atom01 的全部 25 个连杆外观网格，总容量约数十兆字节。每个文件严格遵循 {部位}_{关节自由度}_link.STL 的命名约定，例如 left_thigh_pitch_link.STL 直观对应左腿大腿俯仰连杆。这些网格仅描述连杆的视觉外表面，不包含关节轴、电机或传感器等内部结构。在下游的 ROS / Rviz 或 MuJoCo 可视化中，它们负责呈现机器人的真实机械外形；而物理层面的碰撞检测则由独立的碰撞几何体（简化 box、cylinder 或 mesh）承担。

Sources: 目录结构

按身体部位分类

Atom01 的网格资源可按机械结构划分为四大组：基座、躯干、左腿、右腿、左臂、右臂。下表汇总了各部位的文件清单及其在 URDF 与 MJCF 中的对应关系，便于快速定位特定连杆的网格来源。

部位分组	网格文件名	对应 URDF Link	对应 MJCF Body
基座	`base_link.STL`	`base_link`	`base_link`
躯干	`torso_link.STL`	`torso_link`	`torso_link`
左腿	`left_thigh_yaw_link.STL`	`left_thigh_yaw_link`	`left_thigh_yaw_link`
左腿	`left_thigh_roll_link.STL`	`left_thigh_roll_link`	`left_thigh_roll_link`
左腿	`left_thigh_pitch_link.STL`	`left_thigh_pitch_link`	`left_thigh_pitch_link`
左腿	`left_knee_link.STL`	`left_knee_link`	`left_knee_link`
左腿	`left_ankle_pitch_link.STL`	`left_ankle_pitch_link`	`left_ankle_pitch_link`
左腿	`left_ankle_roll_link.STL`	`left_ankle_roll_link`	`left_ankle_roll_link`
右腿	`right_thigh_yaw_link.STL`	`right_thigh_yaw_link`	`right_thigh_yaw_link`
右腿	`right_thigh_roll_link.STL`	`right_thigh_roll_link`	`right_thigh_roll_link`
右腿	`right_thigh_pitch_link.STL`	`right_thigh_pitch_link`	`right_thigh_pitch_link`
右腿	`right_knee_link.STL`	`right_knee_link`	`right_knee_link`
右腿	`right_ankle_pitch_link.STL`	`right_ankle_pitch_link`	`right_ankle_pitch_link`
右腿	`right_ankle_roll_link.STL`	`right_ankle_roll_link`	`right_ankle_roll_link`
左臂	`left_arm_pitch_link.STL`	`left_arm_pitch_link`	`left_arm_pitch_link`
左臂	`left_arm_roll_link.STL`	`left_arm_roll_link`	`left_arm_roll_link`
左臂	`left_arm_yaw_link.STL`	`left_arm_yaw_link`	`left_arm_yaw_link`
左臂	`left_elbow_pitch_link.STL`	`left_elbow_pitch_link`	`left_elbow_pitch_link`
左臂	`left_elbow_yaw_link.STL`	`left_elbow_yaw_link`	`left_elbow_yaw_link`
右臂	`right_arm_pitch_link.STL`	`right_arm_pitch_link`	`right_arm_pitch_link`
右臂	`right_arm_roll_link.STL`	`right_arm_roll_link`	`right_arm_roll_link`
右臂	`right_arm_yaw_link.STL`	`right_arm_yaw_link`	`right_arm_yaw_link`
右臂	`right_elbow_pitch_link.STL`	`right_elbow_pitch_link`	`right_elbow_pitch_link`
右臂	`right_elbow_yaw_link.STL`	`right_elbow_yaw_link`	`right_elbow_yaw_link`

从命名规律可以看出，每条运动链均按照从机身向末端延伸的顺序排列：以左腿为例，依次经过大腿偏航（yaw）、大腿横滚（roll）、大腿俯仰（pitch）、膝盖（knee）、脚踝俯仰（ankle pitch）和脚踝横滚（ankle roll）。这种命名与关节自由度一一对应，极大降低了在排查可视化异常时定位文件的成本。

Sources: atom01.urdf, atom01.xml

模型文件中的引用架构

在机器人描述包中，同一套 STL 网格被两类模型文件共享，但引用机制存在差异。下面的架构图展示了网格资源与模型文件之间的依赖关系。

flowchart TB
    subgraph meshes_dir["meshes/ 目录"]
        A1[base_link.STL]
        A2[torso_link.STL]
        A3[left_*.STL × 5]
        A4[right_*.STL × 5]
        A5[left_arm_*.STL × 5]
        A6[right_arm_*.STL × 5]
    end

    subgraph urdf_file["urdf/atom01.urdf"]
        B1["&lt;visual&gt; / &lt;collision&gt;<br/>mesh filename='../meshes/xxx.STL'"]
    end

    subgraph mjcf_file["mjcf/atom01.xml"]
        C1["&lt;asset&gt; &lt;mesh file='xxx.STL' /&gt;"]
        C2["&lt;geom type='mesh' mesh='xxx' /&gt;"]
    end

    meshes_dir -->|相对路径引用| urdf_file
    meshes_dir -->|meshdir 编译器属性| mjcf_file

在 URDF 中，每个 link 的 visual 标签内通过 <mesh filename="../meshes/xxx.STL"/> 直接指定相对于 URDF 文件本身的相对路径。由于 URDF 采用声明式结构，网格加载路径与文件位置强耦合，因此若移动 urdf/ 或 meshes/ 目录层级，需同步修正路径，否则 Rviz 或 Gazebo 将无法解析模型表面。

在 MJCF 中，引用被拆分为两步：首先在 <compiler meshdir="../meshes/"/> 中统一声明网格搜索目录，随后在 <asset> 段内以 <mesh name="base_link" file="base_link.STL"/> 注册资源名称与文件名的映射关系；最终在 <worldbody> 的各 <body> 下，通过 <geom type="mesh" mesh="base_link"/> 按名称调用。这种间接引用方式使 MuJoCo 的编译器可以在加载阶段集中解析所有网格，并在后续几何体定义中复用同一资产，避免重复书写路径。

Sources: atom01.urdf, atom01.xml

视觉几何与碰撞几何的分离策略

初学者常有的误区是认为 meshes/ 下的精细 STL 同时决定了机器人在仿真中的碰撞边界。实际上，视觉网格（visual geometry）与碰撞几何（collision geometry）是两个独立的概念。在 Atom01 的描述包中，它们采用了明显不同的策略。

视觉层统一使用高精度 STL 网格，以还原真实机械零件的轮廓与倒角。在 URDF 中，这体现在每个 link 的 <visual> 标签内均指向对应 STL 文件；在 MJCF 中则对应 type="mesh" 的 geom。

碰撞层则根据连杆的物理特性与仿真效率需求，采用了三种策略：

继续使用 mesh：如 base_link 与两侧 ankle_roll_link，其外观网格直接充当碰撞体，适用于形状不规则且对接触精度要求较高的末端部位。
降级为简化几何体：torso_link 使用 box、left_arm_pitch_link 使用 cylinder 等。这种做法显著降低了碰撞检测的计算量，同时保留了足够的物理近似精度。
注释掉 mesh 碰撞：大量腿部连杆（如 left_thigh_yaw_link、left_thigh_roll_link 等）的 <collision> 块被显式注释，仅保留 <visual> 引用。这通常意味着开发者在迭代过程中暂时以简化体或外部方式处理碰撞，避免复杂网格导致仿真不稳定。

下表对比了典型连杆在 URDF 中的视觉与碰撞配置差异。

连杆名称	视觉几何（Visual）	碰撞几何（Collision）	策略说明
`base_link`	`base_link.STL`	`base_link.STL`	外观与碰撞共用精细网格
`left_thigh_pitch_link`	`left_thigh_pitch_link.STL`	`box` (0.08×0.1×0.22)	使用包围盒替代，提升仿真效率
`left_arm_pitch_link`	`left_arm_pitch_link.STL`	`cylinder` (r=0.03, l=0.05)	圆柱体近似手臂杆件
`torso_link`	`torso_link.STL`	`box` (0.16×0.16×0.22)	长方体包裹躯干主体
`left_thigh_yaw_link`	`left_thigh_yaw_link.STL`	已注释/无	当前未启用网格碰撞

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

颜色与外观配置

STL 格式本身不携带材质或颜色信息，因此外观配色完全由模型文件中的材质标签控制。在 URDF 中，各 link 的 <visual> 内嵌 <material> 标签，通过 RGBA 四元组定义表面颜色。观察配色分布可发现两条规律：腿部与躯干连杆多采用灰白色系（如 rgba="0.898 0.917 0.929 1"），而手臂连杆偏向淡蓝紫色系（如 rgba="0.796 0.823 0.937 1"），这种色差在可视化调试时有助于快速区分上肢与下肢。MJCF 中则直接在 <geom> 标签上通过 rgba 属性覆盖颜色，其数值与 URDF 略有差异，但总体保持统一的工业灰白风格，仅在 left_ankle_roll_link 等少数连杆上使用了偏白的配色以突出末端执行器区域。

Sources: atom01.urdf, atom01.urdf, atom01.xml

下一步阅读建议

掌握网格资源的分布与引用逻辑后，建议按以下路径继续深入：

若准备在 ROS 2 环境中查看 Atom01 的三维模型，请阅读 ROS URDF 加载与可视化。
若希望在 MuJoCo 中运行物理仿真，请继续了解 MuJoCo 仿真环境配置。
若想深入理解各连杆之间的关节连接关系与运动学链路，请查阅连杆与关节体系架构。