@realsee/five 6.8.0-alpha.2 → 6.8.0-alpha.21

package/ai_guides/features/load-progress.md

@@ -0,0 +1,140 @@
+# Resource Loading Progress (资源加载进度)
+
+- **Summary**: 监控 3D 模型与全景图的加载状态和实时进度。
+- **Schema**: `Model`, `Tile`, `PanoTextureEvent`
+- **Concepts**: Loaded vs Refined, Level of Detail (LOD), Panorama Lifecycle
+- **Configuration**: `minLevelOfDetail`, `maxScreenSpaceError`
+- **Examples**: 状态检查、进度监听、生命周期事件
+
+## Schema
+
+> **Definition**: [Model](../../five/model/index.d.ts), [Tile](../../five/model/tile3d/tile.d.ts), [PanoTextureEvent](../../five/controllers/events.d.ts)
+
+## Concepts
+
+在 3D Tiles 模型（如 Five 的 Work 模型）中，"加载" 分为两个阶段：
+
+1.  **Loaded (初步加载完成)**:
+    *   表示模型已经加载了足够用于显示的**基础**数据。
+    *   受 `minLevelOfDetail` 参数影响。只有当满足最小 LOD 要求的 Tile 加载完毕后，`loaded` 才会变为 `true`。
+    *   通常作为 "首屏加载完成" 的标志，此时模型可能还比较模糊。
+
+2.  **Refined (细化完成)**:
+    *   表示模型在当前视角下，已经加载了所有必要的**高清**数据，达到了最佳渲染效果。
+    *   受 `maxScreenSpaceError` 参数影响。该值越小，需要的 Tile 精度越高，细化完成所需的时间越长。
+    *   这是一个动态状态。当相机移动时，可能会因为需要加载新的高清分块而从 `refined: true` 变为 `false`。
+
+## Instance Properties
+
+### Model Status
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `five.model.loaded` | `boolean` | 检查模型是否已完成初步加载 (Loaded)。 |
+| `five.model.refined` | `boolean` | 检查模型是否已完成细化 (Refined)。 |
+| `five.model.refineProgress` | `[number, number]` | 细化进度元组 `[current, total]` (已加载/总需加载)。 |
+
+## Examples
+
+### 1. Model Loading (模型加载)
+
+#### 检查当前状态 (State Checking)
+
+```ts
+if (five.model.loaded) {
+  console.log("Model is ready (basic data loaded)!");
+}
+
+if (five.model.refined) {
+  console.log("Model is fully refined (high-res data loaded)!");
+}
+```
+
+#### 监控细化进度 (Refine Progress)
+
+`five.model.refineProgress` 提供了当前视图下模型细化的整体进度。
+
+```ts
+const [current, total] = five.model.refineProgress;
+console.log(`Model Refine Progress: ${current} / ${total}`);
+
+if (current === total && total > 0) {
+  console.log("Model is fully refined for current view.");
+}
+```
+
+#### 监听加载完成事件
+
+```ts
+five.on("modelLoaded", () => {
+  console.log("Model has been loaded.");
+});
+```
+
+#### (Advanced) Tile 级别进度
+
+对于 `3dtiles` 类型的模型，你可以访问具体的 Tile 对象来查看进度。
+
+```ts
+// 仅示例，通常在调试或特定渲染逻辑中使用
+const progress = tile.content.loadProgress; // [0, 1]
+```
+
+#### Tile Lifecycle Monitoring (Tile 生命周期监控)
+
+监控单个 Tile 的加载与卸载事件，用于更精细的调试或资源统计。
+
+```ts
+five.on("model.tileLoad", (tile) => {
+  console.log(`Tile loaded: ${tile.debugLabel}, Size: ${tile.content.byteLength}`);
+});
+
+five.on("model.tileUnload", (tile) => {
+  console.log(`Tile unloaded: ${tile.debugLabel}`);
+});
+```
+
+### 2. Panorama Loading (全景图加载)
+
+全景图通常在用户移动到某个点位时按需加载。
+
+#### 监听加载进度
+
+使用 `pano.texture.progress` 事件获取当前全景图的加载进度。
+
+```ts
+five.on("pano.texture.progress", (event) => {
+  const { progress, pano } = event;
+  console.log(`Pano ${pano.panoIndex} loading: ${(progress * 100).toFixed(1)}%`);
+});
+```
+
+#### 生命周期事件
+
+*   **`pano.texture.load`**: 开始加载。
+*   **`pano.texture.success`**: 加载完成。
+*   **`pano.texture.error`**: 加载失败。
+
+```ts
+five.on("pano.texture.load", (event) => {
+  console.log(`Started loading pano ${event.pano.panoIndex}`);
+});
+
+five.on("pano.texture.success", (event) => {
+  console.log(`Finished loading pano ${event.pano.panoIndex}`);
+});
+
+five.on("pano.texture.error", (event) => {
+  console.error(`Failed to load pano ${event.pano.panoIndex}`, event.error);
+});
+```
+
+## Related
+
+*   [Five Class](../api.md): Five 核心类 API 索引。
+
+---
+
+```yaml
+tags: [loading, progress, refined, loaded, event]
+```

