NavisworksTransport/CLAUDE.md

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

Language Preference

• 使用中文进行所有交流和代码注释
• 与用户交流时优先使用中文
• 代码注释和文档说明使用中文

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

[Plugin("NavisworksTransport.PluginName", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]

Error Handling Best Practices

• Use LogManager for consistent logging
• Implement try-catch blocks around Navisworks API calls
• 写任何与Navisworks相关的代码，都要查在doc/navisworks_api目录下的官方API文档和示例代码，
• 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