@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.31

package/ai_guides/features/camera-animation.md

@@ -10,6 +10,8 @@
 
 ### MovePanoOptions
 
+> **Definition**: [MovePanoOptions](../../five/types/movePanoOptions.d.ts)
+
 点位移动参数配置。
 
 ```typescript
@@ -18,8 +20,12 @@ interface MovePanoOptions extends Partial<Omit<State, "offset" | 'distance' | 'm
   effect?: MovePanoEffect;
   /** 走点图片过度策略 */
   effectEasing?: (progress: number) => number;
-  /** 运动耗时 (ms) */
-  duration?: number;
+  /**
+   * 运动耗时 (ms)
+   * - number: 固定时长
+   * - function: (distance, speed) => number 根据距离动态计算
+   */
+  duration?: number | ((distance: number, speed: number) => number) | string | null;
   /** 运动开始回调 */
   moveStartCallback?: (toState: State) => void;
   /** 运动结束回调 */
@@ -74,6 +80,21 @@ five.moveToPano(panoIndex: number, options?: MovePanoOptions): Promise<void>
 five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
 ```
 
+### 4. updateCamera
+
+在不切换全景点位的情况下，将相机平滑动画到目标位姿。适用于"定点环顾"或"聚焦某个方向"等场景。
+
+```typescript
+five.updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean): Promise<void>
+```
+
+*   `pose`: 目标位姿 (longitude, latitude, fov, offset, distance 等)。
+*   `duration`: 动画时长 (ms)。
+*   `userAction`: 是否标记为用户触发。
+*   **返回**: `Promise<void>`，动画完成时 resolve，被打断时 reject。
+
+> 与 `setState` 的区别：`updateCamera` 返回 Promise，可以精确等待动画结束；`setState` 是 fire-and-forget 风格。
+
 ## Concepts
 
 ### Pose (位姿)
@@ -92,9 +113,24 @@ five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
 
 ## Configuration
 
+### Global Configuration (全局配置)
+
 在 `new Five(config)` 初始化时可以设置全局动画参数：
 
-*   `modeChangeDuration`: 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。默认为 1000ms。
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `modeChangeDuration` | `number` | `1000` | 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。 |
+
+### MovePanoOptions Configuration (移动参数)
+
+调用 `five.moveToPano(index, options)` 时使用的配置参数：
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `effect` | `MovePanoEffect` | `'fly'` | 动画效果。<br>`'fly'`: 空间移动（模拟行走）；<br>`'fade'`: 淡入淡出（保持位置不变）；<br>`'instant'`: 瞬间跳转。 |
+| `duration` | `number` \| `Function` | - | 动画时长 (ms)。若不传，则根据距离和速度自动计算。 |
+| `effectEasing` | `Function` | - | 自定义过渡效果的缓动函数。 |
+| `moveEndCallback` | `Function` | - | 动画结束后的回调函数。 |
 
 ## Examples
 
