CameraControls API

CameraControls 是 u-space 对 camera-controls 库的扩展封装，提供相机飞行、视角切换等高级功能。通过 viewer.controls 访问。

默认配置

属性	默认值	说明
minDistance	0.2	相机最小缩放距离。
smoothTime	0.2	平滑过渡时间（秒）。
dollySpeed	0.2	滚轮缩放速度。

更多基础属性和方法请参考 camera-controls 文档。

方法

flyToBox(box, options?)

将相机飞行到指定的 Box3 包围盒。

import { Box3 } from 'three/webgpu';

const box = new Box3().setFromObject(myModel);
await viewer.controls.flyToBox(box, {
  viewpoint: 'frontTop',
  enableTransition: true,
  padding: 0.1,
});

FlyToBoxOptions

属性	类型	默认值	说明
viewpoint	string	'frontTop'	预设视角方向，见下方视角列表。设为 'current' 保持当前朝向。
enableTransition	boolean	true	是否启用平滑过渡动画。
padding	number	0.1	包围盒四周的留白比例。
cover	boolean	false	是否以覆盖模式适配（类似 CSS object-fit: cover）。

预设视角：

top | bottom | front | back | left | right | frontTop | backTop | leftTop | rightTop | leftFrontTop | rightFrontTop | leftBackTop | rightBackTop | current

flyToObject(object, options?)

将相机飞行到指定对象的包围盒。参数同 flyToBox。

await viewer.controls.flyToObject(myModel, { viewpoint: 'rightFrontTop' });

setCameraViewpoint(viewpoint, enableTransition?)

将相机平滑过渡到指定的位置、目标和缩放。

await viewer.controls.setCameraViewpoint({
  position: { x: 10, y: 5, z: 10 },
  target: { x: 0, y: 0, z: 0 },
  zoom: 1.0,
});

// 禁用过渡动画，立即跳转
await viewer.controls.setCameraViewpoint(viewpoint, false);

参数：

参数	类型	默认值	说明
viewpoint	CameraViewpointData	—	包含 position、target、zoom。
enableTransition	boolean	true	是否启用平滑过渡动画。

CameraViewpointData

属性	类型	说明
position	IVector3	相机位置。
target	IVector3	相机注视目标位置。
zoom	number	相机缩放值。

flyTo(position, target, options?)

将相机飞行到指定的位置和注视目标。

await viewer.controls.flyTo(
  { x: 10, y: 8, z: 10 },
  { x: 0, y: 0, z: 0 },
  { enableTransition: true },
);

参数：

参数	类型	默认值	说明
position	IVector3	—	相机目标位置。
target	IVector3	—	相机注视目标。
enableTransition	boolean	true	是否启用平滑过渡动画。

getCameraViewpoint()

获取当前相机的视角数据，返回 CameraViewpointData。与 setCameraViewpoint 对应，方便保存/恢复视角。

const viewpoint = viewer.controls.getCameraViewpoint();
console.log(viewpoint.position, viewpoint.target, viewpoint.zoom);

// 稍后恢复
await viewer.controls.setCameraViewpoint(viewpoint);

lock() / unlock()

锁定或解锁相机控制（禁用/启用所有用户交互）。

viewer.controls.lock();   // 禁止用户操作相机
viewer.controls.unlock(); // 恢复用户操作

setViewMode(mode, enableTransition?)

在 2D 俯视图和 3D 透视图之间切换。2D 模式会将相机旋转到正上方，并锁定极角。

await viewer.controls.setViewMode('2d'); // 切换到 2D 俯视模式
await viewer.controls.setViewMode('3d'); // 切换回 3D 模式

参数：

参数	类型	默认值	说明
mode	'2d' | '3d'	—	视图模式。
enableTransition	boolean	true	是否启用平滑过渡动画。

absoluteRotations()

将方位角（azimuth）归一化到 [-π, π] 范围内，避免相机在飞行过渡时产生多余旋转。在 flyToBox 内部自动调用。

viewer.controls.absoluteRotations();