NavisworksTransport/.agents/skills/project-tools/utils/PathHelper.md

PathHelper 使用指南

文件位置

src/Utils/PathHelper.cs

用途

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

核心方法

目录操作

// 获取插件目录路径
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");

文件名处理

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

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

路径计算

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

图像格式转换

// 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

截图生成

// 生成场景截图到默认目录
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：生成带时间戳的报告文件

// 生成报告文件名
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：批量处理文件名

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

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

// 在显示碰撞结果后生成截图
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 中使用