@realsee/five-webgpu 1.0.0-alpha.1

package/ai_guides/api.md

@@ -0,0 +1,274 @@
+# Five SDK API Reference
+
+This document provides a summary of the core API for the Five SDK, designed to be easily understood by AI assistants.
+
+## Core Class: `Five`
+
+The `Five` class is the main entry point for the SDK. It manages the rendering, state, and interaction of the 3D scene.
+
+### Constructor
+
+```typescript
+const five = new Five(initArgs?: FiveInitArgs);
+```
+
+### Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `five.state` | `State` | The current state (mode, position, etc.) of the instance. |
+| `five.currentMode` | `Mode` | Shortcut to get the current display mode. |
+| `five.panoIndex` | `number` | Shortcut to get the current panorama index. |
+| `five.work` | `Work` | The currently loaded work data. |
+| `five.model` | `Model` | The 3D model object. |
+| `five.scene` | `THREE.Scene` | The Three.js scene used for non-model elements. |
+| `five.modelScene` | `ModelScene` | The Three.js scene used for the model. |
+| `five.camera` | `Camera` | The internal camera. |
+| `five.renderer` | `THREE.WebGLRenderer` | The WebGL renderer. |
+| `five.needsRender` | `boolean` | Set to `true` to request a render frame in the next loop. |
+| `five.plugins` | `Object` | Access to registered plugins. |
+
+### Static Properties
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `Five.Mode` | `Enum` | Available modes: `Panorama`, `Model`, `Floorplan`, `Topview`, `Mapview`, `VRPanorama`, `XRPanorama`. |
+
+## Initialization Configuration (`FiveInitArgs`)
+
+Configuration object passed to the `Five` constructor.
+
+```typescript
+interface FiveInitArgs {
+  /** External WebGLRenderer. If provided, internal renderer creation is skipped. */
+  renderer?: THREE.WebGLRenderer;
+
+  /** Width/Height of the viewport relative to container (0-1). */
+  viewport?: { left: number; bottom: number; width: number; height: number };
+
+  /** Canvas background color. Default: 0x181A1C */
+  backgroundColor?: number | THREE.Color;
+
+  /** Canvas background alpha (0-1). Default: 1 */
+  backgroundAlpha?: number;
+
+  /** Enable antialiasing. Default: false */
+  antialias?: boolean;
+
+  /** Auto-play rendering loop. Default: true */
+  play?: boolean;
+
+  /** Enable on-demand rendering to save battery. Default: true */
+  onlyRenderIfNeeds?: boolean;
+
+  /** Max FPS limit. false = unlimited. Default: false */
+  maxFps?: number | false;
+
+  /** Mode transition duration in ms. Default: 800 */
+  modeChangeDuration?: number;
+
+  /** Initial plugins to load. */
+  plugins?: FivePlugin[];
+
+  /** Dynamic image configuration for optimization. */
+  imageOptions?: ImageOptions;
+
+  /** Dynamic texture configuration for optimization. */
+  textureOptions?: TextureOptions;
+}
+```
+
+## Core Methods
+
+### `load(work, state?, options?)`
+Loads a "Work" (dataset) into the Five instance.
+
+- **work**: The data object (`LooseWork` or `Work`) containing scene information.
+- **state**: Initial state overrides. `"inherit"`, `"initial"`, or a `State` object.
+- **options**: Loading options (e.g., transition duration).
+
+### `appendTo(element, size?)`
+Mounts the Five canvas to a DOM element.
+
+- **element**: HTMLElement to append to.
+- **size**: Optional `{ width, height }`. Defaults to element size.
+
+### `setState(state, immediately?, userAction?)`
+Updates the current state (position, mode, etc.).
+
+- **state**: Partial `State` object to merge.
+- **immediately**: If `true`, skips animation.
+- **userAction**: Marks the change as triggered by user interaction.
+
+### `changeMode(mode, state?, options?)`
+Switches the viewing mode (e.g., from `Panorama` to `Model`).
+
+- **mode**: Target `Five.Mode`.
+- **state**: Target state after mode change.
+- **options**: Animation duration and effect.
+
+### `moveToPano(panoIndex, options?)`
+Moves to a specific panorama spot.
+
+- **panoIndex**: Index of the panorama.
+- **options**: `{ effect?: MovePanoEffect, duration?: number }`.
+
+### `refresh(size?)`
+Resizes the renderer to fit the container or specified size.
+
+### `getElement()`
+Returns the `<canvas>` element used by Five.
+
+### `project2d(vector, testModel?)`
+Projects a 3D point to 2D screen coordinates.
+
+- **vector**: `THREE.Vector3` (World Space).
+- **testModel**: `boolean` (default `false`). If `true`, checks for occlusion.
+- **returns**: `THREE.Vector2` (Screen Space, px) or `null`.
+
+### `getPixels(x, y, width, height)`
+Get pixel data from the renderer (e.g. for color picking or magnifier).
+
+- **x, y**: Coordinate of the lower-left corner (Screen Space).
+- **width, height**: Size of the rectangle.
+- **returns**: `Uint8Array` (RGBA data).
+
+### `intersectRaycaster(raycaster)`
+(On `five.model`) Performs raycasting against the scene models.
+
+- **raycaster**: `THREE.Raycaster`.
+- **returns**: `THREE.Intersection[]`.
+
+### `addPass(pass)`
+Add a post-processing pass to the rendering chain.
+
+- **pass**: `FivePass` instance (e.g. `Gaussian Blur Pass`).
+
+### `removePass(pass)`
+Remove a post-processing pass from the rendering chain.
+
+- **pass**: `FivePass` instance to remove.
+
+### `dispose()`
+Destroys the Five instance and releases resources.
+
+## State Management
+
+The `State` interface defines the complete status of the Five instance at any moment.
+
+```typescript
+interface State {
+  mode: Mode;          // Current view mode
+  panoIndex: number;   // Current panorama index
+  workCode: string;    // ID of the current work
+  latitude: number;    // Camera latitude (radians)
+  longitude: number;   // Camera longitude (radians)
+  distance: number;    // Camera distance from target
+  fov: number;         // Field of view
+  offset: THREE.Vector3; // Camera target offset
+}
+```
+
+## Data Structures
+
+### `Work`
+The main data object containing the scene description.
+
+```typescript
+interface Work {
+  workCode: string;          // Unique identifier
+  name: string;             // Project name
+  observers: WorkObserver[]; // List of panorama points
+  model: WorkModel;          // 3D model data
+  initial: WorkInitial;      // Initial view state
+  transform: THREE.Matrix4;  // World transform matrix
+}
+```
+
+### `WorkObserver` (Panorama Point)
+Represents a single panorama spot.
+
+```typescript
+interface WorkObserver {
+  index: number;             // Index in the list
+  floorIndex: number;        // Floor number
+  position: THREE.Vector3;   // Position in 3D space
+  quaternion: THREE.Quaternion; // Rotation relative to model
+  accessibleNodes: number[]; // Indices of reachable points
+  images: WorkImage;         // Panorama image URLs
+  active: boolean;           // Whether the point is enabled
+
+  // Coordinate Methods
+  getWorldPosition(): THREE.Vector3;
+  getWorldStandingPosition(): THREE.Vector3;
+
+  // UV Conversion Methods
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [CubeFace, THREE.Vector2];
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+}
+```
+
+## Events
+
+`Five` extends `Subscribe`, allowing event listening via `.on()`, `.once()`, and `.off()`.
+
+The SDK provides a modern event system (dot-notation, e.g., `gesture.tap`) which is recommended over the legacy system (camelCase, e.g., `wantsTapGesture`).
+
+### Recommended Events (Modern)
+
+These events follow a standard naming convention and provide typed event objects.
+
+#### Interaction & Gestures
+
+| Event Name | Description | Payload |
+| :--- | :--- | :--- |
+| `gesture.tap` | Triggered on tap/click. Replaces `wantsTapGesture`. | `{ pointers, event, ... }` |
+| `gesture.pan` | Triggered on pan/drag. | `{ pointers, ... }` |
+| `gesture.pinch` | Triggered on pinch/zoom. | `{ scale, ... }` |
+| `gesture.press` | Triggered on long press. | `{ pointers, ... }` |
+
+#### State & Mode
+
+| Event Name | Description | Payload |
+| :--- | :--- | :--- |
+| `mode.change` | Triggered when mode changes. | `ModeChangeEvent` |
+| `state.change` | Triggered when state changes (frequent). | `StateEvent` |
+| `camera.update` | Triggered when camera pose updates. | `CameraEvent` |
+
+#### Lifecycle & Resources
+
+| Event Name | Description | Payload |
+| :--- | :--- | :--- |
+| `works.load` | Triggered when work data starts loading. | `WorksEvent` |
+| `models.load` | Triggered when models are loaded. | `ModelSceneEvent` |
+| `model.tileLoad` | Triggered when a 3D tile is loaded. | `Tile` |
+| `model.tileUnload` | Triggered when a 3D tile is unloaded. | `Tile` |
+| `pano.arrived` | Triggered when arrival at a panorama node. | `PanoEvent` |
+| `pano.texture.progress` | Triggered when panorama texture loading progresses. | `{ progress, panoIndex }` |
+| `render` | Triggered after each render frame. | `RenderEvent` |
+| `error` | Triggered on internal errors. | `Error` |
+
+### Legacy Events (Deprecated)
+
+Older events are still supported for compatibility but should be avoided in new code.
+
+| Legacy Event | Recommended Replacement | Notes |
+| :--- | :--- | :--- |
+| `wantsTapGesture` | `gesture.tap` | |
+| `wantsPanGesture` | `gesture.pan` | |
+| `modelLoaded` | `models.load` | |
+| `initAnimationEnded` | `mode.change` | Check payload for details |
+
+### Usage Example
+
+```typescript
+// Recommended: Use the new event system
+five.on('gesture.tap', (event) => {
+  console.log('User tapped at:', event);
+});
+
+// Legacy (Avoid):
+// five.on('wantsTapGesture', (raycaster) => { ... });
+```

