lgv 4e9bd398f1 feat(collision): add collision primitive generation tools

Add URDF and USD collision primitive generation, MeshCat collision visualization, configuration, documentation, and generated Isaac Sim assets for the dual-arm model.

2026-07-27 15:39:54 +08:00

4.8 KiB

Raw Blame History

简化碰撞体生成器

统一入口 generate_collision_primitives.py 根据输入和输出扩展名自动处理 URDF 或 USD。它读取机器人各个 link 的可视网格，并拟合为 box、sphere 或 cylinder；自动模式会选择包围体积最小的几何体。

URDF 输入会生成一份包含 <collision> 的新 URDF；USD 输入会生成引用原 USD 的 overlay。两种流程都不会修改源文件。USD 生成器还会把长度单位、质量单位和 up axis 复制到 overlay 根层，避免使用默认的厘米制和 Y-up 坐标系。当前双臂模型使用米制、 Z-up 坐标系。

预览拟合结果

使用 --dry-run 只计算和打印拟合结果，不生成输出文件：

/home/lgv/app/isaacsim/python.sh \
  scripts/isaac_sim/generate_collision_primitives.py \
  --input model/xiaoyan_description/dual_arm_2/dual_arm.usda \
  --config scripts/isaac_sim/dual_arm_collision.toml \
  --dry-run

调试配置时，可使用 --only R_ELBOW_R_S 只拟合一个 link。

生成并验证 overlay USD

先生成到 /tmp 进行测试：

/home/lgv/app/isaacsim/python.sh \
  scripts/isaac_sim/generate_collision_primitives.py \
  --input model/xiaoyan_description/dual_arm_2/dual_arm.usda \
  --output /tmp/dual_arm_collision_test.usda \
  --config scripts/isaac_sim/dual_arm_collision.toml \
  --replace \
  --validate

在 Isaac Sim 中打开 /tmp/dual_arm_collision_test.usda，并在 Viewport 中启用 Guide Geometry，即可查看碰撞体。默认情况下，overlay 会停用输入 USD 中已有的网格碰撞实例，避免旧碰撞体和新碰撞体同时生效。

确认结果后，可以生成到项目目录：

/home/lgv/app/isaacsim/python.sh \
  scripts/isaac_sim/generate_collision_primitives.py \
  --input model/xiaoyan_description/dual_arm_2/dual_arm.usda \
  --output model/xiaoyan_description/dual_arm_collision.usda \
  --config scripts/isaac_sim/dual_arm_collision.toml \
  --replace \
  --validate

配置单个 link

使用 link 名称编写单独配置：

[links.R_ELBOW_R_S]
primitive = "cylinder"
axis = "y"
padding = 0.002
scale = 1.0

primitive 支持以下取值：

auto：自动选择包围体积最小的几何体
box：盒体
sphere：球体
cylinder：圆柱体

盒体设置 alignment = "link" 后，会使用与 link 局部 XYZ 轴平行的 AABB，不会产生自由旋转的斜包围盒。圆柱体设置 axis = "x"、"y" 或 "z" 后，圆柱轴会固定到对应的 link 局部轴。

其他常用参数：

padding：在碰撞体外侧增加的绝对尺寸，单位为米
scale：以碰撞体中心为基准进行整体缩放
enabled = false：跳过该 link

USD 中缺少可视网格时回退到 STL

如果导入后的 USD 中缺少某个 link 的可视网格，可以使用 mesh_file 指向 URDF 使用的原始 STL：

[links.L_WRIST_R_S]
mesh_file = "../../model/xiaoyan_description/meshes/L_WRIST_R_S.STL"
primitive = "box"
alignment = "link"

相对路径以 TOML 配置文件所在目录为基准。STL 顶点必须使用该 link 的局部坐标系。

直接生成带简化碰撞体的 URDF

对于 URDF，统一入口会读取每个 link 的 visual mesh，应用 <visual><origin> 和 <mesh scale> 后，把拟合结果写成新的 <collision>。原始 URDF 不会被修改。

先只预览拟合结果：

/home/lgv/app/isaacsim/python.sh \
  scripts/isaac_sim/generate_collision_primitives.py \
  --input model/xiaoyan_description/dual_arm.urdf \
  --config scripts/isaac_sim/dual_arm_collision.toml \
  --dry-run

生成并验证新的 URDF：

/home/lgv/app/isaacsim/python.sh \
  scripts/isaac_sim/generate_collision_primitives.py \
  --input model/xiaoyan_description/dual_arm.urdf \
  --output model/xiaoyan_description/dual_arm_collision.urdf \
  --config scripts/isaac_sim/dual_arm_collision.toml \
  --replace \
  --validate

默认行为是：只对实际生成碰撞体的 link 删除旧 <collision>，然后写入一个名为 AUTO_COLLISION_BOX、AUTO_COLLISION_SPHERE 或 AUTO_COLLISION_CYLINDER 的新碰撞体。配置为 enabled = false 的 link 完全不改动，所以当前配置会保留 base_link 的底座圆柱，以及 R_FINGER_TIP、R_CAM 的原有球体。

调试时可用 --only L_WRIST_P_S 只处理一个 link。需要保留某个已存在碰撞体并在其后追加自动碰撞体时，使用 --keep-existing。

使用 MeshCat 查看 URDF 碰撞体

生成后可直接启动 MeshCat 查看器。STL 按 URDF 原始材质显示，亮绿色线框是 URDF 的 <collision>：

conda run -n cmvr-es python \
  scripts/meshcat/view_urdf_collisions.py \
  --input model/xiaoyan_description/dual_arm_collision.urdf

完整选项和关节位置设置方法见 scripts/meshcat/README.md。

4.8 KiB Raw Blame History Unescape Escape