NavisworksTransport/doc/guide/clash_detective_integration.md

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

// 初始化集成
void Initialize()

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

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

// 清理资源
void Cleanup()

事件处理

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

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

碰撞结果数据结构

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. 检查系统状态

// 检查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/ 目录

---

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