package/ai_guides/features/3dtile.md

@@ -0,0 +1,172 @@
+# 3DTile (3D 瓦片)
+
+- **Summary**: Five 用于加载和渲染大规模三维场景的核心模块，支持动态 LOD 调度与流式加载。
+- **Schema**: 对应 `ParameterTilesetValue` 接口，通过 Parameter 配置 LOD、显存与并发控制。
+- **Concepts**: LOD (细节层级), SSE (屏幕空间误差), Cache Management (显存管理), ViewLayer (视图层)。
+- **Configuration**: 包含画质精度、显存配额、几何误差、并发请求等详细参数。
+- **Examples**: 画质平衡与多图层优化。
+
+## Schema
+
+> **Definition**: [ParameterTilesetValue](../../five/model/parameter.d.ts)
+
+以下是 `ParameterTilesetValue` 的 TypeScript 定义摘要：
+
+```typescript
+export interface ParameterTilesetValue {
+  /** 屏幕空间误差阈值 (像素) */
+  maxScreenSpaceError: number;
+  /** 最大显存占用 (MB) */
+  maxMemoryUsage: number;
+  /** 最小几何误差 (精度上限锁) */
+  minGeometricError: number;
+  // ... 更多字段见下方配置表
+}
+```
+
+## Concepts
+
+### 1. LOD & Screen Space Error (SSE)
+
+LOD (Level of Detail) 是 3DTile 的核心机制。引擎不会一次性加载整个从宏观到微观的所有模型数据，而是根据相机位置动态计算每个瓦片的 **屏幕空间误差 (SSE)**。
+
+*   **Geometric Error (几何误差)**: 3D Tiles 数据源中定义的指标（单位：米），表示当前瓦片与真实物体之间的最大形状差异。
+    *   **根节点**: 误差巨大（如 100米），仅有模糊轮廓。
+    *   **叶子节点**: 误差极小（如 0.01米），细节丰富。
+*   **SSE 计算逻辑**: `SSE = (GeometricError / DistanceToCamera) * ScreenHeight`。
+*   **判定标准**: 如果 `SSE > maxScreenSpaceError`，说明当前瓦片在屏幕上看起来太粗糙（误差像素太大），需要分裂并加载下一级子瓦片；反之则停止细分。
+*   **调整影响**: 调低 `maxScreenSpaceError` 会迫使引擎加载更深层级的瓦片，从而获得更清晰的细节，但也会急剧增加渲染三角形数量和显存占用。
+
+### 2. 显存管理 (Cache Management)
+
+为了在浏览器有限的资源下渲染海量数据（如城市级倾斜摄影），3DTile 实现了基于 LRU (Least Recently Used) 的缓存淘汰机制和动态画质调整策略。
+
+*   **LRU 淘汰**: 当 `maxMemoryUsage` 超限时，引擎会优先保留当前视锥体内的瓦片。视锥体外的、或者距离相机较远的瓦片会被优先释放。
+*   **动态画质调整 (Dynamic Scaling)**: 如果开启了 `memoryAdjustedScreenSpaceError`，引擎会以 `maxMemoryUsage` 为目标，实时调整 SSE。
+    *   **目标**: 尽量跑满 `maxMemoryUsage` 设定的显存额度，不浪费资源。
+    *   **范围**: 实际 SSE 会在 `1.0` (极高画质) 到 `maxScreenSpaceError` (设定底线) 之间波动。
+    *   **场景**: 适合显存充足但希望自动平衡画质的场景。
+
+### 3. ViewLayer 与 3DTile
+
+目前所有的 `ViewLayer` 在底层都是一个 `Tile3D` 实例。它们各自拥有独立的：
+*   **配置**: `maxScreenSpaceError`, `maxMemoryUsage` 等参数互不干扰。
+*   **缓存**: 显存配额各自独立计算。
+
+> **注意**: 即使是通过 `file_url` 加载的单体模型（如 `.obj`, `.at3d`），在 Five 内部也会被封装为 `Tile3D` 实例进行统一管理。
+
+## Configuration
+
+以下表格列出了控制 3DTile 加载与性能调度的所有可用参数。
+
+### Core Quality & Performance (核心画质与性能)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxScreenSpaceError` | `number` | `16` | **核心参数**。屏幕空间误差阈值 (像素)。<br>值越小画质越高，性能开销越大。建议范围 8-32。 |
+| `maxMemoryUsage` | `number` | `512` | 最大显存占用 (MB)。超限后自动触发 LRU 淘汰机制。 |
+| `memoryAdjustedScreenSpaceError` | `boolean` | `false` | 是否开启基于内存的动态 SSE 调整。<br>开启后引擎会自动调整 SSE 以尽量占满显存配额。 |
+| `cameraCulling` | `boolean` | `true` | 是否开启视锥体剔除 (不加载视野外的瓦片)。**建议始终开启**。 |
+
+### Geometric Error Control (几何误差控制)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `minGeometricError` | `number` | `0` | 最小几何误差 (精度上限锁)。<br>当瓦片误差小于此值时停止细分。可用于限制过高精度的加载。 |
+| `maxGeometricError` | `number` | `10000` | 最大几何误差 (最低精度保证)。<br>强制细分直到误差小于此值。可用于避免模型过于模糊。 |
+
+### Network & Loading (网络与加载)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxRequests` | `number` | `4` | 最大并发请求数。建议保持默认，避免网络拥堵。 |
+| `requestOrder` | `string` | `'SCREEN_SPACE_ERROR'` | 请求优先级策略。<br>`'SCREEN_SPACE_ERROR'`: 优先加载 SSE 大的瓦片；<br>`'SCREEN_LEVEL_VERTICAL'`: 优先加载垂直层级高的。 |
+| `loadSiblings` | `boolean` | `true` | 是否预加载兄弟节点。 |
+| `skipLevelOfDetail` | `boolean` | `false` | 是否允许跳级加载 (跳过中间层级直接加载高精瓦片)。 |
+
+### Legacy LOD Control (不推荐)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `minLevelOfDetail` | `number` | `0` | 最小 LOD 层级 (Tree Depth)。建议使用 `maxGeometricError` 替代。 |
+| `maxLevelOfDetail` | `number` | `20` | 最大 LOD 层级 (Tree Depth)。建议使用 `minGeometricError` 替代。 |
+
+## Examples
+
+### 1. Adjusting Quality & Memory (调整画质与内存平衡)
+
+在移动端或性能受限设备上，建议适当降低画质以保证流畅度。
+
+```typescript
+const parameter = five.modelScene.parameter;
+
+// 1. 性能优先模式 (适用于低端设备)
+// 增大 SSE 阈值，降低画质
+parameter.set('maxScreenSpaceError', 16);
+// 限制显存，防止 Crash
+parameter.set('maxMemoryUsage', 256);
+
+// 2. 画质优先模式 (适用于桌面端/截图)
+// 减小 SSE 阈值，提升细节
+parameter.set('maxScreenSpaceError', 4);
+// 允许更多显存占用
+parameter.set('maxMemoryUsage', 1024);
+
+// 3. 重置为默认
+parameter.reset('maxScreenSpaceError', 'maxMemoryUsage');
+```
+
+### 2. Multi-ViewLayer Optimization (多 ViewLayer 优化)
+
+在对比查看或多楼层场景中，通常存在多个 `ViewLayer`。为了避免资源竞争，建议对非焦点的 ViewLayer 进行降级处理。
+
+```typescript
+// 假设 viewLayerA 是当前主要查看的模型，viewLayerB 是背景参考
+
+// 聚焦 ViewLayerA: 正常画质
+viewLayerA.parameter.reset('maxScreenSpaceError');
+
+// 降级 ViewLayerB: 仅显示轮廓，节省资源
+viewLayerB.parameter.set('maxScreenSpaceError', 48); // 极低画质
+viewLayerB.parameter.set('maxMemoryUsage', 128);     // 极低显存配额
+```
+
+## Debugging
+
+在开发过程中，可以通过访问 `ViewLayer` 内部的 `tileset` 对象来实时监控渲染状态。
+
+```typescript
+// 假设已获取 viewLayer 实例
+const tileset = viewLayer.tileset;
+
+// 1. 查看当前加载的瓦片数量
+console.log(tileset.loadedTiles.size);
+
+// 2. 查看当前实际生效的 SSE (如果开启了动态调整，此值会波动)
+console.log(tileset.currentMaxScreenSpaceError);
+
+// 3. 查看显存占用 (近似值，单位字节)
+// 注意: 这是内部私有属性，仅供调试参考
+console.log((tileset as any).cacheMemoryUsageInBytes / 1024 / 1024 + ' MB');
+```
+
+## Common Pitfalls
+
+1.  **误解 GeometricError 作用域**: `minGeometricError` 和 `maxGeometricError` 是**全局硬约束**，不随相机距离变化。
+    *   错误设置（例如将 `maxGeometricError` 设得极小）会强制全场景所有瓦片（哪怕是远处的背景）都加载到极高精度。
+    *   这会导致三角形数量和显存占用**指数级爆炸**，瞬间卡死浏览器。
+2.  **过度降低 `maxScreenSpaceError`**: 设置过小（如 < 4）可能导致每帧需要加载和渲染的三角形数量指数级上升，瞬间撑爆显存或导致掉帧。
+3.  **忽略 `cameraCulling`**: 默认应该开启。如果手动关闭视锥体剔除，引擎将尝试加载全场景数据，极易导致崩溃。
+4.  **频繁切换配置**: `maxMemoryUsage` 等参数的修改会触发缓存整理，高频修改可能导致卡顿。
+
+## Related
+
+*   [Parameter](./parameter.md): 了解参数的继承关系及材质、点云相关配置。
+*   [Model](./model.md): 了解 Model 和 ViewLayer 的关系。
+*   [Work](./work.md): 了解 Work 数据结构。
+
+---
+
+```yaml
+tags: [3dtile, viewLayer, performance, lod, optimization]
+```

