# Mode (模式)

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

## Schema

> Definition: Mode, FiveInitArgs

Mode 类型定义如下：

    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 (全景漫游)

    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 (模型地图)

    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 (模型户型)

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

### Topview (模型平面)

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

### Model (模型漫游)

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

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

### VRPanorama / XRPanorama (VR 模式)

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

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

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

## Examples

### 快速上手 (Quick Example)

使用 `setState` 切换模式：

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

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

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

    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()` 动态修改各模式的配置参数，无需重新实例化。

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

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

### 进阶用法 (Advanced Usage)

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

    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 - 状态: 了解 Mode 在 State 中的位置及其他状态属性。
- Gesture - 手势: 了解不同模式下的手势交互逻辑。
- Event - 事件: 了解模式切换等相关事件。

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