# State (状态)

- Summary: State 是 Five 的核心状态对象，描述了当前的显示模式、观察点位以及相机的空间姿态。
- Schema: 包含 Pose (相机姿态) 和 Mode (模式) 等属性的接口。
- Concepts: Camera Pose, Coordinate System, Mode Specifics。
- Examples: 状态获取与更新。

## Schema

> Definition: State

State 类型定义如下（继承自 `Pose`）：

    import * as THREE from "three";
    import { Mode } from "@realsee/five";

    interface Pose {
      /** 相机偏航角 (水平方向)，单位：弧度 */
      longitude: number;
      /** 相机俯仰角 (垂直方向)，单位：弧度 */
      latitude: number;
      /** 相机垂直视场角，单位：度 */
      fov: number;
      /** 相机看向的目标中心点坐标 */
      offset: THREE.Vector3;
      /** 相机距离目标中心点的距离 */
      distance: number;
    }

    interface State extends Pose {
      /** 显示模式 */
      mode: Mode;
      /** 当前点位的唯一标识 (workCode) */
      workCode: string;
      /** 当前点位在列表中的索引 */
      panoIndex: number;
    }

## Concepts

- Camera Pose (相机姿态): Five 使用球坐标系 (Spherical) + 笛卡尔偏移 (Cartesian Offset) 来描述相机位置。
  - 相机始终位于以 `offset` 为中心、`distance` 为半径的球面上。
  - longitude: 球面上的经度（水平旋转）。
  - latitude: 球面上的纬度（垂直旋转）。
  - offset: 相机“看向”的点，也是球心。
  - distance: 相机到 `offset` 的距离。
- Coordinate System (坐标系):
  - 采用 Y-Up 右手坐标系（与 Three.js 默认一致）。
  - 单位长度为米。
- Mode Specifics (模式特性):
  - Panorama: `distance` 通常为 0，即相机位置与 `offset` 重合（第一人称视角）。
  - Floorplan/Mapview: `offset` 通常位于模型中心，`distance` 大于模型包围盒半径（第三人称上帝视角）。
- State vs CurrentState:
  - five.state: 目标状态。表示相机最终应该到达的状态。当调用 `setState` 或用户交互结束时，此值即为最终结果。通常用于 UI 同步（如高亮当前模式按钮）。
  - five.getCurrentState(): 瞬时状态。表示当前渲染帧相机的实际状态。在动画过渡过程中，`currentState` 会不断变化直至追赶上 `state`。通常用于需要实时反馈的场景（如罗盘旋转）。

## Examples

### 快速上手 (Quick Example)

使用 `setState` 更新状态：

    // 切换到户型图模式，并旋转相机到 45 度
    five.setState({
      mode: 'Floorplan',
      longitude: Math.PI / 4
    });

### 详细示例 (Detailed Example)

获取当前状态并基于此修改：

    const state = five.state;

    // 在当前状态基础上，向右旋转 90 度，并略微拉远距离
    five.setState({
      longitude: state.longitude + Math.PI / 2,
      distance: state.distance + 2.0
    });

## Common Pitfalls

1. 单位混淆: `longitude` 和 `latitude` 使用弧度，而 `fov` 使用角度（度）。
2. Offset 类型: `offset` 必须是 `THREE.Vector3` 实例。如果在 React 等框架中使用纯对象（Plain Object），Five 内部会自动转换，但在 TypeScript 中需注意类型匹配。
3. 异步更新: `setState` 触发的相机运动是异步动画过程。如果需要立即无动画跳转，可传递第二个参数 `immediately: true`。
4. JSON 序列化: `State` 中的 `offset` 是 `THREE.Vector3` 实例，不能直接 `JSON.stringify`。保存时需手动提取 `{ x, y, z }`，恢复时需重新构造 `new THREE.Vector3(x, y, z)`。

    // 保存
    const snapshot = {
      ...five.state,
      offset: { x: five.state.offset.x, y: five.state.offset.y, z: five.state.offset.z }
    };
    localStorage.setItem('fiveState', JSON.stringify(snapshot));

    // 恢复
    const saved = JSON.parse(localStorage.getItem('fiveState')!);
    five.setState({
      ...saved,
      offset: new THREE.Vector3(saved.offset.x, saved.offset.y, saved.offset.z)
    }, true);

## Related

- Mode - 模式: 详细了解各种 Mode 的区别。
- Camera Animation: 基于 State 的相机动画控制。
- Five: Five 核心类，`setState` / `getCurrentState` 的宿主。
- Coordinate System: 坐标系定义。

    tags: [状态保存, 状态恢复, 场景还原, 快照, camera, state, pose, interaction, save, restore, snapshot]