tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4ddaa0603d
NavisworksTransport/CLAUDE.md

10 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

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

Serena MCP工具配置

  • Token限制策略: 所有serena MCP工具调用必须使用max_answer_chars: 3000参数
  • 适用工具: 包括但不限于：
    • mcp__serena__search_for_pattern
    • mcp__serena__find_symbol
    • mcp__serena__get_symbols_overview
    • mcp__serena__find_referencing_symbols
    • 所有其他支持max_answer_chars参数的serena工具
  • 执行原则:
    • 优先使用精确搜索而非宽泛搜索以减少token消耗
    • 分步骤获取信息，避免一次性获取大量内容
    • 如遇到3k限制导致内容截断，应使用更精确的搜索条件重新查询

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")