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

UnitsConverter 使用指南

文件位置

src/Utils/UnitsConverter.cs

用途

处理模型单位与米制单位之间的转换。Navisworks 文档可以使用不同的单位（米、毫米、英尺等），必须通过此工具类进行转换。

命名规范（极其重要）

单位类型	命名规则	示例
米单位	变量名必须以 InMeters 结尾	lengthInMeters, heightInMeters
模型单位	变量名无后缀	length, height, cellSize

// ✅ 正确
public void SetSize(double lengthInMeters)
{
    double factor = UnitsConverter.GetMetersToUnitsConversionFactor(...);
    double length = lengthInMeters * factor;  // 模型单位，无后缀
    boundingBox = new BoundingBox3D(0, 0, 0, length, width, height);
}

// ❌ 错误
public void SetSize(double length)  // 无法区分是米还是模型单位！
{
    double scale = length / baseSize;  // 单位不明确！
}

核心方法

获取转换因子

// 获取模型单位到米的转换因子（模型单位 × factor = 米）
double factor = UnitsConverter.GetUnitsToMetersConversionFactor();

// 获取米到模型单位的转换因子（米 × factor = 模型单位）
double factor = UnitsConverter.GetMetersToUnitsConversionFactor();

直接转换值

// 模型单位 → 米
double meters = UnitsConverter.ConvertToMeters(distanceInModelUnits);

// 米 → 模型单位
double modelUnits = UnitsConverter.ConvertFromMeters(distanceInMeters);

带单位的转换（从文档）

// 从当前文档获取单位信息
Units units = Application.ActiveDocument.Units;

// 使用特定单位进行转换
double meters = UnitsConverter.ConvertToMeters(distance, units);
double modelUnits = UnitsConverter.ConvertFromMeters(distanceInMeters, units);

使用示例

示例1：读取配置并转换为模型单位

// 配置中存储的是米
double cellSizeInMeters = ConfigManager.Instance.Current.PathEditing.CellSizeMeters;

// 转换为模型单位用于计算
double cellSize = UnitsConverter.ConvertFromMeters(cellSizeInMeters);

示例2：显示长度给用户

// 路径长度是模型单位
double totalLength = route.TotalLength;

// 转换为米显示
double lengthInMeters = UnitsConverter.ConvertToMeters(totalLength);
string displayText = $"总长度: {lengthInMeters:F2} 米";

示例3：完整的函数参数处理

/// <summary>
/// 生成网格地图
/// </summary>
/// <param name="cellSizeInMeters">网格单元大小（米）</param>
public GridMap Generate(double cellSizeInMeters)
{
    // 转换为模型单位
    double cellSize = UnitsConverter.ConvertFromMeters(cellSizeInMeters);
    
    // 后续计算使用 cellSize（模型单位）
    int gridX = (int)(bounds.Width / cellSize);
    int gridY = (int)(bounds.Height / cellSize);
    
    // ...
}

常见错误

// ❌ 错误1：硬编码转换因子
private const double MM_TO_METERS = 0.001;  // 危险！不同文档单位不同
double meters = modelValue * MM_TO_METERS;   // 只在毫米文档正确

// ❌ 错误2：混淆命名
double cellSize = 0.5;  // 这是米还是模型单位？
if (height > cellSize)  // 单位不匹配的严重bug！

// ❌ 错误3：混用不同文档的单位
Units doc1Units = doc1.Units;
Units doc2Units = doc2.Units;
double value1 = ConvertToMeters(modelValue, doc1Units);
double value2 = ConvertToMeters(modelValue, doc2Units);  // 可能不同！