tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a4eaf46723
NavisworksTransport/CLAUDE.md
tian 3cc840b183 删掉serena的提示词
2025-10-10 09:44:29 +08:00

14 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

NavisworksTransport is a Navisworks 2026 plugin for logistics path planning and transportation conflict detection in 3D building models. The plugin supports route optimization, collision detection, and animated object movement along defined paths.

Current Status: Navisworks 2026 exclusive development - no legacy 2017 compatibility required. Leverages 2026-specific features for enhanced animation and A* pathfinding capabilities.

Build Commands

标准编译方式 (Windows)

  • 推荐编译命令: ./compile.bat - 在项目根目录下运行的标准方式
  • 重要说明: 在Windows系统下必须使用 ./ 前缀来运行批处理文件，不要使用 cmd /c compile.bat 或其他复杂方式

Architecture Overview

Dual Plugin Architecture

The system implements multiple Navisworks plugin types working together:

  • MainPlugin.cs: Primary AddInPlugin with ribbon UI and DockPanePlugin integration
  • PathClickToolPlugin.cs: ToolPlugin for 3D mouse interaction and point placement
  • PathPointRenderPlugin.cs: RenderPlugin for 3D visualization overlay

Core Management Layer

  • PathPlanningManager.cs: Central coordinator for route planning with A* pathfinding support
  • LogisticsAnimationManager.cs: Enhanced animation system targeting Navisworks 2026 native components
  • TimeLinerIntegrationManager.cs: Bridge between custom animations and Navisworks TimeLiner
  • CategoryAttributeManager.cs: COM API wrapper for persistent logistics attribute management
  • VisibilityManager.cs: Model layer control and filtering
  • ModelSplitterManager.cs: Model export and layer separation

Data and Coordinate Systems

  • PathPlanningModels.cs: Core data structures with event-driven state management
  • PathDataManager.cs: JSON serialization with migration support
  • CoordinateConverter.cs: 2D map overlay to 3D world coordinate transformation chains
  • GeometryExtractor.cs: Spatial analysis and bounding box calculations
  • FloorDetector.cs: Automatic floor/level detection for multi-story logistics

⚠️ 模型单位系统 - 极其重要！

核心原则：网格地图生成和路径规划中统一使用模型单位（Model Units），不使用米制单位

本项目中出现的大量bug都源于混淆模型单位和米制单位。必须严格遵守以下规则：

1. 单位转换原则

// ✅ 正确做法：在函数入口处一次性转换所有参数
public GridMap GenerateFromBIM(BoundingBox3D bounds, double cellSize, double vehicleRadius, ...)
{
    // 第一步：立即转换所有米制参数为模型单位
    double metersToModelUnitsConversionFactor = UnitsConverter.GetMetersToUnitsConversionFactor(Application.ActiveDocument.Units);
    double cellSizeInModelUnits = cellSize * metersToModelUnitsConversionFactor;
    double vehicleRadiusInModelUnits = vehicleRadius * metersToModelUnitsConversionFactor;
    double safetyMarginInModelUnits = safetyMargin * metersToModelUnitsConversionFactor;
    double vehicleHeightInModelUnits = vehicleHeight * metersToModelUnitsConversionFactor;

    // 之后所有计算都使用模型单位变量
    var gridMap = new GridMap(bounds, cellSizeInModelUnits);
}

// ❌ 错误做法：在计算过程中混用米制和模型单位

2. 网格地图内部统一使用模型单位

GridMapGenerator和AutoPathFinder中的所有空间计算都基于模型单位：

  • 网格单元大小（CellSize）：模型单位
  • 车辆半径（VehicleRadius）：模型单位
  • 安全间隙（SafetyMargin）：模型单位
  • 车辆高度（VehicleHeight）：模型单位
  • 扫描高度（ScanHeight）：模型单位
  • 膨胀半径（InflationRadius）：模型单位
  • 高度差阈值（MaxHeightDiff）：模型单位
  • 网格坐标和世界坐标转换：模型单位

3. 常见错误模式及避免方法

// ❌ 错误：直接使用常量米制值
private const double MAX_HEIGHT_DIFF = 0.35; // 这是米！
if (heightDiff > MAX_HEIGHT_DIFF) // Bug！heightDiff是模型单位

// ✅ 正确：转换后使用
private const double MAX_HEIGHT_DIFF_METERS = 0.35; // 明确标注单位
double maxHeightDiffInModelUnits = MAX_HEIGHT_DIFF_METERS * UnitsConverter.GetMetersToUnitsConversionFactor();
if (heightDiff > maxHeightDiffInModelUnits) // 正确！

