# CameraControls API

`CameraControls` 是 `u-space` 对 [`camera-controls`](https://github.com/yomotsu/camera-controls) 库的扩展封装，提供相机飞行、视角切换等高级功能。通过 `viewer.controls` 访问。

## 默认配置

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

> 更多基础属性和方法请参考 [camera-controls 文档](https://github.com/yomotsu/camera-controls)。

## 方法

### `flyToBox(box, options?)`

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

```typescript
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`。

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

### `setCameraViewpoint(viewpoint, enableTransition?)`

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

```typescript
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?)`

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

```typescript
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` 对应，方便保存/恢复视角。

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

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

### `lock()` / `unlock()`

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

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

### `setViewMode(mode, enableTransition?)`

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

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

**参数：**

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

### `absoluteRotations()`

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

```typescript
viewer.controls.absoluteRotations();
```