@realsee/five/ai_guides/features/mode.md

Realsee Renderer SDK

# Mode (模式)

- **Summary**: Five 支持多种交互模式，包括全景漫游、模型浏览、VR/XR 等，适用于不同的看房场景。
- **Schema**: 字符串枚举类型，定义了 6 种交互模式。
- **Concepts**: Panorama, Mapview, Floorplan, Topview, Model, VR/XR。
- **Examples**: 模式切换与事件监听。

## Schema

> **Definition**: [Mode](../../five/application/mode.d.ts), [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)

**Mode** 类型定义如下：

```ts
type Mode =
  | "Panorama"   // 全景图游走模式
  | "Mapview"    // 模型地图模式
  | "Floorplan"  // 模型户型图模式
  | "Topview"    // 模型平面图模式
  | "Model"      // 模型游走模式
  | "VRPanorama" // Cardboard VR 眼镜模式
  | "XRPanorama" // WebXR 虚拟现实 VR 眼镜模式
```

## Concepts

*   **Panorama (全景漫游)**: 适用于以观察点为中心进行全景图浏览的场景。使用透视相机，位于某个观察点绕自身旋转。常用来展示室内全景照片。
    *   交互：鼠标拖拽 / Pan手势旋转视角；滚轮 / Pinch手势缩放视场角；点击 / Tap手势切换全景点。
*   **Mapview (模型地图)**: 适用于比较大的模型场景。交互类似地图软件。使用透视相机，上帝视角鸟瞰。
    *   交互：左键拖拽 / 单指Pan旋转视角；右键拖拽 / 双指Pan平移相机；滚轮 / Pinch前进后退；点击 / Tap切换到最近全景点。
*   **Floorplan (模型户型)**: 适用于从四周观察模型的场景。使用透视相机围绕模型，并观察模型中心。
    *   交互：鼠标拖拽 / Pan手势旋转视角；滚轮 / Pinch手势缩放视场角；点击 / Tap切换到最近全景点。
*   **Topview (模型平面)**: 适用于查看户型结构。使用正交相机，默认从顶部垂直向下观察模型。
    *   交互：鼠标拖拽 / Pan手势平移相机；滚轮 / Pinch手势缩放画面；点击 / Tap切换到最近全景点。
*   **Model (模型漫游)**: 适用于第一人称在场景中自由游览。交互同 Panorama，但不限制相机只能在观察点位置。
    *   交互：鼠标拖拽 / Pan手势旋转视角；滚轮 / Pinch手势缩放视场角；点击 / Tap移动到指定位置。
*   **VRPanorama / XRPanorama**: 适配 VR 设备（如 Google Cardboard, Apple Vision Pro 等）的沉浸式模式。
    *   交互：配合设备手柄或头部追踪，基本交互逻辑同 Panorama。

## Configuration

初始化 `new Five()` 时，可以通过配置参数对各个模式进行个性化定制。

### Panorama (全景漫游)

```typescript
interface PanoramaConfig {
  /** 默认相机俯仰角 (Default: 0) */
  defaultLatitude?: number;
  /** 默认垂直 FOV (Default: 90) */
  defaultFov?: number;
  /** 最大垂直 FOV (Default: 120) */
  maxFov?: number;
  /** 最小垂直 FOV (Default: 20) */
  minFov?: number;
  /** 最大俯仰角 */
  maxLatitude?: number | ((fov: number) => number);
  /** 最小俯仰角 */
  minLatitude?: number | ((fov: number) => number);
  /** 点位间移动速度 (m/s) (Default: 3.6) */
  moveSpeed?: number;
  /** 最远可移动观察点距离 */
  maxAccessibleDistance?: number;
  /** 点击地面判定范围 */
  panoTapTriggerRadius?: number;
  /** 航拍点最小高度 (Default: 5) */
  aerialObserverMinHeight?: number;
  /** 全景进入渐变时长 (s) */
  tileAppearDuration?: number;
  /** 全景瓦片最大并发请求数 */
  tileMaxRequest?: number;
  /**
   * 地面观察点标识自定义创建器
   * @param observer - 观察点数据
   * @param options - 配置项，如航拍点最小高度
   * @returns PanoCircleMeshInterface 实例 (如 PanoCircleMesh, PanoCircleMeshSolid)
   */
  panoCircleMeshCreator?: (
    observer: WorkObserver,
    options: { aerialObserverMinHeight: number }
  ) => PanoCircleMeshInterface;
}
```

### Mapview (模型地图)

```typescript
interface MapviewConfig {
  /** 默认水平角 (Default: Math.PI / 4) */
  defaultLongitude?: number;
  /** 默认俯仰角 (Default: Math.PI / 4) */
  defaultLatitude?: number;
  /** 默认相机距离 (Default: 150) */
  defaultDistance?: number;
  /** 相机类型: 'perspective' | 'orthographic' | 'auto' (Default: 'auto') */
  cameraType?: "perspective" | "orthographic" | "auto";
  /** 相机移动范围限制 */
  cameraFence?: THREE.Box3 | THREE.Sphere | null;
}
```

