tian/NavisworksTransport
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ca4488dcb8
NavisworksTransport/WARP.md
tian c9cd17c24a 清理临时的项目文件
2025-08-28 10:00:55 +08:00

9.1 KiB
Raw Blame History

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

NavisworksTransport is a comprehensive Navisworks 2026 plugin for logistics path planning and transportation conflict detection in 3D building models. The plugin provides advanced route optimization, collision detection, and animated object movement along user-defined or automatically calculated paths. This is a Navisworks 2026-exclusive project - no legacy 2017 compatibility is maintained.

Common Development Commands

Building

  • Primary build command: ./compile.bat - Must use ./ prefix in PowerShell/CMD on Windows
  • Alternative: dotnet build NavisworksTransportPlugin.csproj --configuration Debug --verbosity normal
  • MSBuild paths auto-detected: VS2022 Community → Professional → VS2019 fallback

Deployment

  • Deploy to Navisworks: deploy-plugin.bat (requires Administrator privileges)
  • Auto-deployment: Build output automatically copies to Navisworks 2026 plugin directory
  • Plugin location: C:\Program Files\Autodesk\Navisworks Manage 2026\Plugins\NavisworksTransportPlugin\

Testing & Debugging

  • Log viewer: Use LogManager centralized logging - logs stored in %CommonApplicationData%\Autodesk\Navisworks Manage 2026\NavisworksTransport\logs\debug.log
  • Hot reload: Restart Navisworks required after each compilation
  • Testing environment: Navisworks Manage 2026 exclusively

Architecture Overview

Dual Plugin Architecture Pattern

This system implements multiple Navisworks plugin types in a single assembly:

  • MainPlugin.cs: Primary AddInPlugin with ribbon UI integration and DockPanePlugin capabilities
  • PathClickToolPlugin.cs: ToolPlugin for 3D mouse interaction and interactive point placement
  • PathPointRenderPlugin.cs: RenderPlugin providing 3D visualization overlays
  • TestPlugin.cs: Development testing plugin (separate from main functionality)

Core Management Layer

  • PathPlanningManager.cs: Central coordinator with A* pathfinding algorithm integration (RoyT.AStar library)
  • LogisticsAnimationManager.cs: Advanced animation system leveraging 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 system
  • ModelSplitterManager.cs: Model export and layer separation capabilities

Data & Coordinate Systems

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

UI Architecture: Hybrid WPF + WinForms

  • WPF Components (src\UI\WPF\): Modern MVVM-based controls
    • LogisticsControlPanel: Main docked interface panel
    • ViewModels: INotifyPropertyChanged pattern implementation
    • Separated Views: ModelSettingsView, PathEditingView, AnimationControlView, SystemManagementView
  • WinForms Dialogs: Legacy property editing interfaces for backward compatibility
  • Integration: ElementHost pattern for embedding WPF in Navisworks environment

Pathfinding & Animation Integration

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

Technical Implementation Details

Navisworks API Integration Strategy

  • Dual API Approach: Native API (Autodesk.Navisworks.Api) for core functionality + COM API (Autodesk.Navisworks.ComApi) for attribute persistence and TimeLiner operations
  • Multi-Plugin Registration: Three distinct plugin types registered in single assembly
  • Global Exception Handling: GlobalExceptionHandler class provides application-wide error management
  • Navisworks 2026 Exclusive: Utilizes 2026-specific API features without backward compatibility constraints

State Management Architecture

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

Logistics Classification System

Eight predefined categories with automatic inheritance from parent to child nodes:

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

Development Guidelines

Language Standards

  • Primary Language: 中文 (Chinese) for all user interaction, code comments, and technical documentation
  • Communication: All development discussions and code documentation must be in Chinese

Package Management (Legacy .NET Framework)

  • Project Format: Old-style csproj using <Reference Include> with HintPath (NOT PackageReference)
  • NuGet Management: Manual packages.config management (do NOT use dotnet add package)
  • Package Installation: Download .nupkg files and extract to packages/ directory
  • Assembly 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 { }

Critical API Usage Patterns

  • Navisworks API Documentation: Always check doc\navisworks_api\ documentation before implementing Navisworks functionality
  • COM API for Persistence: Use COM API for all attribute operations requiring session persistence
  • GlobalExceptionHandler: Must be initialized in MainPlugin constructor for application-wide error handling
  • Thread Safety: All 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 all 2026-specific features
  • Legacy References: 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: Full utilization of improved 2026 APIs for collision detection, animation, and model management

API Documentation Search Strategy

CHM Documentation Best Practices

Problem: CHM extraction creates thousands of HTML files, making standard search tools ineffective

Solution Strategies:

  1. Use structural entry points:

    # Priority access to class member lists
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm

  2. Precise filename search:

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

  3. Hierarchical search approach:

    • First locate class-level documentation
    • Navigate from class member lists to method links
    • Utilize inter-document hyperlink navigation

  4. Common API documentation paths:

    • Document class: AllMembers_T_Autodesk_Navisworks_Api_Document.htm
    • TimeLiner: AllMembers_T_Autodesk_Navisworks_Api_Timeliner_*.htm
    • Plugin base classes: AllMembers_T_Autodesk_Navisworks_Api_Plugins_*.htm

File Structure Context

Source Organization

src/
├── Core/                          # Main plugin components
│   ├── Animation/                # Animation system
│   ├── Collision/                # Collision detection
│   ├── Properties/               # Attribute management
│   └── [Plugin classes]         # Main, Tool, Render plugins
├── PathPlanning/                  # A* pathfinding algorithms
├── UI/
│   ├── Forms/                    # WinForms dialogs
│   └── WPF/                      # Modern WPF interface
└── Utils/                        # Utility classes

Documentation Structure

  • doc/guide/: Development guides and troubleshooting
  • doc/migration/: 2017→2026 migration documentation
  • doc/requirement/: Requirements and specifications
  • doc/working/: Active development documentation

Build Configuration

  • Target Framework: .NET Framework 4.8 (x64 platform)
  • Navisworks Version: 2026 exclusive with conditional compilation (NAVISWORKS_2026)
  • Key Dependencies: RoyT.AStar for pathfinding, WPF for modern UI