package/ai_guides/features/material.md

@@ -0,0 +1,153 @@
+# Material Parameters (材质参数)
+
+- **Summary**: 配置 3D 模型与全景图过渡的视觉表现、渲染样式及特效。
+- **Schema**: 对应 `ParameterMaterialValue` 接口，定义了材质、点云、楼层等外观属性。
+- **Concepts**: Transparency (透明度), Point Cloud (点云), Floor Style (楼层样式), PBR (物理渲染)。
+- **Configuration**: 包含透明度、混合模式、点云大小/形状、阴影设置等详细参数。
+- **Examples**: 模型透明度调整、点云样式定制。
+
+## Schema
+
+> **Definition**: [ParameterMaterialValue](../../five/model/parameter.d.ts)
+
+以下是 `ParameterMaterialValue` 的 TypeScript 定义摘要：
+
+```typescript
+export interface ParameterMaterialValue {
+  /** 模型整体透明度 [0, 1] */
+  opacity: number;
+  /** 点云基础缩放比例 */
+  pointScale: number;
+  /** 点云大小绘制方式 ('ATTENUATION' | 'FIXED') */
+  pointSize: PBMPointSize;
+  /** 楼层显示样式 ('OPACITY' | 'VISIBILITY') */
+  floorStyle: PBMFloorStyle;
+  // ... 更多字段见下方配置表
+}
+```
+
+## Concepts
+
+### 1. Transparency & Blending (透明度与混合)
+
+材质系统提供了两种维度的透明度控制：
+*   **Opacity (`opacity`)**: 控制模型整体的不透明度 (0-1)。
+*   **Model Alpha (`modelAlpha`)**: 控制纹理混合的权重。
+    *   `0`: 仅显示模型自带的 UV 纹理（通常是颜色单一的白模或人工烘焙的纹理）。
+    *   `1`: 仅显示从全景图投影到模型上的纹理（真实感强，但可能存在投影误差）。
+    *   `0.5`: 两者混合。
+
+### 2. Point Cloud Rendering (点云渲染)
+
+Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
+*   **Size Attenuation**: 通过 `pointSize: 'ATTENUATION'` 开启近大远小的透视效果，增强空间感。
+*   **Pixel Limits**: 通过 `pointMinPixel` 和 `pointMaxPixel` 限制点在屏幕上的最小/最大像素尺寸，防止远处点消失或近处点过大遮挡视线。
+
+### 3. Floor Management (楼层管理)
+
+对于多楼层场景，可以通过参数控制楼层的显示策略：
+*   **Floor Style (`floorStyle`)**: 控制非当前楼层的显示方式（如 `OPACITY` 半透明、`VISIBILITY` 隐藏等）。
+*   **Shown Floor (`shownFloorIndex`)**: 指定当前高亮显示的楼层索引。
+
+### 4. Vertex Marks & Semantic Filtering (顶点标记与语义过滤)
+
+`vertexMarks` 是一个**全局开关**，用于控制是否启用模型顶点上的语义标记（`_feature_id_rsmask`）逻辑。
+
+*   **机制**: 模型顶点预置了 `_feature_id_rsmask` 属性，不同的值代表不同的语义部分。
+*   **当前支持**: 目前主要支持 `_feature_id_rsmask=1`（通常标记为天花板/房顶）。
+    *   当 `vertexMarks` 开启时，标记为 `1` 的顶点部分会在特定视角（如俯视）下自动隐藏，实现“开盖”效果，优化室内布局观测体验。
+*   **未来扩展**: 该机制设计支持更多标记值，未来可能用于控制其他特定模型部件的显示效果。
+
+## Configuration
+
+以下表格列出了控制材质与外观的可用参数，按使用频率和场景分类。
+
+### Common Configuration (常用配置)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `opacity` | `number` | `1.0` | 模型整体透明度 [0, 1]。0 为完全透明，1 为完全不透明。 |
+| `pointScale` | `number` | `0.02` | 点的基础缩放比例（控制点的大小）。 |
+| `pointSize` | `PBMPointSize` | `'ATTENUATION'` | 点云大小绘制方式。<br>`'ATTENUATION'`: 随距离衰减（近大远小）；<br>`'FIXED'`: 固定像素大小。 |
+| `pointShape` | `PBMPointShape` | `'CIRCLE'` | 点云形状。<br>`'CIRCLE'`: 圆形；<br>`'SQUARE'`:方形。 |
+| `pointBack` | `PBMPointBack` | `'DARK'` | 点云背面绘制方式。 |
+| `pointMinPixel` | `number` | `0` | 点云最小像素尺寸。 |
+| `pointMaxPixel` | `number` | `40` | 点云最大像素尺寸。 |
+| `pointAppearAnimation` | `boolean` | `true` | 是否开启点云出现动画。 |
+| `vertexMarks` | `boolean` | `true` | 是否显示/生效标注。 |
+| `brightness` | `number` | `1.0` | 场景亮度倍数。 |
+| `floorStyle` | `PBMFloorStyle` | `'OPACITY'` | 楼层显示样式。 |
+| `shownFloorIndex` | `number` | `-1` | 当前显示的楼层索引。`-1` 表示显示所有楼层。 |
+| `castShadow` | `boolean` | `false` | 模型是否产生阴影。 |
+| `receiveShadow` | `boolean` | `false` | 模型是否接收阴影。 |
+| `useAddBlend` | `boolean` | `false` | 是否使用半透明叠加渲染。 |
+| `customShaders` | `PBMCustomShader[]` | `[]` | 自定义 Shader 配置。 |
+| `panoFilter` | `PBMPanoFilter` | `null` | 全景图滤镜 (亮度、对比度、色温等)。详情见 [Pano Filter](./pano-filter.md)。 |
+| `clippers` | `PBMClipperParameter[]` | `[]` | 模型裁切参数。 |
+| `boundingBox` | `THREE.Box3` | `Infinity` | 模型包围盒。 |
+
+### Advanced Appearance (进阶外观配置)
+
+> 这些参数较少使用，仅在需要精细调整特殊视觉效果时修改。
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `colorSaturation` | `number` | `0.0` | 饱和度调整值。 |
+| `colorBrightness` | `number` | `0.0` | 亮度调整值（与 `brightness` 叠加）。 |
+| `colorStyle` | `PBMColorStyle` | `'RGB'` | 颜色显示样式。 |
+| `constantColor` | `THREE.Vector3` | `(0.6, 0.6, 0.6)` | 模型纯色模式下的颜色值。 |
+| `outlineGain` | `number` | `0.0` | 轮廓线增益。 |
+| `distanceGain` | `number` | `0.0` | 距离增益。 |
+| `gaussianSplattingSHDegree` | `number` | `0` | 3D Gaussian Splatting 的球谐阶数。 |
+
+### Internal & Low-Level (内部与底层配置)
+
+> **注意**: 以下参数主要用于引擎内部状态同步或特定底层逻辑，**不建议开发者手动修改**，以免引起渲染异常。
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `modelAlpha` | `number` | `1.0` | 模型纹理混合系数。通常由 Five 内部模式切换控制。 |
+| `useHQWeight` | `boolean` | `false` | 是否使用高质量权重计算（影响渲染质量）。 |
+| `useHQDepth` | `boolean` | `false` | 是否使用高质量深度遮罩。 |
+| `progress` | `number` | `0` | 全景图混合进度。 |
+| `transition` | `PBMTransition` | `'FADE'` | 全景图过渡混合模式。 |
+| `gradientTexture` | `THREE.Texture` | `default` | 高程着色材质纹理。 |
+| `pano0` | `PBMPanoPicture` | `null` | 起始点全景图信息。 |
+| `pano1` | `PBMPanoPicture` | `null` | 结束点全景图信息。 |
+| `pano0Depth` | `PBMPanoDepth` | `null` | 起始点深度信息。 |
+| `pano1Depth` | `PBMPanoDepth` | `null` | 结束点深度信息。 |
+| `refinedScreen` | `PBMRefinedScreen` | `null` | 细化瓦片的屏幕渲染配置。 |
+
+## Examples
+
+### 1. Adjusting Model Transparency and Style (调整模型透明度与样式)
+
+```typescript
+five.model.set({
+  opacity: 0.5,           // Make model semi-transparent (半透明)
+  modelAlpha: 0.0,        // Show original UV texture only (仅显示原始UV贴图)
+  floorStyle: 'wireframe' // Wireframe mode (线框模式)
+});
+```
+
+### 2. Configuring Point Cloud Appearance (配置点云外观)
+
+```typescript
+five.model.set({
+  pointSize: 'ATTENUATION', // 大小随距离衰减
+  pointScale: 0.05,         // 基础大小
+  pointMaxPixel: 20         // 最大像素限制
+});
+```
+
+## Related
+
+*   [Parameter](./parameter.md): 配置系统入口与继承逻辑。
+*   [Pano Filter](./pano-filter.md): 了解全景图滤镜的详细用法。
+*   [3DTile Params](./3dtile.md): 性能与加载相关参数。
+
+---
+
+```yaml
+tags: [material, appearance, pointcloud, parameter, roof, ceiling, config]
+```

