# 🤖 机械臂动态碰撞测试使用指南

## 快速开始

### 运行测试

```bash
# 1. 测试优化版模型（推荐）
python src/real_arm_collision_test.py --optimized --samples 4

# 2. 测试原版模型
python src/real_arm_collision_test.py --samples 4

# 3. 快速验证（仅需20秒）
python src/real_arm_collision_test.py --optimized --samples 2
```

### 查看结果

```bash
# 详细报告（中文）
cat docs/动态碰撞测试报告.md

# 快速总结
cat 动态碰撞测试完成总结.md

# JSON数据
cat docs/dynamic_collision_report.json
```

---

## 📋 测试说明

### 什么是动态碰撞测试？

**静态测试**（原方法，有问题）：
- 只检测一个固定姿态（零位：所有关节=0°）
- 无法发现运动中的碰撞

**动态测试**（新方法，正确）：
- 测试80个不同姿态
- 覆盖所有关节的运动范围
- 包括极限姿态和危险组合

### 为什么需要？

机械臂在运动时，零件的相对位置会改变：
- 手臂折叠时，大臂可能撞小臂
- 关节极限时，零件可能干涉
- 多关节同时运动时，意外碰撞

---

## ⚙️ 参数说明

### --samples N（采样密度）

控制每个关节的测试点数：

| 值 | 姿态数 | 耗时 | 用途 |
|---:|---:|---:|:---|
| 2 | 16 | ~20秒 | 快速验证 |
| 3 | 31 | ~40秒 | 日常测试 |
| **4** | **80** | **~90秒** | **标准测试** ✅ |
| 5 | 148 | ~3分钟 | 高密度 |
| 6 | 216 | ~5分钟 | 完整测试 |

**推荐**：`--samples 4`（平衡速度和覆盖率）

### --optimized（模型选择）

- **不带此参数**：测试原版模型（间隙0.5mm）
- **带此参数**：测试优化版模型（间隙2.0mm）

---

## 📊 测试结果解读

### 成功（无碰撞）

```
======================================================================
📊 碰撞检测报告
======================================================================
✅ 未检测到碰撞！机械臂在全部测试姿态下均无干涉。
```

**含义**：
- ✅ 设计合理，可以打印装配
- ✅ 所有关节可以自由运动到极限
- ✅ 不会发生零件干涉

### 失败（有碰撞）

```
⚠️  检测到碰撞姿态: 5 个
   碰撞姿态占比: 6.25%

🔴 碰撞对统计:
   P06_大臂骨架 ↔ P07_小臂骨架
      发生次数:   3  最大干涉:   125.3 mm³
```

**含义**：
- ❌ 需要调整设计
- 查看报告中的"最严重姿态"
- 增加间隙或修改几何

---

## 🔧 调整设计

### 如果检测到碰撞

#### 1. 增加关节间隙

编辑 `src/arm_model_optimized.py`：

```python
# 第50行
CLEARANCE_GAP = 2.0  # 改为 2.5 或 3.0
```

重新生成模型并测试：
```bash
python src/arm_model_optimized.py
python src/real_arm_collision_test.py --optimized --samples 4
```

#### 2. 修改具体零件

根据报告中的碰撞对，修改对应函数：
- P06_大臂骨架 → `p_humerus_bone()`
- P07_小臂骨架 → `p_forearm_bone()`

#### 3. 调整关节运动范围

如果某个姿态在实际使用中不会达到，可以编辑：

`src/real_arm_collision_test.py` 第25行：
```python
JOINT_LIMITS = {
    "J1": (-90, 90),      # 根据实际需求调整
    "J2": (-120, 45),     
    # ...
}
```

---

## 🎯 测试覆盖的姿态

### 1. 基本姿态（13个）
- 零位：所有关节=0°
- 每个关节的最小极限（6个）
- 每个关节的最大极限（6个）

### 2. 网格采样（64个）
前3个关节（J1, J2, J3）的4×4×4组合

### 3. 危险姿态（3个）
- 手臂完全收回：J2=-90°, J3=-90°
- 极限扭曲：J1=90°, J2=45°, J3=-135°, J4=90°, J5=45°
- 反向极限：J1=-90°, J2=-120°, J3=10°, J4=-90°, J5=-90°, J6=180°

---

## 📁 文件说明

### 测试脚本
**`src/real_arm_collision_test.py`**
- 主测试程序
- 依赖：arm_model.py 或 arm_model_optimized.py
- 输出：docs/dynamic_collision_report.json

### 报告文件
**`docs/动态碰撞测试报告.md`**
- 详细技术文档（8000字）
- 测试方法、算法、结果分析

**`动态碰撞测试完成总结.md`**
- 简洁总结（2000字）
- 快速查看结果

### 数据文件
**`docs/dynamic_collision_report.json`**
- 机器可读的测试结果
- 包含碰撞详情（如有）

---

## 🐛 故障排除

### 错误：ImportError

```
ImportError: No module named 'arm_model_optimized'
```

**解决**：
- 先运行 `python src/arm_model_optimized.py` 生成模型
- 或使用原版：去掉 `--optimized` 参数

### 错误：内存不足

```
MemoryError
```

**解决**：
- 减少采样密度：`--samples 2`
- 关闭其他程序释放内存

### 测试很慢

**优化**：
- 使用快速测试：`--samples 2`
- 正常的，布尔运算本身就慢
- 80姿态约需90秒是正常的

---

## 💡 高级用法

### 测试特定姿态

编辑脚本，添加自定义姿态：

```python
# src/real_arm_collision_test.py 第175行
dangerous = [
    {"J1": 0, "J2": -90, "J3": -90, ...},  # 现有
    {"J1": 45, "J2": -60, "J3": -120, ...},  # 你的姿态
]
```

### 输出碰撞场景（STEP文件）

如果检测到碰撞，可以导出3D文件查看：

```python
# 在 check_collisions() 中添加
if vol > 2.0:
    cq.exporters.export(shape_a, f"collision_{name_a}.step")
    cq.exporters.export(shape_b, f"collision_{name_b}.step")
```

### 计算最小间隙

未来可以实现距离场计算：

```python
def compute_clearance(shape_a, shape_b):
    """计算两个零件之间的最小距离"""
    # TODO: 实现最近点算法
    pass
```

---

## 📚 相关文档

- **设计文档**：`docs/设计说明.md`
- **优化报告**：`docs/optimization_report.md`
- **使用指南**：`docs/optimization_usage_guide.md`
- **技术细节**：`docs/optimization_technical_details.md`

---

## ✅ 当前测试结果

**日期**: 2026-09-26

| 模型 | 姿态数 | 碰撞 | 状态 |
|:---|---:|---:|:---|
| 原版 | 80 | 0 | ✅ 通过 |
| 优化版 | 80 | 0 | ✅ 通过 |

**结论**：两个版本均可安全使用，推荐**优化版**（更大容差）。

---

## 🆘 需要帮助？

1. 查看详细报告：`docs/动态碰撞测试报告.md`
2. 检查测试输出的JSON文件
3. 如有碰撞，查看报告中的"碰撞对统计"和"最严重姿态"

---

**工具版本**: v1.0  
**最后更新**: 2026-09-26  
**维护者**: ZCode AI