lgv
4e9bd398f1
Add URDF and USD collision primitive generation, MeshCat collision visualization, configuration, documentation, and generated Isaac Sim assets for the dual-arm model.
146 lines
4.8 KiB
Markdown
146 lines
4.8 KiB
Markdown
# 简化碰撞体生成器
|
||
|
||
统一入口 `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` 只计算和打印拟合结果，不生成输出文件：
|
||
|
||
```bash
|
||
/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` 进行测试：
|
||
|
||
```bash
|
||
/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 中已有的
|
||
网格碰撞实例，避免旧碰撞体和新碰撞体同时生效。
|
||
|
||
确认结果后，可以生成到项目目录：
|
||
|
||
```bash
|
||
/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 名称编写单独配置：
|
||
|
||
```toml
|
||
[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：
|
||
|
||
```toml
|
||
[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 不会被修改。
|
||
|
||
先只预览拟合结果：
|
||
|
||
```bash
|
||
/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：
|
||
|
||
```bash
|
||
/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>`：
|
||
|
||
```bash
|
||
conda run -n cmvr-es python \
|
||
scripts/meshcat/view_urdf_collisions.py \
|
||
--input model/xiaoyan_description/dual_arm_collision.urdf
|
||
```
|
||
|
||
完整选项和关节位置设置方法见 `scripts/meshcat/README.md`。
|