NavisworksTransport/CHANGELOG.md

NavisworksTransport 变更日志

[0.2.0] - 2025-07-21

重大功能突破 🎯

• 动画碰撞检测完整集成到Clash Detective
  • 实现了"把动画运行过程中的，每一步的测试结果，显示到clashdetective窗口中"的核心需求
  • 新增碰撞位置记录和恢复机制，支持精确重现动画中的碰撞时刻
  • 实现了位置缓存系统，记录每个碰撞的精确3D坐标
  • 动画结束后自动创建独立的碰撞测试，每个碰撞对应一个Clash Detective测试项

技术突破 🔧

• 位置恢复方案

  • 新增CacheCollisionDuringAnimation()方法，实时记录碰撞对象位置
  • 使用OverridePermanentTransform精确移动对象到碰撞位置
  • 实现了对象生命周期管理，避免ObjectDisposedException
  • 支持碰撞测试编号从1开始连续计数

• 碰撞检测算法优化

  • 修复了简化碰撞检测导致的误判问题（之前距离12403.11单位却显示碰撞）
  • 统一了缓存检测和高亮显示的算法标准，确保结果一致性
  • 采用精确的包围盒相交检测替代大容差检测

用户体验提升 ✨

• 完整的碰撞可视化
  • 动画播放完成后，自动在Clash Detective中创建所有碰撞测试
  • 每个测试独立显示，包含碰撞时刻的对象位置信息
  • 支持测试编号连续显示（1,2,3...而不是0,2,4...）
  • 实时显示碰撞距离和位置坐标，便于验证

验证结果 ✅

• ✅ 成功记录6个动画碰撞，位置坐标精确到小数点后2位
• ✅ 位置恢复后运行测试，2个测试真实检测到碰撞
• ✅ 测试编号从1开始连续递增，无跳号问题
• ✅ Clash Detective窗口正确显示所有碰撞测试项
• ✅ 算法一致性验证通过，误判率显著降低

代码质量 🛠️

• 架构优化：分离了动画检测和结果展示，提高代码可维护性
• 错误处理：完善的异常处理和对象有效性检查
• 日志系统：详细的碰撞检测和位置记录日志
• 性能优化：减少不必要的重复检测和计算

---

进一步修复对象生命周期和选择清除问题

深度修复

• 选择清除安全性：创建了SafelyClearSelection()方法，完全安全地处理选择清除
  • 新增IsApplicationDocumentValid()方法检查Application和Document对象有效性
  • 替换所有直接的CurrentSelection.Clear()调用为安全方法调用
  • 增加详细的对象状态验证和日志记录
• 定时器异常处理：改进点击监听定时器的异常处理机制
  • 添加ObjectDisposedException的专门处理
  • 在检测到对象释放时自动停止定时器
  • 防止定时器继续尝试访问已释放的对象

技术增强

• 多层防护机制：
  • IsApplicationDocumentValid()：检查核心对象有效性
  • SafelyClearSelection()：安全的选择清除操作
  • 定时器回调中的早期对象检查
• 智能错误处理：
  • 区分ObjectDisposedException和其他异常类型
  • 对象释放时自动停止相关操作
  • 减少无意义的错误日志输出
• 操作简化：
  • 统一所有选择清除操作到单一安全方法
  • 移除重复的try-catch代码块
  • 集中化的错误处理和日志记录

解决的问题

• ✅ "Object has been Disposed" 在清除选择时的错误
• ✅ 定时器继续访问已释放对象的问题
• ✅ 多重异常处理导致的日志混乱
• ✅ 选择清除操作的不一致性

---

[0.1.12] - 2025-07-18

新增 🎉

• TimeLiner 集成功能：不完整的 Navisworks TimeLiner 集成支持
  • 新增 TimeLinerIntegrationManager 类，实现运输任务与 TimeLiner 的无缝集成
  • 动画播放时自动在 TimeLiner 中创建对应的运输任务
  • 支持任务状态实时同步（播放中、暂停、停止、已完成）
  • 任务显示名称包含车辆信息、时间戳和进度状态

技术突破 🔧

• API 兼容性解决：成功解决 Navisworks 2017 TimeLiner API 限制
  • 发现并使用正确的 TaskAddCopy() 方法替代只读的 Tasks.Add()
  • 实现多重 fallback 机制：直接添加 → 插入副本 → 层次结构管理
  • 解决 C# 7.3 兼容性问题（范围运算符、switch 表达式等）