package/{guides → ai_guides}/features/mode.md

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [Mode](../../five/application/mode.d.ts), [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
 **Mode** 类型定义如下：
 
 ```ts
@@ -257,6 +259,8 @@ document.querySelector('#btn-map').addEventListener('click', () => {
 ## Related
 
 *   [State - 状态](./state.md): 了解 Mode 在 State 中的位置及其他状态属性。
+*   [Gesture - 手势](./gesture.md): 了解不同模式下的手势交互逻辑。
+*   [Event - 事件](./event.md): 了解模式切换等相关事件。
 
 ---
 

package/{guides → ai_guides}/features/model.md

@@ -9,6 +9,8 @@
 
 ### Model
 
+> **Definition**: [Model](../../five/model/model.d.ts)
+
 Model 类继承自 `THREE.Object3D`，是三维场景中的顶级对象。
 
 ```typescript
@@ -23,7 +25,7 @@ class Model extends THREE.Object3D {
   /** 模型参数配置 */
   public parameter: Parameter;
 
-  /** 包含的视图层 (如 mesh, point_cloud) */
+  /** 包含的视图层 (如 mesh, point_cloud, gaussian_splatting) */
   public viewLayers: ViewLayer[];
 
   /** 是否加载完成 (初次加载) */
@@ -77,6 +79,7 @@ const model2 = five.model;
 常见的 ViewLayer 类型：
 *   **`mesh` (网格层)**: 也就是可以看到的实体模型（墙面、地板等）。
 *   **`point_cloud` (点云层)**: 激光点云数据。它并非低精度数据，同样支持高精度的近距离观察，并支持碰撞检测。
+*   **`gaussian_splatting` (高斯泼溅层)**: 新一代三维重建渲染技术，用于展示极高真实感的场景细节。
 
 **层级结构**:
 Model 加载完成后，会自动根据 Work 数据生成对应的 ViewLayer，并挂载为 `Model` 的子对象。开发者可以通过 `model.viewLayers` 访问它们。

package/{guides → ai_guides}/features/move-pano-effect.md

@@ -10,6 +10,8 @@
 
 ### MovePanoEffect
 
+> **Definition**: [MovePanoEffect](../../five/types/movePanoEffect.d.ts)
+
 `effect` 参数定义了全景切换的动画模式。
 
 ```typescript

package/{guides → ai_guides}/features/multi-work.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [FiveLoadOptions](../../five/application/fiveLoadOptions.d.ts), [LooseWorkWithExtrinsics](../../five/work/looseWorkType.d.ts)
+
 ### 核心类型定义
 
 ```typescript

package/ai_guides/features/pano-filter.md

@@ -0,0 +1,148 @@
+# Pano Filter (全景图滤镜)
+
+- **Summary**: `PBMPanoFilter` 用于调整全景图的视觉效果，包括亮度、对比度、饱和度、色温、色调等。它作为参数传递给 `ModelScene`，可实时改变全景图的渲染表现。
+- **Schema**: `PBMPanoFilter`, `PBMUpdateable`
+- **Concepts**: Material Filter, Color Correction
+- **Configuration**: Temperature, Tint, Brightness, Contrast, Saturation
+- **Examples**: 滤镜开启与参数调整
+
+## Schema
+
+> **Definition**: [PBMPanoFilter](../../five/model/materials/pbmMaterial.d.ts)
+
+`PBMPanoFilter` 类定义了全景图的滤镜参数。所有属性均为对象引用，直接修改其内部属性即可生效。
+
+```typescript
+import { PBMUpdateable } from "@realsee/five";
+
+export class PBMPanoFilter extends PBMUpdateable {
+  /** 对比度控制 */
+  public readonly contrast: {
+    /** 对比度偏移 [-1, 1] (默认 0) */
+    contrastBias: number;
+  };
+
+  /** 饱和度控制 */
+  public readonly saturation: {
+    /** 饱和度偏移 [-1, 1] (默认 0) */
+    saturationBias: number;
+  };
+
+  /** 颜色控制 (色温与色调) */
+  public readonly color: {
+    /** 色温偏移 [-100, 100] (默认 0) */
+    temperatureBias: number;
+    /** 色调偏移 [-100, 100] (默认 0) */
+    tintBias: number
+  };
+
+  /** 高光与阴影控制 */
+  public readonly highlightShadow: {
+    /** 全局亮度偏移 [-255, 255] (默认 0) */
+    globalBias: number;
+    /** 高光偏移 [-255, 255] (默认 0) */
+    highlightBias: number;
+    /** 阴影偏移 [-255, 255] (默认 0) */
+    shadowBias: number;
+  };
+}
+```
+
+## Concepts
+
+### Material Filter (材质滤镜)
+与 [Postprocessing](./postprocessing.md) (后处理) 不同，`PBMPanoFilter` 是作用于全景图材质 (Material) 阶段的滤镜。这意味着它直接影响纹理的采样和着色计算，而不是对最终渲染图像进行二次处理。
+
+### Parameter Binding (参数绑定)
+滤镜实例需要通过 `five.modelScene.parameter.set('panoFilter', filter)` 绑定到场景中才能生效。
+
+## Configuration
+
+以下参数均通过修改 `PBMPanoFilter` 实例的属性进行配置。
+
+### Color & Tone (色彩与色调)
+
+| Property | Type | Range | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `color.temperatureBias` | `number` | `[-100, 100]` | `0` | **色温**。正值偏暖 (黄)，负值偏冷 (蓝)。 |
+| `color.tintBias` | `number` | `[-100, 100]` | `0` | **色调**。正值偏洋红，负值偏绿。 |
+| `saturation.saturationBias` | `number` | `[-1, 1]` | `0` | **饱和度**。`0` 为原色，`-1` 为黑白。 |
+| `contrast.contrastBias` | `number` | `[-1, 1]` | `0` | **对比度**。正值增强对比，负值降低对比。 |
+
+### Light & Shadow (光影)
+
+| Property | Type | Range | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `highlightShadow.globalBias` | `number` | `[-255, 255]` | `0` | **亮度 (Brightness)**。整体提升或降低画面亮度。 |
+| `highlightShadow.highlightBias` | `number` | `[-255, 255]` | `0` | **高光 (Highlight)**。仅调整画面亮部的亮度。 |
+| `highlightShadow.shadowBias` | `number` | `[-255, 255]` | `0` | **阴影 (Shadow)**。仅调整画面暗部的亮度。 |
+
+## Examples
+
+### Basic Usage (基础用法)
+
+创建一个滤镜实例并应用到 Five 场景中。
+
+```typescript
+import { Five, PBMPanoFilter } from "@realsee/five";
+
+const five = new Five();
+// ... 初始化 five ...
+
+// 1. 创建滤镜实例
+const panoFilter = new PBMPanoFilter();
+
+// 2. 配置参数 (例如：增加一点暖色调和亮度)
+panoFilter.color.temperatureBias = 10; // 暖色
+panoFilter.highlightShadow.globalBias = 20; // 提亮
+
+// 3. 启用滤镜
+five.modelScene.parameter.set('panoFilter', panoFilter);
+
+// 4. (可选) 停用滤镜
+// five.modelScene.parameter.reset('panoFilter');
+```
+
+### Interactive Adjustment (动态调整)
+
+滤镜参数支持实时修改，适合制作调节面板。
+
+```typescript
+import { Five, PBMPanoFilter } from "@realsee/five";
+
+// 假设已经有 five 实例
+const panoFilter = new PBMPanoFilter();
+five.modelScene.parameter.set('panoFilter', panoFilter);
+
+// 模拟 UI 绑定的数据对象
+const filterSettings = {
+  brightness: 0,
+  contrast: 0,
+};
+
+// 监听 UI 变化 (示例伪代码)
+function onBrightnessChange(value: number) {
+  // value range: [-255, 255]
+  panoFilter.highlightShadow.globalBias = value;
+  // 如果 five 没有开启自动渲染 (play: false)，需要手动触发重绘
+  five.needsRender = true;
+}
+
+function onContrastChange(value: number) {
+  // value range: [-1, 1]
+  panoFilter.contrast.contrastBias = value;
+  five.needsRender = true;
+}
+```
+
+## Related
+
+*   [Model](./model.md): 了解 ModelScene 及其参数系统。
+*   [Parameter](./parameter.md): 了解 Five 的全局初始化参数。
+*   [Postprocessing](./postprocessing.md): 了解屏幕空间的后处理效果。
+
+---
+
+```yaml
+tags: [filter, material, visual, color, brightness, contrast]
+```

package/{guides → ai_guides}/features/pano-tile.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [WorkImage](../../five/work/work.d.ts), [ImageOptions](../../five/types/imageOptions.d.ts)
+
 ### WorkObserver.images
 点位全景图数据结构，包含瓦片列表。
 
@@ -63,20 +65,11 @@ interface ImageOptions {
 
 在初始化 `Five` 时，可以通过 `panorama` 配置参数来配置瓦片加载行为。
 
-### tileLevelForFov
-- **类型**: `(fov: number, viewSize: THREE.Vector2) => number` | `false`
-- **默认值**: 内部默认策略 (根据像素比和 FOV 动态计算)
-- **说明**: 自定义函数，用于根据当前 FOV 和视图尺寸决定加载哪个层级的瓦片。返回 `level` 数值。如果设置为 `false`，则禁用动态瓦片加载。
-
-### tileMaxRequest
-- **类型**: `number`
-- **默认值**: `3` (在某些 VR/XR 模式下可能不同)
-- **说明**: 最大的瓦片图片并发请求数。增加此值可能加快加载速度，但也可能导致网络拥塞。
-
-### imageOptions
-- **类型**: `ImageOptions`
-- **默认值**: `undefined`
-- **说明**: 全景图及瓦片的图片处理配置。可用于全局控制图片的加载格式（如强制使用 WebP）、质量压缩比例或通过 `transform` 函数自定义图片 URL（如适配不同的 CDN 规则）。这对于优化首屏加载速度和节省带宽非常有用。
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `tileLevelForFov` | `(fov: number, viewSize: Vector2) => number` \| `false` | `undefined` | 自定义函数，用于根据当前 FOV 和视图尺寸决定加载哪个层级的瓦片。返回 `level` 数值。如果设置为 `false`，则禁用动态瓦片加载。默认使用内部策略。 |
+| `tileMaxRequest` | `number` | `3` | 最大的瓦片图片并发请求数。增加此值可能加快加载速度，但也可能导致网络拥塞。 |
+| `imageOptions` | `ImageOptions` | `undefined` | 全景图及瓦片的图片处理配置。可用于全局控制图片的加载格式（如强制使用 WebP）、质量压缩比例或通过 `transform` 函数自定义图片 URL。 |
 
 ## Examples
 

package/ai_guides/features/pano-uv.md

@@ -0,0 +1,131 @@
+# 全景图 UV 与方向转换 (Panorama UV Conversion)
+
+- **Summary**: 提供了一组工具方法，用于在**全景图 UV 坐标** (Equirectangular UV / Cubemap UV) 与**三维空间方向向量** (Vector3) 之间进行转换。
+- **Schema**: 依赖 `WorkObserver` 实例，提供四个核心转换方法。
+- **Concepts**: Equirectangular Projection, Cubemap Projection, UV Origin, Coordinate Systems.
+- **Configuration**: `uvOrigin` (UV 原点设置).
+- **Examples**: 向量转全景 UV、UV 转向量、Cubemap 转换。
+
+## Schema
+
+> **Definition**: [WorkObserver](../../five/work/work.d.ts)
+
+这些方法挂载在 `WorkObserver` 实例上，依赖当前观察点 (Observer) 的位姿信息 (Position & Quaternion) 以及 `work.transform` 进行计算。
+
+```typescript
+interface WorkObserver {
+  /**
+   * 将方向向量转化为全景图 uv
+   * @param vector - 全局方向向量 (World Space)
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+
+  /**
+   * 将全景图 uv 转化为方向向量
+   * @param uv - 全景图 UV 坐标 [0, 1]
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+
+  /**
+   * 将方向向量转化为六视图 uv
+   * @param vector - 全局方向向量 (World Space)
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];
+
+  /**
+   * 将六视图 uv 转化为方向向量
+   * @param cubeFace - 立方体面 ('up' | 'down' | 'left' | 'right' | 'front' | 'back')
+   * @param uv - 该面上的 UV 坐标 [0, 1]
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+}
+
+type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
+```
+
+## Concepts
+
+### 1. 坐标系转换 (Coordinate Transformation)
+转换过程会自动处理以下坐标空间的变换：
+1.  **World Space (世界坐标系)**: `vector` 参数所处的坐标系。
+2.  **Work Space (Work 坐标系)**: 考虑 `work.transform` 带来的整体旋转。
+3.  **Observer Space (观察者坐标系)**: 考虑 `observer.quaternion` 带来的观察点旋转。
+4.  **Panorama Space (全景图空间)**: 最终映射到 2D 图片上的 UV 坐标。
+
+### 2. 投影方式 (Projection Types)
+*   **Equirectangular (等距柱状投影)**: 将球体展开为 2:1 的矩形图片。常用于全景图预览。
+*   **Cubemap (立方体贴图)**: 将球体投影到立方体的六个面上。常用于高清全景浏览。
+
+### 3. UV 原点 (UV Origin)
+*   **top-left (默认)**: 原点 `(0, 0)` 在图片**左上角**。U 轴向右，V 轴向下。符合大多数 Web 图片处理习惯 (Canvas, DOM)。
+*   **bottom-left**: 原点 `(0, 0)` 在图片**左下角**。U 轴向右，V 轴向上。符合 WebGL / OpenGL 纹理坐标习惯。
+
+## Configuration
+
+所有方法均包含可选参数 `uvOrigin`。
+
+### Common Configuration
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `uvOrigin` | `'top-left' \| 'bottom-left'` | `'top-left'` | 指定 UV 坐标系的原点位置。 |
+
+## Examples
+
+### 1. 点击全景图获取空间方向 (Click to Vector)
+假设你有一个全景图的点击事件，获取到了点击位置的 UV：
+
+```typescript
+const observer = five.work.observers[0];
+// 假设这是用户点击全景图后归一化得到的 UV (0~1)
+const clickUv = new THREE.Vector2(0.5, 0.5);
+
+// 转换为世界空间的方向向量
+const direction = observer.equirectangularUvToVector(clickUv);
+
+console.log('点击方向:', direction);
+```
+
+### 2. 将空间点映射到全景图上 (World Point to UV)
+假设场景中有一个 3D 物体，你想知道它在当前全景图上的位置（例如打标签）：
+
+```typescript
+const observer = five.work.observers[0];
+const objectPosition = new THREE.Vector3(10, 2, 5);
+
+// 计算物体相对于观察点的方向向量
+const direction = objectPosition.clone().sub(observer.position).normalize();
+
+// 获取全景图 UV
+const uv = observer.vectorToEquirectangularUv(direction);
+
+console.log(`物体在全景图上的位置: u=${uv.x}, v=${uv.y}`);
+```
+
+### 3. 处理 Cubemap 坐标 (Cubemap Conversion)
+如果你使用的是六面体全景图资源：
+
+```typescript
+const observer = five.work.observers[0];
+const direction = new THREE.Vector3(0, 0, -1); // 正前方
+
+// 获取对应的面和 UV
+const [face, uv] = observer.vectorToCubemapUv(direction);
+
+console.log(`正前方对应 Cubemap 的 ${face} 面，UV 为`, uv);
+```
+
+## Related
+
+*   [Work](./work.md): 了解 WorkObserver 的数据结构。
+*   [Coordinate System](./coordinate-system.md): 了解 Five 的坐标系定义。
+
+---
+
+```yaml
+tags: [work, observer, uv, projection, math]
+```