# 2.5.2 碰撞检查功能设计说明

## 2.5.2.1. 模块描述

碰撞检查模块是碰撞检测功能的核心模块，负责在指定物流组件（待载转运车）动画运行过程中，如果与其他模型发生碰撞或干涉，要高亮显示该模型，并记录碰撞结果。支持碰撞记录导出。该模块使用ClashDetective集成和空间索引实现高效的动态碰撞检测。

该模块与ClashDetectiveIntegration、PathAnimationManager和CollisionSceneHelper紧密集成，实现实时碰撞检测和结果记录。

## 2.5.2.2. 功能

### 核心功能
1. **实时碰撞检测**：在动画播放过程中实时检测碰撞
2. **碰撞高亮**：高亮显示发生碰撞的模型
3. **碰撞记录**：记录碰撞的时间、位置、对象等信息
4. **结果导出**：导出碰撞记录到文件
5. **ClashDetective集成**：与Navisworks ClashDetective联动

### 子功能
| 功能编号 | 功能名称 | 功能描述 |
|---------|---------|---------|
| 2.5.2.F1 | 预计算碰撞 | 预计算可能的碰撞点 |
| 2.5.2.F2 | 实时检测 | 动画过程中的实时碰撞检测 |
| 2.5.2.F3 | 碰撞高亮 | 高亮显示碰撞对象 |
| 2.5.2.F4 | 碰撞记录 | 记录碰撞详情 |
| 2.5.2.F5 | 结果查看 | 查看碰撞结果列表 |
| 2.5.2.F6 | 记录导出 | 导出碰撞记录 |
| 2.5.2.F7 | 排除设置 | 设置不参与碰撞检测的对象 |
| 2.5.2.F8 | 容差设置 | 设置碰撞检测容差 |

## 2.5.2.3. 性能

### 性能指标
| 指标名称 | 目标值 | 说明 |
|---------|-------|------|
| 检测响应时间 | < 50ms | 单次碰撞检测的响应时间 |
| 帧率影响 | < 5FPS | 碰撞检测对动画帧率的影响 |
| 支持对象数量 | > 10000 | 支持检测的场景对象数量 |
| 内存占用 | < 200MB | 碰撞检测的额外内存占用 |

### 性能优化策略
1. 使用空间索引加速检测
2. 碰撞结果缓存
3. 分层检测减少计算量

## 2.5.2.4. 输入输出项

### 1. 字段输入输出

#### 输入字段
| 字段名 | 类型 | 必填 | 说明 |
|-------|------|-----|------|
| AnimatedObject | ModelItem | 是 | 运动对象 |
| ExcludedObjects | List<ModelItem> | 否 | 排除的对象列表 |
| Tolerance | double | 否 | 检测容差（米），默认0.05 |
| UseClashDetective | bool | 否 | 使用ClashDetective，默认true |

#### 输出字段
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Collisions | List<CollisionResult> | 碰撞结果列表 |
| CollisionCount | int | 碰撞总数 |
| UniqueCollisions | int | 去重后的碰撞数 |

### 2. 界面交互输入输出

#### 界面输入
- 检测容差设置
- 排除对象选择
- 手动触发检测

#### 界面输出
- 碰撞列表显示
- 碰撞位置高亮
- 碰撞统计信息
- 结果导出提示

## 2.5.2.5. 算法

### 碰撞检测算法
```
算法：基于空间索引的碰撞检测
输入：运动对象，场景对象，容差
输出：碰撞结果

1. 获取运动对象的包围盒
2. 膨胀包围盒（增加容差）
3. 使用空间索引查询可能碰撞的对象
4. 对于每个候选对象：
   5. 进行精确的碰撞检测
   6. 如果碰撞：
      7. 记录碰撞信息
8. 返回所有碰撞结果
```

### ClashDetective集成算法
```
算法：使用ClashDetective检测碰撞
输入：运动对象，检测配置
输出：碰撞结果

1. 创建Clash测试
2. 设置测试参数
3. 执行测试
4. 获取碰撞结果
5. 解析结果数据
6. 转换为内部格式
7. 返回碰撞列表
```

### 碰撞记录算法
```
算法：记录碰撞信息
输入：碰撞结果
输出：记录数据

1. 对于每个碰撞：
   2. 记录时间戳
   3. 记录动画进度
   4. 记录碰撞位置
   5. 记录涉及的对象
   6. 记录碰撞类型
   7. 保存到数据库
8. 返回记录ID
```

## 2.5.2.6. 流程逻辑