@@ -176,9 +212,11 @@ function wait(ms: number) {
 *   [Five](./five.md): Five 核心类及 `setState` 方法。
 *   [Mode](./mode.md): 各种交互模式说明。
 *   [State](./state.md): 状态对象的完整定义。
+*   [Move Pano Effect](./move-pano-effect.md): 全景点位切换的过渡效果配置。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解 longitude/latitude 的含义。
 
 ---
 
 ```yaml
-tags: [camera-animation, pose, state]
+tags: [巡航, 动画, 旋转, 缩放, 运镜, 导览, camera-animation, pose, state, auto-tour, fly-through, rotate, zoom, transition]
 ```

package/ai_guides/features/clipper.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [PBMClipperParameter](../../five/model/materials/pbmMaterial.d.ts)
+
 ```typescript
 /** 模型裁切参数 */
 interface PBMClipperParameter {
@@ -124,10 +126,10 @@ function updateClipper(mesh: THREE.Mesh) {
 
 ## Related
 
-*   [model.md](./model.md): 模型模块概览。
+*   [Model](./model.md): 模型模块概览。
 
 ---
 
 ```yaml
-tags: [clipper, model, cut, discard, geometry]
+tags: [裁切, 剖面, 隐藏部分模型, 开盖, 房屋剖面, clipper, model, cut, discard, geometry, clipping-box, section-view]
 ```

package/ai_guides/features/{coordnate-system.md → coordinate-system.md}

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [TilesetHeader](../../five/model/tile3d/header.d.ts)
+
 ### RootMeta
 
 3D Tiles `rootMeta` 字段中定义的坐标系元数据。
@@ -37,6 +39,22 @@ interface Coordinate {
 
 ## Concepts
 
+### Overview (坐标系总览)
+
+Five 中涉及多个坐标系，它们在不同场景下各有用途。理解它们的关系是正确使用 Five 的关键。
+
+| 坐标系 | 上轴 | 适用场景 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **Local (Y-up)** | Y | 渲染场景、前端开发 | Five 的 `five.scene`、Observer 位置、`project2d` 等均使用此坐标系。与 Three.js 默认一致。 |
+| **ENU (Z-up)** | Z | 算法交互、后端接口、模型原始数据 | 测绘行业习惯。3D Tiles 数据源、`loadGltf` 等加载器默认输出 Z-up。 |
+| **ECEF** | - | RTK 定位、地球坐标 | 地心地固坐标系，用于包含 RTK 信息的模型。 |
+| **World** | Y | Three.js 世界坐标 | 通常等同于 Local，除非有 Object3D 层级嵌套偏移。 |
+
+> **关键区分**：
+> - **开发者在 `five.scene` 中操作的所有对象**（添加标签、射线检测结果、`project2d` 输入等）都处于 **Local (Y-up)** 坐标系。
+> - **模型数据源**（3D Tiles、PLY、GLTF 等文件）通常以 **ENU (Z-up)** 存储。Five 在加载时会自动将其旋转对齐到 Local (Y-up)。
+> - **与后端/算法交互**时，推荐使用 **ENU (Z-up)** 坐标系传输数据，通过 `viewLayer.localToEnu()` / `viewLayer.enuToLocal()` 进行转换。
+
 ### Local Coordinate System (Y-up)
 Five 的渲染场景 (`five.scene`) 和 Observers (观察点) 使用 **Y-up** (Y 轴向上) 的右手坐标系。
 这与 Three.js 的默认坐标系一致，便于前端开发和场景渲染。
@@ -62,6 +80,8 @@ Five 的渲染场景 (`five.scene`) 和 Observers (观察点) 使用 **Y-up** (Y
 3.  **自动对齐**: Five 加载模型时（load 方法），会自动处理旋转和坐标系转换，将其对齐到 Five 的 Local (Y-up) 坐标系中。
     - 开发者在 `five.scene` 中看到的所有模型都已处于统一的 Y-up 坐标系下。
 
+> **注意**: 外部模型加载函数（如 `loadGltf`, `loadPly` 等）的 `upAxis` 参数默认为 `'Z'`，表示输出的模型以 Z-up 存储。这是因为这些函数返回的是**原始模型对象**，尚未经过 Five 的自动对齐。当你通过 `five.load(work)` 加载 Work 数据时，Five 会自动完成 Z-up → Y-up 的转换。如果你手动使用 `loadGltf` 并添加到 `five.scene`，需要自行处理坐标系旋转。详见 [Load External Model](./load-external-model.md)。
+
 ### Coordinate in Files
 在 3D Tiles 的 `tileset.json` 中，`rootMeta` 字段用于描述坐标系转换信息（没有该字段则默认 Z-up）：
 - 包含 `pose_ecef_to_enu` 和 `pose_enu_to_ecef` 变换矩阵。
@@ -117,10 +137,10 @@ const displayPosition = viewLayer.ecefToLocal(ecefPosition.clone());
 
 ## Related
 
-*   [load-external-model.md](./load-external-model.md): 加载外部模型时的坐标轴配置 (`upAxis`, `modelUpAxis`)。
+*   [Load External Model](./load-external-model.md): 加载外部模型时的坐标轴配置 (`upAxis`, `modelUpAxis`)。
 
 ---
 
 ```yaml
-tags: [coordinate-system, enu, ecef, z-up, y-up, transform]
+tags: [坐标系, 坐标转换, 右手坐标系, 模型方向, 旋转, 地理坐标, coordinate-system, enu, ecef, z-up, y-up, transform, local, world, rtk]
 ```

package/ai_guides/features/event.md

@@ -1,12 +1,14 @@
 # Events (事件系统)
 
 - **Summary**: Five 提供了一套基于发布/订阅模式的事件系统，用于监听用户交互、状态变更、数据加载及渲染生命周期。
-- **Schema**: `on` / `once` / `off` 接口定义。
-- **Concepts**: Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.
-- **Examples**: 监听全景移动、手势交互及状态变更。
+- **Schema**: `on` / `once` / `off` 接口定义；`BaseEvent` / `BaseExtendableEvent` 事件对象。
+- **Concepts**: Event 对象（`preventDefault` / `waitUntil`）、Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.
+- **Examples**: 监听全景移动、手势交互及状态变更；使用 `preventDefault` 拦截默认行为；使用 `waitUntil` 延迟点位切换。
 
 ## Schema
 
+> **Definition**: [Five](../../five/application/five.d.ts), [EventTypes](../../five/application/events.d.ts)
+
 Five 实例提供了以下方法来管理事件监听：
 
 ### on
@@ -48,6 +50,101 @@ five.off(
 - **name**: (可选) 若不传，则清空所有事件；若传，则取消指定类型的事件。
 - **callback**: (可选) 若传，则仅取消该特定的回调函数；若不传，则取消该类型下的所有回调。
 
+## Event 对象
+
+> **Definition**: [BaseEvent / BaseExtendableEvent](../../five/utils/event.d.ts)
+
+Five 中所有事件回调的参数都是一个 Event 对象，分为两种基础类型：
+
+### BaseEvent
+
+所有事件的基础接口，包含以下属性和方法：
+
+```typescript
+interface BaseEvent {
+  /** 事件类型名称 */
+  type: string;
+  /** 事件触发时的时间戳 */
+  timeStamp: number;
+  /** 阻止事件的默认行为 */
+  preventDefault(): void;
+  /** 是否已调用过 preventDefault */
+  readonly defaultPrevented: boolean;
+}
+```
+
+### BaseExtendableEvent
+
+继承自 `BaseEvent`，额外提供 `waitUntil` 方法，用于在事件处理中插入异步等待逻辑：
+
+```typescript
+interface BaseExtendableEvent extends BaseEvent {
+  waitUntil(f: Promise<any>): void;
+}
+```
+
+目前 `pano.prepare` 事件使用 `BaseExtendableEvent`（对应 `PanoPrepareEvent`），其余事件均基于 `BaseEvent`。
+
+### preventDefault
+
+调用 `event.preventDefault()` 可以阻止事件的默认行为。Five 内部会在触发事件后检查 `event.defaultPrevented`，若为 `true` 则跳过后续的默认处理逻辑。
+
+比如：
+- `gesture.tap`：阻止默认的点位跳转或相机弹跳动画。
+- `intersect.update`：阻止默认的交互高亮行为。
+
+```typescript
+// 示例：阻止点击时的默认点位跳转
+five.on("gesture.tap", (event) => {
+  if (shouldBlockNavigation()) {
+    event.preventDefault();
+    // 执行自定义逻辑
+    showCustomMenu(event);
+  }
+});
+
+// 示例：阻止拖拽时的默认相机旋转
+five.on("gesture.pan", (event) => {
+  event.preventDefault();
+  // 用拖拽手势实现自定义交互（如绘制标注）
+  drawAnnotation(event);
+});
+```
+
+### waitUntil
+
+`waitUntil(promise)` 仅在 `ExtendableEvent` 上可用。调用后，Five 会等待传入的 Promise 完成后再继续后续流程。可多次调用，所有 Promise 会被并行等待。
+
+目前仅 `pano.prepare` 事件支持 `waitUntil`。
+
+```typescript
+// 示例：在切换点位前预加载资源
+five.on("pano.prepare", (event) => {
+  // 等待自定义资源加载完成后再继续点位切换
+  event.waitUntil(
+    loadCustomResources(event.pano)
+  );
+
+  // 可以多次调用，所有 Promise 会被并行等待
+  event.waitUntil(
+    preloadTextures(event.pano)
+  );
+});
+
+// 示例：通过 waitUntil reject 来取消走点
+five.on("pano.prepare", (event) => {
+  event.waitUntil(
+    showConfirmDialog("是否前往该点位？").then((confirmed) => {
+      if (!confirmed) {
+        throw new Error("用户取消走点");
+      }
+    })
+  );
+});
+```
+
+> **注意**: `preventDefault` 和 `waitUntil` 必须在事件回调的同步执行阶段调用，不能放在 `await` 之后。
+
 ## Concepts
 
 Five 的事件系统将事件主要分为以下几类：
@@ -66,6 +163,7 @@ Five 的事件系统将事件主要分为以下几类：
 ### Pano Events (全景导航)
 监听全景图的点位切换过程。
 
+- `pano.prepare`: 准备切换到新点位。这是一个 `ExtendableEvent`，支持通过 `waitUntil(promise)` 延迟后续加载流程（如预加载资源），以及通过 `preventDefault()` 取消本次走点。
 - `pano.arrived`: 成功到达新点位（移动动画结束）。
 - `pano.moving`: 正在移动到新点位（动画进行中）。
 - `pano.willChange`: 即将发生点位变更（旧版兼容）。
@@ -103,13 +201,13 @@ import { Five } from "@realsee/five";
 const five = new Five();
 
 // 监听点击事件
-five.on("gesture.tap", (pose) => {
-  console.log("User tapped at:", pose);
+five.on("gesture.tap", (event) => {
+  console.log("User tapped at:", event);
 });
 
 // 监听点位变更完成
-five.on("pano.arrived", (index) => {
-  console.log("Arrived at pano index:", index);
+five.on("pano.arrived", (event) => {
+  console.log("Arrived at pano:", event.pano);
 });
 ```
 
@@ -142,11 +240,11 @@ five.on("render", onRender);
 
 ## Related
 
-- [state.md](./state.md): 了解 State 的结构与变更机制。
-- [five.md](./five.md): Five 核心类说明。
+- [State](./state.md): 了解 State 的结构与变更机制。
+- [Five](./five.md): Five 核心类说明。
 
 ---
 
 ```yaml
-tags: [events, interaction, lifecycle, gesture, state]
+tags: [事件监听, 点击, 拖拽, 加载完成, 渲染回调, 生命周期, 回调, events, interaction, lifecycle, gesture, state, preventDefault, waitUntil, on, off, subscribe]
 ```

package/ai_guides/features/five.md

@@ -9,6 +9,9 @@
 ## Schema
 
 ### FiveInitArgs
+
+> **Definition**: [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
 `new Five(args)` 的初始化参数对象。
 
 ```typescript
@@ -64,7 +67,7 @@ Five 内部维护了一个 `requestAnimationFrame` 循环。
 
 | 参数 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
-| `imageOptions` | `ImageOptions` | `{}` | 图片加载策略，详见 [image-options.md](./image-options.md) |
+| `imageOptions` | `ImageOptions` | `{}` | 图片加载策略，详见 [Image Options](./image-options.md) |
 | `textureOptions` | `TextureOptions` | `{}` | 贴图加载策略，同上 |
 | `onlyRenderIfNeeds` | `boolean` | `true` | 是否仅在需要时渲染，建议保持 `true` |
 | `antialias` | `boolean` | `false` | 抗锯齿，开启会增加性能消耗 |
@@ -141,40 +144,41 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 
 ### 实例属性 (Instance Properties)
 
-- **`work`**: 当前加载的 Work 数据（主 Work）。详见 [work.md](./work.md)。
-- **`works`**: 当前加载的所有 Work 数据列表。详见 [work.md](./work.md)。
-- **`model`**: 当前加载的 Model 数据（主 Model）。详见 [model.md](./model.md)。
-- **`models`**: 当前加载的所有 Model 数据列表。详见 [model.md](./model.md)。
+- **`work`**: 当前加载的 Work 数据（主 Work）。详见 [Work](./work.md)。
+- **`works`**: 当前加载的所有 Work 数据列表。详见 [Work](./work.md)。
+- **`model`**: 当前加载的 Model 数据（主 Model）。详见 [Model](./model.md)。
+- **`models`**: 当前加载的所有 Model 数据列表。详见 [Model](./model.md)。
 
 ### 实例方法 (Instance Methods)
 
 - **`appendTo(element: HTMLElement)`**: 将 canvas 挂载到指定 DOM 元素。
-- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [work.md](./work.md)。
+- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [Work](./work.md)。
 - **`dispose()`**: 销毁实例，释放 WebGL 上下文与内存。
 - **`updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean)`**: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。
 - **`updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)`**: 通过关键帧动画移动相机。
 - **`refresh()`**: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。
 - **`getPixels(x, y, width, height, ...)` / `getPixels(options)`**: 获取画布指定区域的像素数据。常用于截图、生成缩略图或颜色拾取。支持配置区域、像素比 (pixelRatio)、Y轴翻转 (flipY) 及是否忽略全景图 (skipPanorama) 等。
+- **`project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null`**: 计算三维坐标对应到屏幕的二维坐标。如果坐标在视野外或被遮挡（开启 testModel 时），返回 null。详见 [Screen Project](./screen-project.md)。
 - **`ready(args?: { tile?: boolean })`**: Promise，当 Five 状态稳定时 resolve。
   - **Resolve 时机**：
     1. **状态同步**：相机姿态已通过动画过渡到目标状态（`stateSynced` 为 true）。
     2. **模型加载**：如果是 Floorplan/Topview/Mapview/Model 模态，需等待模型加载完成 (`modelScene.loaded`)。
     3. **瓦片加载**：如果是 Panorama 模态且传入了 `{ tile: true }`，需等待当前视角的瓦片加载完成。
-- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
-- **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [event.md](./event.md)。
+- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [State](./state.md)。
+- **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [Event](./event.md)。
 
 ## Related
 
-*   [work.md](./work.md): Work 数据结构说明。
-*   [model.md](./model.md): Model 数据结构说明。
-*   [state.md](./state.md): 状态管理详解。
-*   [event.md](./event.md): 事件系统说明。
-*   [image-options.md](./image-options.md): 图片加载配置。
-*   [mode.md](./mode.md): 模态切换说明。
-*   [parameter.md](./parameter.md): 其他核心参数。
+*   [Work](./work.md): Work 数据结构说明。
+*   [Model](./model.md): Model 数据结构说明。
+*   [State](./state.md): 状态管理详解。
+*   [Event](./event.md): 事件系统说明。
+*   [Image Options](./image-options.md): 图片加载配置。
+*   [Mode](./mode.md): 模态切换说明。
+*   [Parameter](./parameter.md): 其他核心参数。
 
 ---
 
 ```yaml
-tags: [five, initialization, core, instance, lifecycle]
+tags: [初始化, 创建实例, 渲染器, 销毁, 入口, 构造函数, five, initialization, core, instance, lifecycle, canvas, appendTo, dispose]
 ```