145 lines
4.0 KiB
Markdown
145 lines
4.0 KiB
Markdown
# 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. **性能考虑**：频繁调整视角可能影响性能，建议在关键操作后统一调整
|