// ❌ 错误：在循环中重复转换
for (int i = 0; i < count; i++) {
    double modelValue = meterValue * UnitsConverter.GetMetersToUnitsConversionFactor(); // 性能浪费
}

// ✅ 正确：提前转换一次
double metersToModelUnits = UnitsConverter.GetMetersToUnitsConversionFactor();
double modelValue = meterValue * metersToModelUnits; // 转换一次
for (int i = 0; i < count; i++) {
    // 使用modelValue进行计算
}

4. 变量命名约定

为了避免混淆，强制使用以下命名规范：

  • 米制变量：使用Meters后缀，如vehicleHeightMeters、cellSizeMeters
  • 模型单位变量：使用InModelUnits后缀，如vehicleHeightInModelUnits、cellSizeInModelUnits
  • 转换系数：统一命名为metersToModelUnitsConversionFactor

5. 关键API的单位约定

// Navisworks API返回的坐标和尺寸都是模型单位
BoundingBox3D bbox = modelItem.BoundingBox(); // 模型单位
Point3D worldPos = gridMap.GridToWorld3D(gridPos); // 模型单位

// 用户配置的参数通常是米制
double cellSize = 0.5; // 米，需要转换
double vehicleRadius = 0.3; // 米，需要转换

6. 日志输出最佳实践

// ✅ 正确：在日志中明确标注单位
LogManager.Info($"网格大小: {cellSize}米 → {cellSizeInModelUnits:F2}模型单位");
LogManager.Info($"高度差阈值: {MAX_HEIGHT_DIFF_METERS}米 = {maxHeightDiffInModelUnits:F2}模型单位");

// ❌ 错误：日志中不标注单位，容易造成误解
LogManager.Info($"网格大小: {cellSize}");

记住：违反这些规则会导致路径规划失败、碰撞检测错误、网格生成异常等各种难以追踪的bug！

UI Architecture: WPF + WinForms Hybrid

  • WPF Components: Modern MVVM-based controls in src\UI\WPF\
    • LogisticsControlPanel: Main docked interface
    • ViewModels with INotifyPropertyChanged pattern
    • Separated Views for different functional areas
  • WinForms Dialogs: Legacy property editing interfaces
  • Integration: ElementHost for WPF in Navisworks environment

Key Technical Details

Navisworks API Integration Pattern

  • Dual API Strategy: Native API (Autodesk.Navisworks.Api) for core functionality + COM API (Autodesk.Navisworks.ComApi) for attribute persistence and TimeLiner operations
  • Plugin Architecture: Three distinct plugin types registered in single assembly
  • Event-Driven Design: Global exception handling with GlobalExceptionHandler class
  • Navisworks 2026 Focus: Utilizes 2026-specific API features without backward compatibility constraints

Pathfinding and Animation System

  • A Algorithm*: RoyT.AStar library integration for optimal path calculation
  • Animation Pipeline: Transform-based movement with collision detection integration
  • TimeLiner Bridge: Synchronization between custom path animations and Navisworks timeline
  • Real-time Collision: ClashDetectiveIntegration for dynamic conflict detection during animation

State Management and Persistence

  • Session State: PathEditState enum (None, AddingPoints, EditingPath) with event callbacks
  • Data Serialization: JSON-based persistence with LogisticsAttributeChangedEventArgs for tracking
  • Coordinate Mapping: Multi-layer coordinate system supporting 2D overlay on 3D models

Logistics Classification System

Eight predefined categories with inheritance from parent to child nodes:

  • 门 (Doors), 电梯 (Elevators), 楼梯 (Stairs), 通道 (Channels)
  • 障碍物 (Obstacles), 装卸区 (Loading Zones), 停车区 (Parking), 检查点 (Checkpoints)

Language and Communication

  • 使用中文进行所有交流和代码注释 - Primary language for user interaction and code documentation
  • 代码注释和文档说明使用中文 - All technical documentation in Chinese

Package Management (Legacy Format)

  • Old-style csproj: Uses <Reference Include> with HintPath instead of PackageReference
  • packages.config: Manual NuGet package management (do NOT use dotnet add package)
  • Manual package installation: Download .nupkg files and extract to packages/ directory
  • Path format: packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll

Plugin Registration Patterns

