# UnitsConverter 使用指南

## 文件位置

`src/Utils/UnitsConverter.cs`

## 用途

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

## 命名规范（极其重要）

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

```csharp
// ✅ 正确
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;  // 单位不明确！
}
```

## 核心方法

### 获取转换因子

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

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

### 直接转换值

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

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

### 带单位的转换（从文档）

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

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

## 使用示例

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

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

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

### 示例2：显示长度给用户

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

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

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

```csharp
/// <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);
    
    // ...
}
```

## 常见错误

```csharp
// ❌ 错误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);  // 可能不同！
```