# ViewpointHelper 使用指南

## 文件位置

`src/Utils/ViewpointHelper.cs`

## 用途

提供 Navisworks 视角调整功能，用于自动调整摄像机位置和视角，支持路径居中显示、碰撞位置聚焦等。

## 核心方法

### 路径视角调整

```csharp
// 智能调整视角到路径中心
ViewpointHelper.AdjustViewpointSmart(path, collisions);

// 调整视角到路径中心，确保整个路径在视野内
ViewpointHelper.AdjustViewpointToPathCenter(path);

// 计算路径的包围盒
BoundingBox3D bounds = ViewpointHelper.CalculatePathBoundingBox(path);
```

### 碰撞视角调整

```csharp
// 计算碰撞位置的包围盒
BoundingBox3D bounds = ViewpointHelper.CalculateCollisionsBoundingBox(collisions);

// 聚焦到碰撞对象（两个对象）
ViewpointHelper.FocusOnCollision(item1, item2, viewAngleDegrees: 45, targetViewRatio: 0.25);

// 聚焦到指定位置
ViewpointHelper.FocusOnPosition(center, targetSize, viewAngleDegrees: 45, targetViewRatio: 0.25);
```

### 模型元素聚焦

```csharp
// 聚焦到单个模型元素
ViewpointHelper.FocusOnModelItem(modelItem, viewAngleDegrees: 45, targetViewRatio: 0.25);
// viewAngleDegrees: 视角角度（度）
// targetViewRatio: 目标占据视图比例（0.25 = 1/4）
```

### 视角保存与恢复

```csharp
// 保存当前视角
Viewpoint savedViewpoint = ViewpointHelper.SaveCurrentViewpoint();

// 恢复视角
ViewpointHelper.RestoreViewpoint(savedViewpoint);
```

## 使用示例

### 示例1：生成碰撞报告前调整视角

```csharp
// 保存当前视角
Viewpoint originalViewpoint = ViewpointHelper.SaveCurrentViewpoint();

try
{
    // 调整视角到路径中心
    ViewpointHelper.AdjustViewpointToPathCenter(path);
    
    // 生成截图
    string screenshotPath = PathHelper.GenerateSceneScreenshot(
        "collision_report", 1920, 1080, ImageFormat.Png
    );
}
finally
{
    // 恢复原始视角
    ViewpointHelper.RestoreViewpoint(originalViewpoint);
}
```

### 示例2：聚焦到碰撞位置

```csharp
// 检测到碰撞后，聚焦到碰撞对象
if (collision.Item1 != null && collision.Item2 != null)
{
    ViewpointHelper.FocusOnCollision(
        collision.Item1, 
        collision.Item2,
        viewAngleDegrees: 45,    // 45度视角
        targetViewRatio: 0.3      // 占据视图30%
    );
    
    // 高亮碰撞对象
    ModelHighlightHelper.HighlightItems("collision", new[] { collision.Item1, collision.Item2 });
}
```

### 示例3：聚焦到特定模型元素

```csharp
// 用户选择了一个门对象
var doorItem = selectedItems.FirstOrDefault();
if (doorItem != null)
{
    // 聚焦到该门，45度斜上方视角
    ViewpointHelper.FocusOnModelItem(doorItem, 45, 0.25);
    
    LogManager.Info($"已聚焦到: {doorItem.DisplayName}");
}
```

### 示例4：路径规划完成后调整视角

```csharp
// 路径规划完成
if (pathRoute.Points.Count > 0)
{
    // 智能调整视角
    ViewpointHelper.AdjustViewpointSmart(pathRoute, collisionResults);
    
    // 高亮路径点
    var pathItems = pathRoute.Points.Select(p => p.AssociatedModelItem).Where(i => i != null);
    ModelHighlightHelper.HighlightItems("pathPreview", pathItems);
}
```

## 视角参数说明

| 参数 | 说明 | 推荐值 |
|------|------|--------|
| `viewAngleDegrees` | 相机视角角度（度） | 45°（斜上方） |
| `targetViewRatio` | 目标占据视图比例 | 0.25（1/4视图） |
| `baseDimension` | 基准尺寸计算相机距离 | 路径长度或包围盒最大边 |

## 注意事项

1. **视角保存**：在进行视角调整前建议保存当前视角，便于后续恢复
2. **异常处理**：方法会抛出 `InvalidOperationException`（无活动文档）和 `ArgumentException`（参数错误），需要适当捕获
3. **单位转换**：内部自动使用 `UnitsConverter` 进行米和模型单位的转换
4. **标准视角**：`FocusOnModelItem` 和 `FocusOnPosition` 使用模型的标准前右上视角（`FrontRightTopViewVector`）
5. **性能考虑**：频繁调整视角可能影响性能，建议在关键操作后统一调整