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

Realsee Renderer SDK

# State (状态)

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

## Schema

> **Definition**: [State](../../five/types/state.d.ts)

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

```ts
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` 更新状态：

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

### 详细示例 (Detailed Example)

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

```ts
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)`。

```typescript
// 保存
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.md): 详细了解各种 Mode 的区别。
*   [Camera Animation](./camera-animation.md): 基于 State 的相机动画控制。
*   [Five](./five.md): Five 核心类，`setState` / `getCurrentState` 的宿主。
*   [Coordinate System](./coordinate-system.md): 坐标系定义。

---

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