127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# 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); // 可能不同！
|
||
```
|