package/ai_guides/features/camera-animation.md

@@ -0,0 +1,205 @@
+# 相机动画 (Camera Animation)
+
+- **Summary**: 介绍如何在 Five 中通过编程方式控制相机运动，包括旋转、位移、全景切换以及模态转换时的动画效果。
+- **Schema**: `State` (状态), `MovePanoOptions` (移动参数)。
+- **Concepts**: Pose (位姿), Animation Loop, Easing (缓动), Fly/Fade Effect。
+- **Configuration**: `modeChangeDuration`, `movePanoOptions`。
+- **Examples**: 旋转视角、切换全景点、模态切换动画。
+
+## Schema
+
+### MovePanoOptions
+
+> **Definition**: [MovePanoOptions](../../five/types/movePanoOptions.d.ts)
+
+点位移动参数配置。
+
+```typescript
+interface MovePanoOptions extends Partial<Omit<State, "offset" | 'distance' | 'mode'>> {
+  /** 动画效果: 'fly' | 'fade' | 'instant' ... */
+  effect?: MovePanoEffect;
+  /** 走点图片过度策略 */
+  effectEasing?: (progress: number) => number;
+  /**
+   * 运动耗时 (ms)
+   * - number: 固定时长
+   * - function: (distance, speed) => number 根据距离动态计算
+   */
+  duration?: number | ((distance: number, speed: number) => number) | string | null;
+  /** 运动开始回调 */
+  moveStartCallback?: (toState: State) => void;
+  /** 运动结束回调 */
+  moveEndCallback?: (state: State) => void;
+  /** 运动被取消回调 */
+  moveCancelCallback?: () => void;
+}
+```
+
+### MovePanoEffect
+
+```typescript
+type MovePanoEffect =
+  | "fly"     // 通过相机移动方式变化 (默认)
+  | "instant" // 直接变化 (无动画)
+  | "fade"    // 通过渐变方式变化
+  | "model";  // 通过过度到模型
+```
+
+## Core Methods (核心方法)
+
+Five 提供了多种层级的 API 来控制相机动画。
+
+### 1. setState
+
+最通用的状态更新方法。可以通过修改 `longitude` / `latitude` (旋转) 或 `fov` (缩放) 来产生动画。
+
+```typescript
+five.setState(state: Partial<State>, immediately?: boolean): void
+```
+
+*   `state`: 目标状态 (包含 mode, panoIndex, longitude, latitude, fov 等)。
+*   `immediately`: 是否立即跳转 (无动画)。默认为 `false` (有动画)。
+
+### 2. moveToPano
+
+专用于全景点位之间的切换。支持 "飞行" (Fly) 和 "渐变" (Fade) 两种效果。
+
+```typescript
+five.moveToPano(panoIndex: number, options?: MovePanoOptions): Promise<void>
+```
+
+*   `options.effect`: 切换效果。`'fly'` (空间飞行) 或 `'fade'` (淡入淡出)。
+*   `options.duration`: 动画时长 (ms)。
+*   `options.moveEndCallback`: 动画结束回调。
+
+### 3. changeMode
+
+切换交互模式 (如从全景切换到模型鸟瞰)。
+
+```typescript
+five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
+```
+
+## Concepts
+
+### Pose (位姿)
+
+相机的状态主要由位姿描述：
+
+*   **Longitude (经度)**: 水平旋转角度 (0 - 2π)。
+*   **Latitude (纬度)**: 垂直旋转角度 (-π/2 - π/2)。
+*   **FOV (视场角)**: 相机可视范围角度。
+
+### Animation Effects (动画效果)
+
+*   **Linear / Easing**: 大多数 `setState` 产生的旋转和缩放动画使用平滑的缓动函数 (Ease-in-out)。
+*   **Fly (飞行)**: 模拟真实空间中的移动，相机位置会发生物理位移。适用于 `Panorama` 模式下的点位切换。
+*   **Fade (渐变)**: 保持相机位置不变，通过透明度渐变切换场景。适用于距离较远或不通视的点位切换。
+
+## Configuration
+
+### Global Configuration (全局配置)
+
+在 `new Five(config)` 初始化时可以设置全局动画参数：
+
+| 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
+
+### 1. 旋转视角 (Rotate Camera)
+
+平滑旋转到指定角度。
+
+```typescript
+// 旋转到水平 0 度，垂直 0 度
+five.setState({
+  longitude: 0,
+  latitude: 0
+});
+
+// 立即跳转 (无动画)
+five.setState({ longitude: Math.PI }, true);
+```
+
+### 2. 切换全景点 (Change Pano)
+
+模拟行走效果切换到下一个房间。
+
+```typescript
+// 飞向索引为 2 的全景点
+five.moveToPano(2, {
+  effect: 'fly', // 飞行效果
+  duration: 1500, // 1.5秒
+  moveEndCallback: () => {
+    console.log("到达目的地");
+  }
+});
+```
+
+### 3. 模态切换 (Change Mode)
+
+从全景模式切换到户型图模式。
+
+```typescript
+// 切换到 Floorplan 模式
+five.changeMode('Floorplan');
+
+// 切换回 Panorama 模式，并指定进入时的视角
+five.setState({
+  mode: 'Panorama',
+  panoIndex: 0,
+  longitude: Math.PI / 2
+});
+```
+
+### 4. 自动巡更 (Auto Tour)
+
+通过连续调用 `setState` 或 `moveToPano` 实现简单的自动导览。
+
+```typescript
+async function startTour() {
+  // 1. 先看天花板
+  five.setState({ latitude: Math.PI / 3 });
+  await wait(2000); // 等待动画完成
+
+  // 2. 移动到下一个点
+  await five.moveToPano(1, { effect: 'fly' });
+
+  // 3. 切换到模型鸟瞰
+  await five.changeMode('Mapview');
+}
+
+function wait(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+```
+
+## Common Pitfalls
+
+1.  **并发调用**: 尽量避免在动画过程中再次调用 `setState`，这可能会打断当前动画或导致状态突变。建议使用 `Promise` 或回调等待动画结束。
+3.  **相机位姿**: 确保传入的 `longitude` / `latitude` 符合 Five 的坐标系定义 (Y-up, 右手系)。
+
+## Related
+
+*   [Five](./five.md): Five 核心类及 `setState` 方法。
+*   [Mode](./mode.md): 各种交互模式说明。
+*   [State](./state.md): 状态对象的完整定义。
+
+---
+
+```yaml
+tags: [camera-animation, pose, state]
+```