### Floorplan (模型户型)

```typescript
interface FloorplanConfig {
  /** 默认水平角 (Default: Math.PI / 4) */
  defaultLongitude?: number;
  /** 默认俯仰角 (Default: Math.PI / 4) */
  defaultLatitude?: number;
  /** 默认垂直 FOV (Default: 80) */
  defaultFov?: number;
}
```

### Topview (模型平面)

```typescript
interface TopviewConfig {
  /** 默认水平角 (Default: 0) */
  defaultLongitude?: number;
  /** 默认俯仰角 (Default: Math.PI / 2) */
  defaultLatitude?: number;
}
```

### Model (模型漫游)

继承自 Panorama 配置，支持 FOV、俯仰角限制及移动速度等参数。

```typescript
interface ModelConfig {
  moveSpeed?: number;
  defaultFov?: number;
  // ... 同 Panorama 基础配置
}
```

### VRPanorama / XRPanorama (VR 模式)

继承自 Panorama 配置，但移除了俯仰角限制（`maxLatitude`, `minLatitude`），因为 VR 模式下视角由设备姿态控制。

```typescript
interface VRPanoramaConfig {
  // ... 同 Panorama 基础配置
  // 移除: maxLatitude, minLatitude
}

interface XRPanoramaConfig {
  // ... 同 Panorama 基础配置
  // 移除: maxLatitude, minLatitude
}
```

## Examples

### 快速上手 (Quick Example)

使用 `setState` 切换模式：

```ts
// 切换到模型地图模式
five.setState({ mode: 'Mapview' });
```

### 初始化配置示例 (Initialization Configuration Example)

在 `new Five()` 时配置各个模式的默认参数：

```typescript
import { Five, PanoCircleMeshSolid } from '@realsee/five';

const five = new Five({
  // 全景模式配置
  panorama: {
    // 限制垂直视角范围
    minFov: 40,
    maxFov: 100,
    // 调整移动速度
    moveSpeed: 5.0,
    // 自定义地面点位样式 (例如：只显示实心点)
    panoCircleMeshCreator: (observer, options) => {
      // 这里的 options 包含了 aerialObserverMinHeight 等信息
      return new PanoCircleMeshSolid({
        color: 0x3366ff, // 自定义颜色
        scale: 1.2       // 自定义大小
      });
    }
  },
  // 模型地图配置
  mapview: {
    // 设置默认进入时的视角参数
    defaultLatitude: Math.PI / 3, // 60度俯视
    defaultDistance: 200,         // 相机距离
  },
  // 模型漫游配置
  model: {
    moveSpeed: 10.0 // 模型模式下移动更快
  }
});
```

### 动态修改配置 (Update Configuration)

初始化后，可以使用 `five.updateConfiguration()` 动态修改各模式的配置参数，无需重新实例化。

```typescript
// 动态修改全景模式的移动速度和最大 FOV
five.updateConfiguration({
  panorama: {
    moveSpeed: 10.0,
    maxFov: 140
  }
});

// 动态修改模型地图模式的相机距离
five.updateConfiguration({
  mapview: {
    defaultDistance: 300
  }
});
```

### 进阶用法 (Advanced Usage)

使用 `changeMode` 精准控制切换过程，并监听完成时机：

```ts
import { Five, Mode } from '@realsee/five';

const five = new Five();

// ... 初始化 ...

// 定义一个切换模式的函数
async function switchMode(targetMode: Mode) {
  try {
    // changeMode 返回 Promise，resolve 时表示切换动画结束
    await five.changeMode(targetMode, undefined, {
        duration: 1000 // 动画时长 1000ms
    });
    console.log(`成功切换到 ${targetMode} 模式`);
  } catch (error) {
    console.error(`切换到 ${targetMode} 失败`, error);
  }
}

// 绑定按钮事件
document.querySelector('#btn-map').addEventListener('click', () => {
    switchMode('Mapview');
});
```

## Common Pitfalls

1.  **相机类型差异**：`Topview` 模式使用的是正交相机 (OrthographicCamera)，而其他模式使用的是透视相机 (PerspectiveCamera)。在进行自定义渲染或计算时需注意投影矩阵的差异。
2.  **切换动画**：`setState` 触发的切换动画是自动规划的，而 `changeMode` 允许更细粒度的控制。如果需要精确控制动画时长或回调，请使用 `changeMode`。
3.  **全景加载**：`Panorama` 模式下会自动使用瓦片（tile）方式加载全景图以平衡效率和清晰度，而其他模式（如 `Mapview`）主要展示模型几何。

## Related

*   [State - 状态](./state.md): 了解 Mode 在 State 中的位置及其他状态属性。
*   [Gesture - 手势](./gesture.md): 了解不同模式下的手势交互逻辑。
*   [Event - 事件](./event.md): 了解模式切换等相关事件。

---

```yaml
tags: [模式, 全景, 户型图, 鸟瞰, 漫游, 切换模式, 视角, mode, state, interaction, VR, panorama, floorplan, mapview, topview, model]
```