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

package/ai_guides/features/load-external-model.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [LoadResultType](../../five/model/loaders/shared.d.ts)
+
 所有加载函数均返回 `Promise<LoadResultType>`。
 
 ```typescript
@@ -32,6 +34,7 @@ interface BaseLoaderOptions {
   modelUpAxis?: 'Y' | 'Z';    // (部分加载器支持) 原始模型的上轴，用于自动旋转修正
   fetcher?: Fetcher;          // 自定义网络请求 Fetcher
   light?: boolean;            // 是否使用简化/无光照材质 (取决于加载器实现)
+  onDownloadProgress?: (progress: { loaded: number, total: number }) => void; // 下载进度回调
 }
 ```
 
@@ -58,6 +61,26 @@ Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
 
 ### loadGltf
 加载 `.gltf` 或 `.glb` 文件。支持 Draco 压缩。
+支持扩展：
+*   `KHR_binary_glTF`
+*   `KHR_draco_mesh_compression`
+*   `KHR_texture_basisu`
+*   `KHR_texture_transform`
+*   `KHR_mesh_quantization`
+*   `KHR_materials_unlit`
+*   `KHR_node_visibility`
+*   `KHR_animation_pointer`
+*   `EXT_meshopt_compression`
+*   `KHR_materials_clearcoat`
+*   `KHR_materials_sheen`
+*   `KHR_materials_transmission`
+*   `KHR_materials_emissive_strength`
+*   `EXT_texture_webp`
+*   `CESIUM_RTC`
+*   `REALSEE_materials_lightmap`
+*   `KHR_gaussian_splatting`
+*   `KHR_gaussian_splatting_compression_spz`
+*   `KHR_gaussian_splatting_compression_spz_2`
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
@@ -320,10 +343,12 @@ loadAt3d('https://example.com/model.at3d', {
 
 ## Related
 
-*   [model.md](./model.md): 关于 Five 内部模型加载机制的说明。
+*   [Model](./model.md): 关于 Five 内部模型加载机制的说明。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解 Y-up 与 Z-up 的转换。
+*   [Request Proxy](./request-proxy.md): 自定义请求拦截（鉴权、CDN），与 fetcher 配合使用。
 
 ---
 
 ```yaml
-tags: [loader, gltf, ply, splat, fbx, external-model]
+tags: [加载模型, 导入模型, 点云, 内存泄漏, loader, gltf, ply, splat, fbx, external-model, glb, obj, 3d-model, gaussian-splatting, point-cloud, draco, dispose]
 ```

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, tile-load, loading-bar]
+```

package/ai_guides/features/material.md

@@ -0,0 +1,159 @@
+# 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.modelScene.parameter.set('opacity', 0.5);
+
+// 仅显示原始 UV 贴图
+five.modelScene.parameter.set('modelAlpha', 0.0);
+
+// 设置楼层样式
+five.modelScene.parameter.set('floorStyle', 'wireframe');
+```
+
+### 2. Configuring Point Cloud Appearance (配置点云外观)
+
+```typescript
+// 大小随距离衰减
+five.modelScene.parameter.set('pointSize', 'ATTENUATION');
+
+// 基础大小
+five.modelScene.parameter.set('pointScale', 0.05);
+
+// 最大像素限制
+five.modelScene.parameter.set('pointMaxPixel', 20);
+```
+
+## Related
+
+*   [Parameter](./parameter.md): 配置系统入口与继承逻辑。
+*   [Pano Filter](./pano-filter.md): 了解全景图滤镜的详细用法。
+*   [3DTile Params](./3dtile.md): 性能与加载相关参数。
+
+---
+
+```yaml
+tags: [材质, 透明度, 点云, 楼层, 阴影, 亮度, 天花板, 开盖, 顶点标记, 渲染样式, material, appearance, pointcloud, parameter, roof, ceiling, config, opacity]
+```

package/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,9 +259,11 @@ document.querySelector('#btn-map').addEventListener('click', () => {
 ## Related
 
 *   [State - 状态](./state.md): 了解 Mode 在 State 中的位置及其他状态属性。
+*   [Gesture - 手势](./gesture.md): 了解不同模式下的手势交互逻辑。
+*   [Event - 事件](./event.md): 了解模式切换等相关事件。
 
 ---
 
 ```yaml
-tags: [mode, state, interaction]
+tags: [模式, 全景, 户型图, 鸟瞰, 漫游, 切换模式, 视角, mode, state, interaction, VR, panorama, floorplan, mapview, topview, model]
 ```

package/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` 访问它们。
@@ -179,5 +182,5 @@ model.viewLayers.forEach((layer) => {
 ---
 
 ```yaml
-tags: [model, viewlayer, object3d]
+tags: [模型, 三维模型, 点云, 高斯泼溅, 加载, 渲染, 图层, 楼层, 细化, model, viewlayer, object3d, mesh, refine]
 ```

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

@@ -10,6 +10,8 @@
 
 ### MovePanoEffect
 
+> **Definition**: [MovePanoEffect](../../five/types/movePanoEffect.d.ts)
+
 `effect` 参数定义了全景切换的动画模式。
 
 ```typescript
@@ -139,5 +141,5 @@ five.moveToPano(aerialPanoIndex, {
 ---
 
 ```yaml
-tags: [move-pano-effect, camera-animation, pano-switch]
+tags: [全景切换, 走点效果, 淡入淡出, 飞行, 过渡动画, 缓动, move-pano-effect, camera-animation, pano-switch, fly, fade, easing]
 ```

package/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
@@ -140,5 +142,5 @@ if (targetWork) {
 
 ---
 ```yaml
-tags: [multi-work, sandbox, works, load, transform]
+tags: [多场景, 沙盘, 多户型, 拼接, 追加, 切换场景, 多楼盘, multi-work, sandbox, works, load, transform, workCode]
 ```

package/ai_guides/features/pano-filter.md

@@ -0,0 +1,149 @@
+# 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): 了解屏幕空间的后处理效果。
+*   [Material](./material.md): 材质参数配置（透明度、点云等）。
+
+---
+
+```yaml
+tags: [滤镜, 色温, 暖色, 冷色, 饱和度, 亮度, 对比度, filter, material, visual, color, brightness, contrast, color-correction, warm, cool, tone]
+```

package/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
 
@@ -135,5 +128,5 @@ const five = new Five({
 ---
 
 ```yaml
-tags: [pano-tile, observer]
+tags: [全景瓦片, 高清全景, 分片加载, 瓦片, 全景图, 分辨率, 按需加载, pano-tile, observer, LOD, tile]
 ```