# PathHelper 使用指南

## 文件位置

`src/Utils/PathHelper.cs`

## 用途

提供文件路径相关的通用方法，包括插件目录管理、文件名处理、截图生成等。

## 核心方法

### 目录操作

```csharp
// 获取插件目录路径
string pluginDir = PathHelper.GetPluginDirectory();
// 返回: C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin

// 获取截图目录路径
string screenshotDir = PathHelper.GetScreenshotDirectory();

// 获取报告目录路径
string reportDir = PathHelper.GetReportDirectory();

// 确保目录存在（不存在则创建）
PathHelper.EnsureDirectoryExists("C:\\MyFolder\\SubFolder");
```

### 文件名处理

```csharp
// 清理文件名中的非法字符
string safeName = PathHelper.SanitizeFileName("文件<名称>:非法*字符?");
// 返回: "文件名称非法字符"

// 生成带时间戳的文件名
string fileName = PathHelper.GenerateTimestampedFileName("screenshot", "png");
// 返回: "screenshot_20240225_143052.png"
```

### 路径计算

```csharp
// 计算从HTML文件到目标文件的相对路径
string relativePath = PathHelper.GetRelativePath(
    @"C:\reports\index.html",
    @"C:\images\photo.png"
);
// 返回: "../images/photo.png"
```

### 图像格式转换

```csharp
// ImageFormat 转文件扩展名
string ext = PathHelper.ImageFormatToExtension(ImageFormat.Jpeg);  // "jpg"
string ext = PathHelper.ImageFormatToExtension(ImageFormat.Png);   // "png"

// 文件扩展名转 ImageFormat
ImageFormat format = PathHelper.ExtensionToImageFormat(".jpg");    // Jpeg
ImageFormat format = PathHelper.ExtensionToImageFormat(".png");    // Png
```

### 截图生成

```csharp
// 生成场景截图到默认目录
string path = PathHelper.GenerateSceneScreenshot(
    sceneName: "collision_view",
    width: 1920,
    height: 1080,
    format: ImageFormat.Png,
    prefix: "collision"
);
// 返回: 截图文件完整路径

// 生成场景截图到指定目录
string path = PathHelper.GenerateSceneScreenshotToDirectory(
    outputDirectory: @"C:\MyScreenshots",
    sceneName: "path_view",
    width: 1920,
    height: 1080,
    format: ImageFormat.Jpeg,
    prefix: "path"
);
```

## 使用示例

### 示例1：生成带时间戳的报告文件

```csharp
// 生成报告文件名
string reportDir = PathHelper.GetReportDirectory();
PathHelper.EnsureDirectoryExists(reportDir);

string safeRouteName = PathHelper.SanitizeFileName(route.Name);
string reportFile = PathHelper.GenerateTimestampedFileName(
    $"collision_report_{safeRouteName}", 
    "html"
);
string fullPath = Path.Combine(reportDir, reportFile);

// 保存报告...
```

### 示例2：批量处理文件名

```csharp
// 清理多个文件名
var fileNames = new[] { "文件:1", "名称*2", "测试?3" };
var safeNames = fileNames.Select(f => PathHelper.SanitizeFileName(f));
// 结果: "文件1", "名称2", "测试3"
```

### 示例3：生成碰撞报告截图

```csharp
// 在显示碰撞结果后生成截图
string screenshotPath = PathHelper.GenerateSceneScreenshot(
    sceneName: $"collision_{collisionId}",
    width: 1920,
    height: 1080,
    format: ImageFormat.Png,
    prefix: "collision"
);

if (!string.IsNullOrEmpty(screenshotPath))
{
    LogManager.Info($"截图已保存: {screenshotPath}");
}
```

## 注意事项

1. **目录自动创建**：`GenerateSceneScreenshot` 会自动创建必要的目录
2. **非法字符处理**：`SanitizeFileName` 会移除所有 Windows 文件系统不支持的字符
3. **时间戳格式**：使用 `yyyyMMdd_HHmmss` 格式，确保文件名唯一且可排序
4. **相对路径**：`GetRelativePath` 返回的路径使用正斜杠（/），适合在 HTML 中使用