```
开始
  │
  ▼
┌─────────────────┐
│  配置检测参数    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  设置排除对象    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐      是
│  预计算碰撞？    │──────────┐
└────────┬────────┘          │
         │否                 │
         ▼                   │
┌─────────────────┐          │
│  开始动画播放    │          │
└────────┬────────┘          │
         │                   │
         ▼                   │
┌─────────────────┐          │
│  实时碰撞检测    │          │
└────────┬────────┘          │
         │                   │
    ┌────┴────┐              │
    ▼         ▼              │
┌────────┐  ┌────────┐       │
│发现碰撞│  │无碰撞  │       │
└───┬────┘  └───┬────┘       │
    │           │            │
    ▼           │            │
┌────────┐      │            │
│高亮显示│      │            │
└───┬────┘      │            │
    │           │            │
    ▼           │            │
┌────────┐      │            │
│记录碰撞│      │            │
└───┬────┘      │            │
    │           │            │
    └─────┬─────┘            │
          │                  │
          ▼                  │
┌─────────────────┐          │
│  继续动画？      │──────────┤
└────────┬────────┘ 否       │
         │                   │
         │是                 │
         │                   │
         └───────────────────┤
                             │
                             ▼
                   ┌─────────────────┐
                   │  执行ClashDetective检测  │
                   └────────┬────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │  合并检测结果    │
                   └────────┬────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │  显示最终结果    │
                   └────────┬────────┘
                            │
                            ▼
                           结束
```

## 2.5.2.7. 接口

### 公共接口
```csharp
/// <summary>
/// ClashDetective集成
/// </summary>
public class ClashDetectiveIntegration
{
    /// <summary>
    /// 执行碰撞检测测试
    /// </summary>
    /// <param name="animatedObject">运动对象</param>
    /// <param name="config">检测配置</param>
    /// <returns>检测结果</returns>
    public ClashTestResult RunClashTest(ModelItem animatedObject, ClashTestConfig config);
    
    /// <summary>
    /// 获取当前碰撞结果
    /// </summary>
    public List<ClashResult> GetCurrentCollisions();
    
    /// <summary>
    /// 导出碰撞结果
    /// </summary>
    /// <param name="filePath">导出路径</param>
    public void ExportCollisions(string filePath);
    
    /// <summary>
    /// 设置排除对象
    /// </summary>
    public void SetExcludedObjects(List<ModelItem> excludedObjects);
}

/// <summary>
/// 碰撞检测配置
/// </summary>
public class ClashTestConfig
{
    public double Tolerance { get; set; }
    public bool UsePreciseDetection { get; set; }
    public List<ModelItem> ExcludedObjects { get; set; }
}
```

### 事件接口
```csharp
/// <summary>
/// 碰撞检测事件参数
/// </summary>
public class CollisionDetectedEventArgs : EventArgs
{
    public ModelItem AnimatedObject { get; set; }
    public ModelItem CollisionObject { get; set; }
    public Point3D Position { get; set; }
    public double AnimationProgress { get; set; }
}

/// <summary>
/// 碰撞检测事件
/// </summary>
public event EventHandler<CollisionDetectedEventArgs> CollisionDetected;
```

## 2.5.2.8. 注释设计

### 代码注释规范
```csharp
/// <summary>
/// 碰撞结果
/// </summary>
public class CollisionResult
{
    /// <summary>
    /// 运动对象
    /// </summary>
    public ModelItem Item1 { get; set; }
    
    /// <summary>
    /// 被碰撞对象
    /// </summary>
    public ModelItem Item2 { get; set; }
    
    /// <summary>
    /// 碰撞位置
    /// </summary>
    public Point3D CollisionPoint { get; set; }
    
    /// <summary>
    /// 碰撞时的动画进度（0-1）
    /// </summary>
    public double AnimationProgress { get; set; }
    
    /// <summary>
    /// 碰撞时间
    /// </summary>
    public DateTime Timestamp { get; set; }
}
```

## 2.5.2.9. 数据结构

### CollisionResult 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Item1 | ModelItem | 运动对象 |
| Item2 | ModelItem | 被碰撞对象 |
| CollisionPoint | Point3D | 碰撞位置 |
| AnimationProgress | double | 动画进度（0-1） |
| Timestamp | DateTime | 碰撞时间 |
| CollisionType | CollisionType | 碰撞类型 |
| PenetrationDepth | double | 穿透深度 |

### CollisionType 枚举
| 值 | 说明 |
|---|------|
| Hard | 硬碰撞（实体接触） |
| Soft | 软碰撞（容差范围内） |
| Clearance | 间隙不足 |

### ClashTestConfig 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| Tolerance | double | 检测容差（米） |
| UsePreciseDetection | bool | 使用精确检测 |
| ExcludedObjects | List<ModelItem> | 排除对象 |
| TestName | string | 测试名称 |

### CollisionStatistics 结构
| 字段名 | 类型 | 说明 |
|-------|------|------|
| TotalCollisions | int | 总碰撞数 |
| UniqueCollisions | int | 去重后碰撞数 |
| HardCollisions | int | 硬碰撞数 |
| SoftCollisions | int | 软碰撞数 |
| MostHitObject | ModelItem | 被碰撞最多的对象 |
| FirstCollisionTime | double | 首次碰撞进度 |