• 双轨制架构设计：
  • 自制动画系统：负责实际的模型移动和碰撞检测
  • TimeLiner 显示系统：负责任务管理和状态展示
  • 两个系统独立运行，互不干扰，确保稳定性

集成组件 📦

• PathAnimationManager 增强：
  • 添加 TimeLiner 相关公共属性：IsTimeLinerAvailable、CurrentState、CurrentTaskId、TimeLinerManager
  • 动画播放时自动创建 TimeLiner 任务
  • 实时同步动画进度到 TimeLiner 任务状态
  • 完善的错误处理和降级机制（TimeLiner 不可用时使用基础动画功能）
• TimeLinerIntegrationManager 核心功能：
  • 任务创建：CreateTransportTask() - 使用官方 API 创建运输任务
  • 进度更新：UpdateTaskProgress() - 实时更新任务状态和进度
  • 任务管理：支持任务删除、清理和层次结构管理
  • 事件系统：StatusChanged、TaskCreated 事件通知

用户体验 ✨

• 无缝集成：原有动画功能完全保持不变，TimeLiner 功能作为增强特性
• 可视化管理：用户可在 TimeLiner 面板中查看所有运输任务
• 状态同步：任务名称实时显示动画状态和进度百分比
• 错误恢复：TimeLiner 功能异常时自动降级到基础动画模式

技术细节 📋

• API 方法：
  • _documentTimeliner.TaskAddCopy(task) - 添加任务副本
  • _documentTimeliner.TaskInsertCopy(index, task) - 插入任务副本
  • _documentTimeliner.TaskAddCopy(parentTask, childTask) - 添加子任务
• 兼容性修复：
  • 使用 Substring(0, 6) 替代 [..6] 范围操作符
  • 传统 switch 语句替代 switch 表达式
  • ModelItemCollection 替代 Selection 直接操作
• 资源管理：
  • 完善的初始化和清理流程
  • 任务引用的本地字典管理
  • 异常情况下的资源自动释放

验证结果 ✅

• ✅ TimeLiner 窗口成功显示运输任务："运输任务：SHINYSTE13_运输_131040"
• ✅ 任务创建使用 TaskAddCopy 方法成功，任务数量从 0 增加到 1
• ✅ 车辆关联正确：关联了 SHINYSTE13 车辆模型
• ✅ 路径参数准确：5 个路径点，10 秒持续时间
• ✅ 原有动画功能完全正常，无任何影响
• ✅ 编译成功，在 Navisworks 2017 中稳定运行

代码优化 🛠️

• 日志系统简化：移除冗余的调试日志，保留关键信息
• 错误处理优化：统一异常处理逻辑，提高代码可读性
• 性能改进：减少不必要的 API 调用和状态检查

[0.1.11] - 2025-06-19

修复

• 🔧 恢复进入路径编辑模式后控制面板自动关闭功能
  • 在v0.1.10添加全局异常处理时意外删除了此功能
  • 现在进入路径编辑模式成功后，控制面板会自动关闭
  • 用户可以正常在3D视图中点击模型添加路径点
• 🔧 修复3D交互阻塞问题
  • 控制面板保持打开状态会阻挡3D视图的鼠标事件
  • 自动关闭确保焦点回到Navisworks主界面

改进

• 📝 更新用户提示信息
  • 明确告知用户控制面板已关闭，避免困惑
  • 提醒用户完成路径编辑后需要重新打开插件面板退出编辑模式
  • 保持原有的操作流程指导

用户体验

• 操作流程：选择通道 → 点击进入编辑 → 面板自动关闭 → 3D点击添加路径点 → 重新打开插件 → 退出编辑
• 交互优化：确保用户能够无障碍地在3D环境中进行路径规划操作

[0.1.10] - 2025-06-19

新增

• 🛡️ 全局异常处理机制，彻底防止程序崩溃
  • 新增GlobalExceptionHandler工具类，捕获AppDomain和Thread级别的未处理异常
  • 实现SafeExecute方法，为所有关键操作提供安全包装
  • 添加未处理异常的详细日志记录（异常类型、消息、堆栈信息）
• 🛡️ 异常自动恢复机制
  • 检测到异常时自动退出路径编辑模式
  • 自动清除临时材质和高亮状态
  • 尝试恢复程序到安全状态

