@realsee/five 6.8.0-alpha.1 → 6.8.0-alpha.11

package/ai_guides/features/mode.md

@@ -0,0 +1,269 @@
+# 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]
+```

package/ai_guides/features/model.md

@@ -0,0 +1,186 @@
+# Model (模型)
+
+- **Summary**: Model 是 Five 中三维场景的核心实体，负责管理三维模型数据的加载、渲染和交互。
+- **Schema**: 继承自 THREE.Object3D，包含 ViewLayer 等子对象。
+- **Concepts**: ViewLayer, Parameter, 3DTile, five.ready()。
+- **Examples**: 模型操作与事件监听。
+
+## Schema
+
+### Model
+
+> **Definition**: [Model](../../five/model/model.d.ts)
+
+Model 类继承自 `THREE.Object3D`，是三维场景中的顶级对象。
+
+```typescript
+// 简化版定义，完整定义参考 lib/five/model/model.ts
+class Model extends THREE.Object3D {
+  /** 唯一标识 */
+  public fiveId: string;
+
+  /** 对应的 Work 数据 */
+  public work: Work;
+
+  /** 模型参数配置 */
+  public parameter: Parameter;
+
+  /** 包含的视图层 (如 mesh, point_cloud, gaussian_splatting) */
+  public viewLayers: ViewLayer[];
+
+  /** 是否加载完成 (初次加载) */
+  public loaded: boolean;
+
+  /** 是否细化完成 (高清纹理/模型加载完毕) */
+  public refined: boolean;
+
+  /** 细化进度 [当前, 总数] */
+  public refineProgress: [number, number];
+
+  /** 外包围盒 */
+  public boundingBox: THREE.Box3;
+
+  /** 楼层数量 */
+  public floorLength: number;
+}
+```
+
+> **refineProgress 说明**:
+> *   类型: `[number, number]`
+> *   含义: `[已处理的瓦片/纹理数量, 总瓦片/纹理数量]`。
+> *   用途: 用于计算模型加载/细化的百分比进度 (progress = current / total)。
+
+## Concepts
+
+### 1. `five.models` vs `five.model`
+
+*   **`five.models`**: 这是一个数组，返回当前场景中所有已加载的 `Model` 实例列表。
+*   **`five.model`**: 这是一个便捷属性，直接返回 `five.models[0]`。
+
+通常情况下，如果你只加载了一个 Work，可以直接使用 `five.model` 来操作当前模型。
+
+```typescript
+// 下面两种方式是等价的
+const model1 = five.models[0];
+const model2 = five.model;
+```
+
+### 2. Model vs Work
+
+*   **Work (数据)**: 它是静态的描述数据（JSON），包含了模型的下载地址（URL）、元数据（Metadata）、初始状态等。它是“菜谱”。
+*   **Model (实体)**: 它是运行时的三维对象（Object3D），包含了实际的几何体（Geometry）、材质（Material）和渲染状态。它是“菜肴”。
+
+关系：`five.load(work)` 过程就是根据 Work 数据创建 Model 实体的过程。
+
+### 3. ViewLayer 分层思想
+
+一个完整的 VR 模型通常由多个部分组成，Five 使用 **ViewLayer** 来管理这些分层。
+
+常见的 ViewLayer 类型：
+*   **`mesh` (网格层)**: 也就是可以看到的实体模型（墙面、地板等）。
+*   **`point_cloud` (点云层)**: 激光点云数据。它并非低精度数据，同样支持高精度的近距离观察，并支持碰撞检测。
+*   **`gaussian_splatting` (高斯泼溅层)**: 新一代三维重建渲染技术，用于展示极高真实感的场景细节。
+
+**层级结构**:
+Model 加载完成后，会自动根据 Work 数据生成对应的 ViewLayer，并挂载为 `Model` 的子对象。开发者可以通过 `model.viewLayers` 访问它们。
+
+```text
+Model (Object3D)
+  ├── ViewLayer (mesh)   -> 负责网格模型渲染
+  └── ViewLayer (point_cloud) -> 负责点云渲染
+```
+
+### 4. Parameter (简述)
+
+`Model` 实例上挂载了一个 `parameter` 对象（`five.models[0].parameter`）。
+它是专门用于控制 **模型渲染表现** 的配置器。
+
+*   **作用**: 控制模型的透明度、显示的楼层、相机裁剪范围等。
+*   **详情**: 详见 [Parameter](./parameter.md) (待创建)。
+
+### 5. 3DTile (简述)
+
+`ViewLayer` 的底层实现基于 **3DTile** 技术（类名为 `Tile3D`）。
+
+*   **作用**: 实现大规模三维数据的流式加载（LOD）。它能根据相机距离动态加载不同精度的模型块，保证渲染性能。
+*   **详情**: 详见 [3DTile](./3dtile.md) (待创建)。
+
+### 6. five.ready()
+
+`five.ready()` 是一个 Promise 方法，用于等待当前环境“准备就绪”。
+
+*   **对于 Model 模式**: 它会等待 Model 几何体加载完成（`model.loaded` 为 true）。
+*   **对于 Panorama 模式**: 它会等待全景图基本加载完成。
+
+推荐在执行截图、复杂的模型操作前，先 `await five.ready()`。
+
+### 7. 射线碰撞 (Raycaster)
+
+Model 提供了高效的射线检测方法 `intersectRaycaster`，内置了 BVH 加速，性能优于 Three.js 原生方法。
+
+*   **API**: `model.intersectRaycaster(raycaster: THREE.Raycaster): THREE.Intersection[]`
+*   **用途**: 鼠标点击拾取、视线检测、碰撞检测。
+*   **详情**: 详见 [Raycast](./raycast.md)。
+
+## Events
+
+Five 实例上会派发与 Model 相关的生命周期事件，开发者可以通过 `five.on()` 监听。
+
+| 事件名 | 说明 | 回调参数 |
+| :--- | :--- | :--- |
+| **`model.load`** | 单个 Model 几何体加载完成时触发。此时模型可见，但纹理可能模糊。 | `{ model: Model, work: Work }` |
+| **`models.refined`** | 所有 Model 的纹理细化完成（变清晰）时触发。 | `{ modelScene: ModelScene }` |
+| **`model.changeShownFloor`** | Model 的楼层显隐状态发生变化时触发。 | `{ model: Model, work: Work }` |
+| **`model.error`** | Model 加载出错时触发。 | `{ error: Error, model: Model, work: Work }` |
+
+## Examples
+
+### 获取并操作当前模型
+
+```typescript
+// 获取当前模型
+const model = five.models[0];
+
+if (model) {
+  console.log("模型对应 Work 名称:", model.work.name);
+  console.log("模型是否细化完成:", model.refined);
+
+  // 监听模型细化事件
+  five.on("model.refined", () => {
+    console.log("模型高清资源加载完毕");
+  });
+}
+```
+
+### 遍历 ViewLayer
+
+```typescript
+const model = five.models[0];
+// model.viewLayers 即为 ViewLayer 列表
+model.viewLayers.forEach((layer) => {
+  console.log(`图层名称: ${layer.name}, 类型: ${layer.type}`);
+
+  if (layer.type === 'mesh') {
+    // 对网格层做特殊处理
+    layer.visible = true;
+  }
+});
+```
+
+## Common Pitfalls
+
+1.  **直接修改 `model.children`**: 不要直接修改 `model.children` 数组。Model 的子对象是由 Five 内部管理的。如果需要隐藏某个图层，请设置 `layer.visible = false`。
+2.  **混淆 `five.model` 和 `five.work`**: `five.model` 是 Three.js 对象 (Object3D)，用于渲染；`five.work` 是数据对象，用于描述。
+
+## Related
+
+*   [Work](./work.md): 了解 Work 数据结构。
+*   [Parameter](./parameter.md): 了解模型参数配置。
+*   [3DTile](./3dtile.md): 了解 3DTile 技术。
+*   [Raycast](./raycast.md): 了解射线检测机制。
+
+---
+
+```yaml
+tags: [model, viewlayer, object3d]
+```

package/ai_guides/features/move-pano-effect.md

@@ -0,0 +1,145 @@
+# 全景切换效果 (Move Pano Effect)
+
+- **Summary**: 介绍 `moveToPano` 方法中 `effect` 和 `effectEasing` 参数的作用及使用方式，用于控制全景点位切换时的视觉过渡效果。
+- **Schema**: `MovePanoEffect` (枚举字符串), `MovePanoOptions` (接口).
+- **Concepts**: Effect Modes (切换模式), Easing Function (缓动函数), Blend Ratio (混合比例).
+- **Configuration**: `moveToPano` 的 `options` 参数.
+- **Examples**: 基础切换、自定义缓动函数.
+
+## Schema
+
+### MovePanoEffect
+
+> **Definition**: [MovePanoEffect](../../five/types/movePanoEffect.d.ts)
+
+`effect` 参数定义了全景切换的动画模式。
+
+```typescript
+type MovePanoEffect =
+  | "fly"      // 飞行效果 (默认)：模拟相机在空间中的移动
+  | "instant"  // 瞬间切换：无动画，直接跳变
+  | "fade"     // 淡入淡出：原场景渐隐，新场景渐现 (位置保持不变)
+  | "montage"  // 蒙太奇：通过黑屏过渡 (渐变穿插到黑屏再亮起)
+  | "spread"   // 扩散：新场景从中心向四周扩散
+  | "zoomin"   // 放大：新场景从小放大覆盖
+  | "zoomout"  // 缩小：原场景缩小消失
+  | "model";   // 模型过渡：切换过程中展示 3D 模型结构
+```
+
+### effectEasing
+
+`effectEasing` 是一个函数，用于控制前后全景图的混合进度。
+
+```typescript
+// 输入 0-1 的进度值，返回 0-1 的混合比例
+type EffectEasing = (progress: number) => number;
+```
+
+*   **输入 (Input)**: `progress` (0 到 1)，表示动画的时间进度。
+*   **输出 (Output)**: 混合比例 (0 到 1)。
+    *   `0`: 完全显示前一个全景图。
+    *   `1`: 完全显示后一个全景图。
+    *   `0.5`: 两个全景图各显示 50%。
+
+## Concepts
+
+### Effect Modes (切换模式)
+
+*   **Fly (飞行)**: 最常用的模式。相机在三维空间中真实移动，给用户强烈的空间位置感。适用于相邻或视线通透的点位切换。
+*   **Fade (渐变)**: 保持相机位置不变，仅改变图像透明度。适用于距离较远、不通视或空间关系不明确的点位切换，避免产生"穿墙"的违和感。
+*   **Model (模型)**: 在切换过程中淡入模型的线框或白模，强调空间结构。
+
+### Easing Function (缓动函数)
+
+默认情况下，混合比例与时间进度是线性的 (`y = x`)。通过自定义 `effectEasing`，可以实现非线性的混合效果。例如：
+
+*   **快速切入**: 开始时混合很快，后面变慢。
+*   **延迟切入**: 开始时保持原图较长时间，最后快速切换到新图。
+*   **特殊场景**: 如“地面-天空”切换，可能希望在特定的时间点才开始显示新图。
+
+## Examples
+
+### 1. 基础用法 (Basic Usage)
+
+使用不同的 `effect` 进行切换。
+
+```typescript
+// 1. 飞行模式 (默认)
+five.moveToPano(1, {
+  effect: 'fly',
+  duration: 1500
+});
+
+// 2. 瞬间切换 (无动画)
+five.moveToPano(2, {
+  effect: 'instant'
+});
+
+// 3. 淡入淡出 (适用于远距离切换)
+five.moveToPano(10, {
+  effect: 'fade',
+  duration: 1000
+});
+```
+
+### 2. 自定义缓动 (Custom Easing)
+
+使用 `effectEasing` 控制混合节奏。
+
+```typescript
+// 示例：Ease-In-Quad (先慢后快)
+function easeInQuad(x: number): number {
+  return x * x;
+}
+
+five.moveToPano(5, {
+  effect: 'fly',
+  duration: 2000,
+  // 自定义混合曲线
+  effectEasing: easeInQuad
+});
+```
+
+### 3. 高级缓动控制 (Advanced Easing)
+
+在某些特殊场景（如从地面点切换到航拍点），我们可能希望前 80% 的时间都显示地面点，最后 20% 才快速过渡到航拍图。
+
+```typescript
+five.moveToPano(aerialPanoIndex, {
+  effect: 'fly',
+  duration: 3000,
+  effectEasing: (progress) => {
+    // 0 - 0.8 期间返回 0 (显示原图)
+    // 0.8 - 1.0 期间线性过渡到 1
+    if (progress < 0.8) return 0;
+    return (progress - 0.8) / 0.2;
+  }
+});
+```
+
+## Configuration
+
+`moveToPano` 的第二个参数 `options` 支持以下配置：
+
+| 参数 | 类型 | 说明 | 默认值 |
+| :--- | :--- | :--- | :--- |
+| `effect` | `MovePanoEffect` | 切换效果模式 | `'fly'` |
+| `effectEasing` | `(p: number) => number` | 图片混合缓动函数 | `p => p` (线性) |
+| `duration` | `number` | 动画耗时 (ms) | 根据距离自动计算 |
+
+## Common Pitfalls
+
+1.  **Effect 适用性**: `fly` 效果虽然炫酷，但在穿过墙体或障碍物时可能会导致视觉上的“穿帮”。此时应优先考虑使用 `fade` 或 `model`。
+2.  **Easing 范围**: `effectEasing` 函数的返回值应严格控制在 `0` 到 `1` 之间。超出此范围可能会导致渲染异常（如过曝或反色）。
+3.  **Duration**: 如果 `duration` 设置为 `0`，无论 `effect` 是什么，效果都等同于 `instant`。
+
+## Related
+
+*   [Camera Animation](./camera-animation.md): 更多关于相机控制的说明。
+*   [Five](./five.md): Five 实例及 API。
+
+---
+
+```yaml
+tags: [move-pano-effect, camera-animation, pano-switch]
+```