197 lines
9.1 KiB
Markdown
197 lines
9.1 KiB
Markdown
# 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
|
|
|
|
```csharp
|
|
// 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**:
|
|
|
|
```bash
|
|
# Priority access to class member lists
|
|
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm
|
|
```
|
|
|
|
2. **Precise filename search**:
|
|
|
|
```bash
|
|
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
|