改进内容

• 📝 用户友好的错误提示
  • 技术详情与用户信息分离显示
  • 不同级别的错误提示（错误对话框 vs 简单提示）
  • 错误信息本地化，使用中文提示
• 📝 增强的异常日志
  • 统一的日志格式：[全局异常] 前缀
  • 记录异常类型、消息、堆栈信息
  • 记录是否为终止性异常

技术细节

• 修改MainPlugin.Execute方法，使用GlobalExceptionHandler.SafeExecute包装
• 为ShowCategorySelectionDialog方法添加异常保护
• 为所有按钮点击事件添加SafeExecute包装
• 解决System.Windows.Forms.Application与Autodesk.Navisworks.Api.Application的命名冲突
• 所有异常处理采用"fail-safe"策略，宁可功能失效也不崩溃

版本 [0.1.5] - 2025-06-19

修复对象生命周期管理问题

主要修复

• Object has been Disposed 错误：修复了点击监听和高亮功能中的对象释放错误
  • 添加了IsModelItemValid()方法检查ModelItem对象是否有效
  • 在高亮功能中过滤无效的ModelItem对象
  • 改进了异常处理，防止已释放对象的访问
• 异步操作竞态条件：移除了可能导致对象释放的异步Task.Delay调用
  • 将异步的重新高亮调用改为同步方式
  • 移除了延迟清除选择的异步操作
  • 简化了选择清除的错误处理机制

技术改进

• 对象有效性检查：
  • 新增IsModelItemValid()私有方法
  • 通过访问基本属性检测对象是否已被释放
  • 在高亮前过滤出有效的通道对象
• 同步操作优化：
  • 移除所有System.Threading.Tasks.Task.Delay异步调用
  • 改为直接同步执行选择清除操作
  • 简化了点击监听器的错误处理逻辑
• 错误处理增强：
  • 增加详细的对象状态日志记录
  • 改进异常处理的具体性和准确性
  • 添加有效对象计数和状态反馈

解决的具体问题

• ✅ "Argument 'path' has been Disposed" 错误
• ✅ "Object has been Disposed (null)" 重复错误
• ✅ 点击监听过程中的对象释放异常
• ✅ 高亮功能中的对象访问错误

---

版本 [0.1.2] - 2025-06-17

增加分层可见性控制功能

主要变更

• 修复可见性逻辑缺陷：解决了隐藏非物流项目时，具有物流属性的项目也被错误隐藏的问题
• 改进用户界面：将两个独立按钮（"隐藏非物流分类项目"和"显示所有项目"）替换为单个复选框"只显示物流分类项目"
• 增强递归检查：添加了HasLogisticsAttributesRecursive方法，确保父节点包含具有物流属性的子节点时不会被隐藏
• 优化用户体验：复选框状态实时反映当前可见性状态，操作失败时自动回滚状态

技术成果

• 核心算法改进：

  • 新增递归检查方法，避免误隐藏包含物流子项的父项
  • 修复了 item.Children.Count 方法组调用问题，改为 item.Children.Count()
  • 优化了错误处理和状态管理机制

• UI/UX提升：

  • 单一复选框控制替代双按钮，操作更直观
  • 实时状态反馈，显示隐藏项目数量
  • 操作失败时的状态回滚机制

验证结果

• ✅ 设置3个模型为物流分类后，勾选"只显示物流分类项目"复选框，成功隐藏非物流项目同时保持物流项目可见
• ✅ 取消勾选复选框，所有项目正确恢复显示
• ✅ 状态标签准确显示操作结果和隐藏项目数量
• ✅ 错误处理和状态回滚机制工作正常

---

版本 [0.1.1] - 2025-06-17

增加物流类别属性功能

主要变更

• 实现物流属性分类系统：支持8种物流元素类型（门、电梯、楼梯、通道、障碍物、装卸区、停车位、检查点）
• 集成COM API功能：通过Navisworks COM API实现自定义属性的添加和管理
• 优化代码架构：将LogisticsCategories.cs功能整合到CategoryAttributeManager.cs中，避免重复定义
• 修复API兼容性问题：解决了多个Navisworks 2017 API兼容性问题

技术成果

• COM API集成：

  • 正确实现了ComApiBridge.State的使用
  • 修复了ObjectFactory的调用方式
  • 实现了InwGUIPropertyNode2的自定义属性设置

