# 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