// Multi-plugin registration in single assembly
[Plugin("NavisworksTransport.MainPlugin", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
public class MainPlugin : AddInPlugin { }

[Plugin("NavisworksTransport.PathClickTool", "YourDeveloperID")]  
[ToolPluginAttribute("NavisworksTransport.PathClickTool", "YourDeveloperID")]
public class PathClickToolPlugin : ToolPlugin { }

Development Principles

  • 防御性编程的正确态度:

    • ✅ 应该做：检测异常情况并报错，让问题暴露出来
    • ❌ 不应该做：用默认值掩盖问题，让bug隐藏在系统中

  • 对于"备份方案"和"容错处理":

    • ✅ 正确做法：发现问题时记录错误日志，中断处理流程
    • ❌ 错误做法：遇到异常数据时自动"修复"或使用替代值继续执行

  • 对于"向后兼容性"：

    • 明确拒绝考虑向后兼容性
    • 专注解决当前问题，不为旧版本或边缘情况妥协

  • 核心原则：

    • "让问题快速暴露" > "让程序看起来正常运行"
    • "报错比静默失败好" > "容忍错误数据继续处理"
    • "数据一致性检查" > "宽松的数据验证"
    • "最小化修改" > "复杂全面的逻辑"

Critical API Usage Patterns

  • Always reference Navisworks API documentation: Check doc\navisworks_api\ before implementing any Navisworks functionality
  • COM API for persistence: Use COM API for attribute operations that need to persist across sessions
  • GlobalExceptionHandler: Initialize in MainPlugin constructor for application-wide error handling
  • Thread safety: UI operations must be marshaled to main thread when called from background processes

Navisworks 2026 Development Focus

  • Exclusive 2026 targeting: No backward compatibility required - leverage 2026-specific features freely
  • Legacy artifacts: src\Legacy\ contains reference code from 2017 version but is not actively maintained
  • Modern animation system: Use Navisworks 2026 native animation components instead of manual Transform manipulation
  • Enhanced APIs: Take advantage of improved 2026 APIs for collision detection, animation, and model management

API Documentation Search Strategy

CHM文档搜索最佳实践

问题：CHM解压后产生大量HTML文件（数千个），标准搜索工具效果有限

解决策略：

  1. 使用文档结构入口点：

    # 优先访问类成员列表
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm

  2. 精确文件名搜索：

    find . -name "*ClassName*" -o -name "*MethodName*"

  3. 分层搜索方法：

    • 先定位到类级别文档
    • 从类成员列表找到方法链接
    • 利用文档间超链接导航

  4. 搜索模式示例：

    # 搜索特定API
grep -r "SaveFile\|Export.*nwd" --include="*.htm" doc/navisworks_api/

# 查找特定类的所有成员
find . -name "AllMembers_T_Autodesk_Navisworks_Api_Document.htm"

  5. 常用API文档路径：

    • Document类：AllMembers_T_Autodesk_Navisworks_Api_Document.htm
    • TimeLiner：AllMembers_T_Autodesk_Navisworks_Api_Timeliner_*.htm
    • 插件基类：AllMembers_T_Autodesk_Navisworks_Api_Plugins_*.htm

避免的搜索方式：

  • 避免在HTML内容中进行模糊搜索（标签干扰）
  • 不要依赖GUID格式的文件名
  • 避免使用过于宽泛的搜索词

Testing and Deployment

  • Testing environment: Navisworks Manage 2026 exclusively - 2017 support discontinued
  • Plugin deployment: Build output automatically copies to Navisworks 2026 plugin directory
  • Hot reload: Restart Navisworks required after compilation to load new plugin version
  • Debugging: Use LogManager for centralized logging and the built-in log viewer dialog for log analysis
  • 2026 Features: Test advanced animation capabilities, enhanced collision detection, and improved model handling
  • 在编码中，不要用回退或向后兼容的思路和步骤
  • 程序的日志在：C:\ProgramData\Autodesk\Navisworks Manage 2026\NavisworksTransport\logs\debug.log
  • 使用agent完成任务前，一定要先用Plan模式设计好方案和任务清单，并征得我同意。
  • 网格坐标代表的是网格单元的左下角，而不是中心点！

运行路径测试

需要先编译单元测试DLL，然后再编译TestRunner：

● Bash(powershell -Command "& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' NavisworksTransport.UnitTests.csproj /p:Configu…) ⎿ 适用于 .NET Framework MSBuild 版本 17.14.10+8b8e13593

   NavisworksTransport.UnitTests -> C:\Users\Tellme\apps\NavisworksTransport\bin\Debug\NavisworksTransport.UnitTests.dll

● Bash(powershell -Command "& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' AStarTestRunner.csproj /p:Configuration=Debug /…) ⎿ 适用于 .NET Framework MSBuild 版本 17.14.10+8b8e13593

   AStarTestRunner -> C:\Users\Tellme\apps\NavisworksTransport\bin\Debug\AStarTestRunner.exe

● 现在运行新的测试程序：

● Bash("bin\Debug\AStarTestRunner.exe")