• 属性管理系统：

  • 支持5种物流属性：类型、可通行性、优先级、适用车辆尺寸、速度限制
  • 实现了属性检查、获取和筛选功能
  • 提供了完整的属性值验证机制

• 代码质量改进：

  • 解决了命名空间冲突（Color和Application类型）
  • 修复了编译错误和方法组调用问题
  • 优化了错误处理和调试信息输出

验证结果

• ✅ 成功为选定模型项添加物流属性，属性在Navisworks属性面板中正确显示
• ✅ 8种物流元素类型的按钮功能正常，属性设置准确
• ✅ COM API调用稳定，无内存泄漏或崩溃问题
• ✅ 编译通过，插件在Navisworks 2017中正常加载和运行

---

版本 [0.1.3] - 2024-01-XX

修复

• 兼容性修复: 修复C# 7.3兼容性问题，移除了nullable引用类型语法
• API兼容性: 修复Navisworks 2017 API兼容性问题
  • 替换了不存在的View.RequestSavedViewpoint()方法
  • 使用Model.RootItem.BoundingBox()替代不存在的Model.BoundingBox()
  • 实现了相机位置估算算法作为API限制的替代方案
• 方法签名优化: 将nullable返回类型改为out参数模式以提高兼容性
  • GetPreciseClickPoint() 方法
  • GetRaycastClickPoint() 方法
  • GetSurfacePointFromGeometry() 方法
  • GetCameraPosition() 方法
• 射线投射算法: 完善了射线与包围盒交点计算的错误处理

技术改进

• 错误处理: 增强了所有射线投射相关方法的错误处理和日志记录
• 后备方案: 在精确坐标获取失败时提供包围盒中心点作为后备方案
• 日志优化: 改进了调试日志的详细程度和格式

技术债务和改进计划

当前已知问题

• 暂无已知的功能性问题

已完成功能 ✅

1. ✅ TimeLiner 集成：已实现完整的 TimeLiner 集成功能（v0.1.9）
   • 运输任务自动创建和管理
   • 动画状态实时同步
   • 完善的错误处理和降级机制

下一步开发计划

1. 路径规划功能：实现 A* 算法的 3D 路径规划
2. 动态碰撞检测增强：进一步集成 Clash Detective 功能
3. 动画和可视化优化：添加更多路径动画效果和碰撞高亮显示
4. DELMIA导出：实现结构化数据导出功能
5. TimeLiner 高级功能：
   • 支持任务时间线编辑
   • 批量任务管理
   • 任务导入导出功能

性能优化目标

• 大型模型的处理性能优化
• 异步操作的用户界面响应性改进
• 内存使用优化和资源清理机制完善

[0.1.4] - 2024-01-XX

修复

• 点击监听问题: 修复鼠标点击没有效果的问题
  • 添加了点击状态跟踪机制，避免重复处理同一选择
  • 增加最小点击间隔（500ms）防止误触
  • 优化定时器间隔从100ms增加到200ms，减少资源消耗
  • 在处理完点击后自动清除选择，为下次点击做准备
• 通道高亮显示: 修复通道自动高亮显示丢失的问题
  • 在进入路径编辑模式前先清除之前的高亮
  • 改用更鲜艳的LimeGreen颜色提高可见性
  • 添加详细的高亮状态日志和错误处理
  • 增强高亮结果验证机制
• 重复路径点: 修复点击3次却产生81条记录的问题
  • 实现选择去重机制，相同选择在时间间隔内不重复处理
  • 添加ModelItem对比逻辑
  • 优化定时器触发频率
• 点选详情显示: 实现路径点列表中点选时的详情显示
  • 在状态栏显示选中点的完整信息（名称、类型、坐标、创建时间）
  • 修复PointsListBox_SelectedIndexChanged事件处理
  • 添加点选择日志记录
  • 实现地图中选中点的高亮重绘

技术改进

• 状态管理: 增强点击状态跟踪和管理
  • 添加_lastProcessedItem和_lastProcessedTime字段
  • 实现MinClickInterval常量控制最小点击间隔
• 日志系统: 改进调试日志的详细程度
  • 点击监听过程的详细日志
  • 通道高亮过程的状态跟踪
  • 异常堆栈信息记录
• 用户体验: 优化交互反馈
  • 改进状态消息显示选中通道数量
  • 在状态栏显示详细的点信息
  • 清除无效选择的自动处理