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;
}
Copy

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
});
Copy

详细示例 (Detailed Example)

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

const state = five.state;

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

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);
Copy

Related

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

---

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