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

ViewpointHelper 使用指南

文件位置

src/Utils/ViewpointHelper.cs

用途

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

核心方法

路径视角调整

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

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

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

碰撞视角调整

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

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

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

模型元素聚焦

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

视角保存与恢复

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

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

使用示例

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

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

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

示例2：聚焦到碰撞位置

// 检测到碰撞后，聚焦到碰撞对象
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：聚焦到特定模型元素

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

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

// 路径规划完成
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. 性能考虑：频繁调整视角可能影响性能，建议在关键操作后统一调整