# Clash Detective 集成使用指南

## 概述

本指南详细介绍了 NavisworksTransport 插件与 Clash Detective 的集成功能，实现了动态碰撞检测与 Clash Detective 窗口的联动。

## 功能特性

### 1. 自动碰撞检测

- **实时检测**: 动画播放过程中实时检测碰撞
- **智能回退**: 当 Clash Detective 不可用时，自动切换到简化碰撞检测
- **双重模式**: 支持精确几何碰撞检测和简化包围盒检测

### 2. Clash Detective 集成

- **自动发现**: 自动检测并连接到 Clash Detective 插件
- **测试管理**: 创建和管理动态碰撞测试
- **结果同步**: 碰撞结果同步显示到 Clash Detective 窗口

### 3. 可视化高亮

- **碰撞高亮**: 自动高亮碰撞对象（红色显示）
- **实时更新**: 动画过程中实时更新碰撞状态
- **清理机制**: 动画结束后自动清理临时高亮

## 使用方法

### 1. 启动插件

1. 打开 Navisworks Manage 2017
2. 加载包含物流路径的模型
3. 从菜单栏选择 "附加模块" > "Transport Plugin"

### 2. 设置动画

1. 在控制面板中选择要动画的物体对象
2. 选择预定义的路径或创建新路径
3. 设置动画参数（时长、速度等）

### 3. 启用碰撞检测

1. 在动画控制面板中确保"启用碰撞检测"选项已勾选
2. 可选择"高亮显示碰撞"以可视化碰撞结果
3. 点击"播放动画"开始带碰撞检测的动画

### 4. 测试集成功能

1. 点击"测试Clash Detective集成"按钮
2. 系统会自动运行完整的集成测试
3. 查看测试结果和日志信息

## 集成架构

### 核心组件

#### 1. ClashDetectiveIntegration

- **功能**: 主要的集成管理器
- **位置**: `src/ClashDetectiveIntegration.cs`
- **职责**:
  - 管理与 Clash Detective 的连接
  - 执行碰撞检测逻辑
  - 处理结果同步

#### 2. PathAnimationManager

- **功能**: 动画管理器（已升级）
- **位置**: `src/PathAnimationManager.cs`
- **职责**:
  - 集成碰撞检测到动画循环
  - 管理碰撞检测事件
  - 处理高亮显示

#### 3. ClashDetectiveIntegrationTest

- **功能**: 集成测试管理器
- **位置**: `src/ClashDetectiveIntegrationTest.cs`
- **职责**:
  - 验证集成功能
  - 性能测试
  - 错误诊断

### 数据流程

```
动画播放 -> 碰撞检测 -> 结果处理 -> 高亮显示 -> 窗口同步
    ↓           ↓           ↓           ↓           ↓
   Timer    DetectCollisions  ProcessResults  HighlightObjects  SyncWindow
```

## API 接口

### 主要方法

#### ClashDetectiveIntegration.Instance

```csharp
// 初始化集成
void Initialize()

// 检测碰撞
List<CollisionResult> DetectCollisions(ModelItem animatedObject, ModelItemCollection excludeObjects = null)

// 高亮显示碰撞
void HighlightCollisions(List<CollisionResult> results)

// 清理资源
void Cleanup()
```

#### 事件处理

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

// 事件参数
public class CollisionDetectedEventArgs : EventArgs
{
    public List<CollisionResult> Results { get; }
    public int CollisionCount { get; }
}
```

### 碰撞结果数据结构

```csharp
public class CollisionResult
{
    public Guid ClashGuid { get; set; }
    public string DisplayName { get; set; }
    public ClashResultStatus Status { get; set; }
    public string GridLocation { get; set; }
    public ModelItem Item1 { get; set; }
    public ModelItem Item2 { get; set; }
    public Point3D Center { get; set; }
    public double Distance { get; set; }
    public DateTime CreatedTime { get; set; }
}
```

## 配置选项

### 碰撞检测参数

- **容差**: 默认 0.01 米（1厘米）
- **测试类型**: 硬碰撞检测
- **检测频率**: 50ms 间隔（20 FPS）

### 高亮设置

- **碰撞颜色**: 红色
- **非碰撞对象**: 保持原色
- **清理时机**: 动画结束或用户停止

## 故障排除

### 常见问题

#### 1. Clash Detective 未找到

**症状**: 系统提示"未找到Clash Detective插件"
**解决**:

- 确保 Clash Detective 已正确安装
- 检查 Navisworks 版本兼容性
- 查看日志文件获取详细信息

#### 2. 碰撞检测不工作

**症状**: 动画播放但无碰撞检测结果
**解决**:

- 确保模型包含几何体
- 检查动画对象是否有效
- 使用测试按钮验证集成

#### 3. 高亮显示异常

**症状**: 碰撞对象未正确高亮
**解决**:

- 重启动画播放
- 检查对象选择是否正确
- 清理临时材质覆盖

### 调试方法

#### 1. 查看日志

日志文件位置: `%USERPROFILE%\Documents\NavisworksTransport\Logs\`

#### 2. 运行测试

使用"测试Clash Detective集成"按钮进行全面测试

#### 3. 检查系统状态

```csharp
// 检查COM API状态
var state = ComApiBridge.ComApiBridge.State;

// 检查插件数量
var pluginCount = state.Plugins().Count;
```

## 性能优化

### 建议设置

- **大模型**: 增加碰撞检测间隔到 100ms
- **复杂路径**: 减少路径点数量
- **多对象**: 使用批处理检测

### 内存管理

- 动画结束后自动清理资源
- 定期重置临时材质
- 避免长时间运行动画

## 更新日志

### v0.1.8 (当前版本)

- ✅ 新增 Clash Detective 集成功能
- ✅ 实现实时碰撞检测
- ✅ 添加自动化测试框架
- ✅ 优化性能和错误处理

### 计划功能

- 🔄 支持自定义碰撞规则
- 🔄 批量路径碰撞分析
- 🔄 碰撞报告导出
- 🔄 更多可视化选项

## 技术支持

如有问题请查看：

1. 日志文件: `%USERPROFILE%\Documents\NavisworksTransport\Logs\`
2. 测试结果: 使用集成测试按钮
3. 开发文档: `doc/design/` 目录

---

*本文档随插件版本更新，请查看最新版本获取准确信息。*