# 简化碰撞体生成器

统一入口 `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`。