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

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

Development Guidelines

Claude Code Work Delegation Principle

  • 任何具体的开发工作，全部让子代理完成 - All concrete development work must be delegated to specialized sub-agents
  • Claude Code主要负责需求理解、任务分解和工作协调，不直接进行代码编写
  • 使用专业子代理处理具体实现：navisworks-feature-developer、navisworks-api-researcher、navisworks-ui-designer、technical-architect、project-task-manager

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

  • 不考虑向后兼容性: 直接修改现有代码逻辑，无需保持向后兼容性，专注于解决当前问题和改进现有功能
  • 最小化修改原则: 进行任何代码修改时，必须遵循最小化原则，只修改必要的部分，不添加额外的功能或逻辑，以确保问题能够清晰暴露和定位

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
  • 在编码中，不要用回退或向后兼容的思路和步骤