# 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 2017 plugin (v0.1.8) for logistics path planning and transportation conflict detection in 3D building models. The plugin enables route optimization, collision detection, and animated object movement along defined paths.

## Build Commands

- **Build**: `compile.bat` - Automatically detects MSBuild (VS 2017/2019/2022) or falls back to `dotnet build`
- **Target**: .NET Framework 4.6.2, x64 platform
- **Output**: Direct deployment to `%PROGRAMFILES%\Autodesk\Navisworks Manage 2017\Plugins\NavisworksTransportPlugin\`

## Architecture Overview

### Core Plugin Structure
- **MainPlugin.cs**: Primary AddInPlugin entry point with ribbon UI
- **PathClickToolPlugin.cs**: ToolPlugin for 3D mouse interaction
- **PathPointRenderPlugin.cs**: RenderPlugin for 3D visualization

### Manager Components
- **PathPlanningManager.cs**: Central path planning and route management logic
- **PathAnimationManager.cs**: TimeLiner integration for object movement animation
- **CoordinateConverter.cs**: 2D map overlay to 3D world coordinate conversion
- **CategoryAttributeManager.cs**: COM API wrapper for logistics attribute management
- **VisibilityManager.cs**: Layer visibility and model filtering control
- **ModelSplitterManager.cs**: Model layer separation and export functionality

### Data and Utilities
- **PathPlanningModels.cs**: Core data structures (PathEditState, PathRoute, PathPoint)
- **PathDataManager.cs**: Serialization and persistence using Newtonsoft.Json
- **GeometryExtractor.cs**: 3D geometry analysis and bounding box calculations
- **LogManager.cs**: Centralized logging with global exception handling

### UI Components
- **LogisticsPropertyEditDialog.cs**: Property editing interface
- **ModelSplitterDialog.cs**: Model splitting configuration UI

## Key Technical Details

### Navisworks API Integration
- Uses dual API approach: Native API (`Autodesk.Navisworks.Api`) + COM API (`Autodesk.Navisworks.ComApi`)
- COM API required for attribute persistence and TimeLiner operations
- Plugin types: AddInPlugin (main), ToolPlugin (interaction), RenderPlugin (visualization)

### Exception Handling
Global exception handling implemented in MainPlugin with:
- AppDomain.CurrentDomain.UnhandledException
- Application.ThreadException
- Automatic recovery and user-friendly error reporting

### Coordinate Systems
- Supports 2D map overlay on 3D models with dynamic zoom/pan
- Margin-based boundary calculations for click precision
- Transform chains for coordinate conversion between spaces

### Logistics Categories
Eight predefined logistics element types:
- 门 (Doors), 电梯 (Elevators), 楼梯 (Stairs), 通道 (Channels)
- 障碍物 (Obstacles), 装卸区 (Loading Zones), 停车区 (Parking), 检查点 (Checkpoints)

## Development Guidelines

### File Organization
- Core managers handle specific functionality areas
- Models file contains shared data structures
- UI dialogs are separate form classes
- Utilities (logging, geometry, data) are standalone classes

### Plugin Registration Pattern
```csharp
[Plugin("NavisworksTransport.PluginName", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
```

### Error Handling Best Practices
- Use LogManager for consistent logging
- Implement try-catch blocks around Navisworks API calls
- Provide meaningful error messages to users
- Use COM API error codes for troubleshooting

### Dependencies
- **System.Windows.Forms**: UI dialogs and controls
- **System.Drawing**: Graphics and coordinate operations

## Testing and Deployment

- Manual testing required through Navisworks Manage 2017
- Plugin automatically deploys to Navisworks plugin directory during build
- Restart Navisworks after compilation to load new plugin version
- Use LogManager output for debugging and troubleshooting