@realsee/five 6.8.0-alpha.8 → 6.8.0

package/ai_guides/features/flowing-light-3d-pass.md

@@ -1,16 +1,16 @@
 # Flowing Light 3D Pass (流光 3D 通道)
 
-- **Summary**: `FlowingLight3DPass` 基于 3D 世界坐标绘制流光效果，自动投影到屏幕空间，适合沿模型表面、路径或空间轨迹演示动态流动光带。
+- **Summary**: `FlowingLight3DPass` 基于 3D 世界坐标绘制流光效果,使用 InstancedMesh 实例化渲染优化性能,自动投影到屏幕空间,适合沿模型表面、路径或空间轨迹演示动态流动光带。
 - **Schema**: `FlowingLight3DPass` 类及 Line 数据结构。
-- **Concepts**: 基于相机投影的 3D 光带、世界坐标到屏幕坐标映射、动画驱动。
-- **Configuration**: 3D 路径点、颜色、不透明度、动画周期。
-- **Examples**: 空间轨迹演示、结合相机动画、多条 3D 路径。
+- **Concepts**: 基于相机投影的 3D 光带、InstancedMesh 实例化渲染、世界坐标到屏幕坐标映射、头尾追逐动画。
+- **Configuration**: 3D 路径点、颜色、不透明度、线宽、动画周期、延迟。
+- **Examples**: 空间轨迹演示、结合相机动画、多条 3D 路径、高 DPR 场景优化。
 
 ## Schema
 
 > **Definition**: [FlowingLight3DPass](../../five/renderer/postprocessing/passes/flowing-light-3d-pass.d.ts)
 
-`FlowingLight3DPass` 继承自 `FivePass`，支持投影到当前相机视锥。核心接口如下：
+`FlowingLight3DPass` 继承自 `FivePass`,支持投影到当前相机视锥。核心接口如下:
 
 ```ts
 import * as THREE from 'three';
@@ -18,11 +18,15 @@ import { FivePass } from './pass';
 import { type Camera } from '../../../core/camera';
 
 type Line = {
+  id?: string;                   // 可选的唯一标识符,不传则自动生成 UUID
   points: THREE.Vector3[];      // 世界坐标系路径点
-  totalLength: number;           // 路径总长度（世界单位）
+  totalLength: number;           // 路径总长度(世界单位)
   color: THREE.Color;            // 光带颜色
-  opacity?: number;              // 光带不透明度（0-1）
-  duration?: number;             // 动画周期（毫秒）
+  opacity?: number;              // 光带不透明度(0-1)
+  duration?: number;             // 动画周期(毫秒)
+  delay?: number;                // 动画延迟(毫秒)
+  lineWidth?: number;            // 线宽(像素)
+  tailLengthRatio?: number;      // 尾巴长度比例(0-1),默认 0.2
 };
 
 export class FlowingLight3DPass extends FivePass {
@@ -31,6 +35,9 @@ export class FlowingLight3DPass extends FivePass {
   // 设置要渲染的路径列表
   public setLines(lines: Line[]): void;
 
+  // 修改单条线的参数(通过 id)
+  public setLine(params: { id: string } & Partial<Omit<Line, 'id'>>): void;
+
   public render(
     renderer: THREE.WebGLRenderer,
     writeBuffer: THREE.WebGLRenderTarget,
@@ -42,17 +49,28 @@ export class FlowingLight3DPass extends FivePass {
   public dispose(): void;
 }
 ```
-
 ## Concepts
 
+### InstancedMesh 实例化渲染 (Instanced Rendering)
+为了优化高 DPR(Device Pixel Ratio)场景下的性能,该 Pass 使用 InstancedMesh 代替全屏着色器。每个线段作为一个实例,只渲染线段覆盖的区域,避免了对每个像素的全屏检查,显著提升了渲染效率。
+
 ### 世界空间路径与投影 (World-space Projection)
-路径点定义在 3D 世界坐标系中。Pass 内部自动根据当前相机投影矩阵将 3D 点映射到屏幕空间，从而实现"随相机变化"的动态光带效果。
+路径点定义在 3D 世界坐标系中。Pass 内部自动根据当前相机投影矩阵将 3D 点映射到屏幕空间,从而实现"随相机变化"的动态光带效果。
+
+### 头尾追逐动画 (Head-Tail Chase Animation)
+流光效果采用"头尾追逐"模式:
+- **头部(Head)**: 光流的前端,沿路径循环移动
+- **尾部(Tail)**: 光流的后端,跟随头部移动
+- **渐变**: 从尾部(透明度 0)到头部(透明度 1)线性渐变
+- **尾长**: 尾部长度由 `tailLengthRatio` 参数控制(默认 0.2,即路径总长的 20%)
 
-### 循环流动 (Looping Flow)
-默认使用循环模式（`LOOP = true`），光头在路径上循环流动，无起点/终点的区分。尾部长度为路径总长的 1/4。
+光头在路径上循环流动,通过 `gl_FragCoord` 投影到线段上计算每个像素的渐变位置,确保渐变效果准确。尾巴长度会在动画开始时逐渐增长,直到达到 `tailLengthRatio * totalLength`。
 
 ### 相机同步
-Pass 自动同步相机的投影矩阵和视图矩阵，无需手动管理。支持相机运动时光带跟随。
+Pass 自动同步相机的投影矩阵和视图矩阵,无需手动管理。支持相机运动时光带跟随。
+
+### DPR 处理
+自动处理高 DPR 场景,渲染目标尺寸根据 `readBuffer` 自动调整,确保在 Retina 等高分辨率屏幕上位置准确且性能优化。
 
 ## Configuration
 
@@ -60,25 +78,32 @@ Pass 自动同步相机的投影矩阵和视图矩阵，无需手动管理。支
 
 | Parameter | Type | Required | Default | Description |
 | :--- | :--- | :--- | :--- | :--- |
+| `id` | `string` | | 自动生成 UUID | 唯一标识符,用于 `setLine` 方法更新单条线。 |
 | `points` | `THREE.Vector3[]` | ✓ | - | 世界坐标系路径点数组。至少 2 个点。 |
-| `totalLength` | `number` | ✓ | - | 路径总长度（世界单位）。通常为所有相邻点间距离之和。 |
-| `color` | `THREE.Color` | ✓ | - | 光带颜色（RGB）。 |
-| `opacity` | `number` | | `1` | 光带不透明度（0-1）。控制与背景的混合强度。 |
-| `duration` | `number` | | `1000` | 动画周期（毫秒）。光头完成一个循环所需时长。 |
+| `totalLength` | `number` | ✓ | - | 路径总长度(世界单位)。通常为所有相邻点间距离之和。 |
+| `color` | `THREE.Color` | ✓ | - | 光带颜色(RGB)。 |
+| `opacity` | `number` | | `1.0` | 光带不透明度(0-1)。控制与背景的混合强度。 |
+| `duration` | `number` | | `1000` | 动画周期(毫秒)。光头完成一个循环所需时长。 |
+| `delay` | `number` | | `0` | 动画延迟(毫秒)。延迟后才开始播放动画。 |
+| `lineWidth` | `number` | | `3.0` | 线宽(像素)。控制光带在屏幕上的宽度。 |
+| `tailLengthRatio` | `number` | | `0.2` | 尾巴长度比例(0-1)。控制流光尾巴相对于路径总长的比例。 |
 
-> **注意**: `totalLength` 应为世界坐标单位。若不准确，流速会偏差。
+> **注意**: `totalLength` 应为世界坐标单位。若不准确,流速会偏差。
 
 ## Instance Methods
 
 ### `constructor(camera: Camera)`
-初始化 Pass，需传入相机以获取投影矩阵和视图矩阵。
+初始化 Pass,需传入相机以获取投影矩阵和视图矩阵。
 
 ### `setLines(lines: Line[])`
 更新要渲染的路径列表。支持运行时动态更改。
 
-**示例**：
+**自动生成 ID**: 如果 line 没有提供 `id`,会自动生成 UUID。
+
+**示例**:
 ```ts
 const pathLine: Line = {
+  id: 'my-3d-line',  // 可选,不传则自动生成
   points: [
     new THREE.Vector3(0, 0, 0),
     new THREE.Vector3(5, 2, 3),
@@ -88,21 +113,74 @@ const pathLine: Line = {
   color: new THREE.Color(0xff6600),
   opacity: 0.85,
   duration: 3000,
+  delay: 500,
+  lineWidth: 4.0,
 };
 pass.setLines([pathLine]);
 ```
 
+### `setLine(params: { id: string } & Partial<Omit<Line, 'id'>>)`
+通过 `id` 修改单条线的参数。支持部分更新,只更新传入的字段。
+
+**性能优化**:
+- 如果 `points` 数量不变,只更新 GPU 的 instance attributes,性能极高
+- 如果 `points` 数量改变,会重建整个 mesh,性能开销较大
+
+**示例**:
+```ts
+// 只修改颜色 - 高性能
+pass.setLine({
+  id: 'my-3d-line',
+  color: new THREE.Color(0xff0000),
+});
+
+// 修改多个属性 - 高性能
+pass.setLine({
+  id: 'my-3d-line',
+  color: new THREE.Color(0x00ff00),
+  opacity: 0.5,
+  duration: 3000,
+  lineWidth: 5.0,
+});
+
+// 修改 points (相同数量) - 高性能
+pass.setLine({
+  id: 'my-3d-line',
+  points: [
+    new THREE.Vector3(0, 0, 0),
+    new THREE.Vector3(6, 3, 4),
+    new THREE.Vector3(12, 2, 8),
+  ],  // 仍是 3 个点
+  totalLength: 15,
+});
+
+// 修改 points (不同数量) - 会重建 mesh
+pass.setLine({
+  id: 'my-3d-line',
+  points: [
+    new THREE.Vector3(0, 0, 0),
+    new THREE.Vector3(10, 5, 5),
+  ],  // 从 3 个点变为 2 个点
+  totalLength: 12,
+});
+```
+
+**注意事项**:
+- 如果 `id` 不存在,会在控制台输出警告
+- 动画时间(`uTime`)不会被重置,流光继续从当前位置播放
+- 建议修改 `points` 时同时更新 `totalLength`
+
 ### `render(...)`
-由 EffectComposer 自动调用，无需手动调用。自动同步相机矩阵。
+由 EffectComposer 自动调用,无需手动调用。自动同步相机矩阵和渲染目标尺寸。
 
 ### `dispose()`
-释放着色材质和数据纹理资源，销毁 Pass 时必须调用。
+释放 InstancedMesh、着色材质和渲染目标资源,销毁 Pass 时必须调用。
 
 ## Examples
 
 ### 快速上手 (Quick Example)
 
-```ts
+```typescript
 import { Five } from '@realsee/five';
 import { FlowingLight3DPass } from '../../lib/five/renderer/postprocessing';
 import * as THREE from 'three';
@@ -112,7 +190,7 @@ const five = new Five();
 // 创建 3D 流光通道
 const flowing3D = new FlowingLight3DPass(five.camera);
 
-// 定义一条 3D 路径（世界坐标）
+// 定义一条 3D 路径(世界坐标)
 const path = [
   new THREE.Vector3(-5, 0, 0),
   new THREE.Vector3(-2, 3, 2),
@@ -127,6 +205,7 @@ flowing3D.setLines([{
   color: new THREE.Color(0x00ff88),
   opacity: 0.8,
   duration: 4000,
+  lineWidth: 3.0,
 }]);
 
 five.addPass(flowing3D);
@@ -138,9 +217,10 @@ function animate() {
 animate();
 ```
 
+
 ### 多条 3D 路径
 
-```ts
+```typescript
 const pass = new FlowingLight3DPass(camera);
 
 const paths = [
@@ -152,6 +232,7 @@ const paths = [
     totalLength: 11,
     color: new THREE.Color(0xff0000),
     duration: 2000,
+    lineWidth: 3.0,
   },
   {
     points: [
@@ -161,6 +242,8 @@ const paths = [
     totalLength: 12,
     color: new THREE.Color(0x00ff00),
     duration: 2500,
+    delay: 500,
+    lineWidth: 4.0,
   },
   {
     points: [
@@ -170,15 +253,18 @@ const paths = [
     totalLength: 11,
     color: new THREE.Color(0x0000ff),
     duration: 2200,
+    delay: 1000,
+    lineWidth: 2.5,
   },
 ];
 
 pass.setLines(paths);
 ```
 
+
 ### 计算 3D 路径长度
 
-```ts
+```typescript
 function calculatePath3DLength(points: THREE.Vector3[]): number {
   let length = 0;
   for (let i = 1; i < points.length; i++) {
@@ -187,25 +273,38 @@ function calculatePath3DLength(points: THREE.Vector3[]): number {
   return length;
 }
 
+const points = [
+  new THREE.Vector3(0, 0, 0),
+  new THREE.Vector3(5, 2, 3),
+  new THREE.Vector3(10, 1, 6),
+];
+
 const pathLine = {
-  points: [...],
+  points: points,
   totalLength: calculatePath3DLength(points),
   color: new THREE.Color(0x00ccff),
   duration: 3000,
+  lineWidth: 3.0,
 };
 ```
 
+
 ### 结合相机动画
 
-```ts
+```typescript
 // 光带路径随相机移动自动投影
 const pass = new FlowingLight3DPass(camera);
 
 pass.setLines([{
-  points: [...],
+  points: [
+    new THREE.Vector3(-10, 0, 0),
+    new THREE.Vector3(0, 5, 0),
+    new THREE.Vector3(10, 0, 0),
+  ],
   totalLength: 20,
   color: new THREE.Color(0xffff00),
   duration: 3000,
+  lineWidth: 4.0,
 }]);
 
 // 相机动画过程中光带自动跟随投影
@@ -215,18 +314,105 @@ five.setState({
 });
 ```
 
+
+### 高 DPR 场景优化
+
+```typescript
+// InstancedMesh 实现自动优化高 DPR 性能
+// 在 DPR=2 的 Retina 屏幕上,性能显著优于全屏着色器方案
+
+const pass = new FlowingLight3DPass(camera);
+
+// 多条路径在高 DPR 下仍能保持流畅
+const paths = Array.from({ length: 10 }, (_, i) => ({
+  points: [
+    new THREE.Vector3(i * 2, 0, 0),
+    new THREE.Vector3(i * 2, 5, 5),
+  ],
+  totalLength: 7,
+  color: new THREE.Color(Math.random() * 0xffffff),
+  duration: 2000 + i * 100,
+  delay: i * 200,
+  lineWidth: 3.0,
+}));
+
+pass.setLines(paths);
+```
+
+
 ## Debugging
 
-- **光带不可见**：检查路径点是否在相机视锥内；验证 `color` 和 `opacity` 非全透明。
-- **光带抖动或消失**：确认路径在相机背面时自动丢弃（3D 投影的预期行为）。
-- **流速不对**：检查 `totalLength` 计算是否为世界单位；调整 `duration` 以改变流速。
+- **光带不可见**: 检查路径点是否在相机视锥内;验证 `color` 和 `opacity` 非全透明。
+- **光带抖动或消失**: 确认路径在相机背面时自动丢弃(3D 投影的预期行为)。
+- **流速不对**: 检查 `totalLength` 计算是否为世界单位;调整 `duration` 以改变流速。
+- **位置偏移**: 确认在高 DPR 场景下渲染目标尺寸正确,Pass 会自动同步 `readBuffer` 尺寸。
+- **性能问题**: InstancedMesh 实现已优化,但过多路径点仍会影响性能。建议单条路径不超过 20 个点。
+
+## Performance
+
+### 与全屏着色器对比
+- **全屏着色器**: 每帧检查所有像素,DPR=2 时像素数增加 4 倍,性能下降明显
+- **InstancedMesh**: 仅渲染线段覆盖区域,DPR=2 时性能影响较小
+- **实测**: 在 DPR=2 场景下,InstancedMesh 方案 FPS 提升约 3-5 倍
+
+### setLine 性能优化
+`setLine` 方法根据修改类型自动选择最优更新策略:
+
+| 修改类型 | 性能 | 说明 |
+|---------|------|------|
+| 只修改颜色/透明度 | ⚡️ 极快 (~100x) | 只更新 instanceColor attribute |
+| 只修改 duration/delay | ⚡️ 极快 (~100x) | 只更新 instanceMeta attribute |
+| 只修改 lineWidth | ⚡️ 极快 (~100x) | 只更新 instanceData attribute |
+| 修改 points (相同数量) | ⚡️ 快 (~50x) | 只更新 instanceStart/End attributes |
+| 修改 points (不同数量) | ⚠️ 慢 | 重建整个 mesh |
+
+**最佳实践**:
+```ts
+// ✅ 高性能 - 频繁修改颜色
+requestAnimationFrame(() => {
+  pass.setLine({
+    id: lineId,
+    color: new THREE.Color(Math.random(), Math.random(), Math.random())
+  });
+});
+
+// ✅ 高性能 - 动画路径(保持点数)
+function animatePath(t: number) {
+  pass.setLine({
+    id: lineId,
+    points: [
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(5 + Math.sin(t) * 2, 2, 3),
+      new THREE.Vector3(10, 0, 0),
+    ]  // 始终 3 个点
+  });
+}
+
+// ⚠️ 低性能 - 避免频繁改变点数
+setInterval(() => {
+  const pointCount = Math.floor(Math.random() * 5) + 2;
+  pass.setLine({
+    id: lineId,
+    points: generateRandomPoints(pointCount)  // 点数不固定
+  });
+}, 100);
+```
+
+### 优化建议
+1. 减少路径点数量,使用更简化的路径
+2. 降低 `lineWidth`,减少渲染区域
+3. 控制同时渲染的路径数量
+4. 使用 `setLine` 而非 `setLines` 来更新单条线
+5. 保持 points 数量不变,只修改坐标
+6. 在低端设备上可通过 `pass.enabled = false` 禁用
 
 ## Common Pitfalls
 
-1. **totalLength 单位混淆**：必须使用世界坐标单位，不能混用屏幕像素或其他单位。
-2. **投影失败**：确保相机矩阵有效，相机在构造时已初始化。
-3. **路径在背面**：相机背后的点自动投影到屏幕外，无需手动处理。
-4. **未调用 dispose()**：销毁 Pass 时必须调用 `dispose()`，避免 GPU 资源泄漏。
+1. **totalLength 单位混淆**: 必须使用世界坐标单位,不能混用屏幕像素或其他单位。
+2. **投影失败**: 确保相机矩阵有效,相机在构造时已初始化。
+3. **路径在背面**: 相机背后的点自动投影到屏幕外,无需手动处理。
+4. **未调用 dispose()**: 销毁 Pass 时必须调用 `dispose()`,避免 GPU 资源泄漏。
+5. **DPR 不匹配**: 确保渲染目标尺寸与实际屏幕 DPR 匹配,Pass 会自动处理。
 
 ## Related
 
@@ -235,6 +421,5 @@ five.setState({
 
 ---
 
-```yaml
-tags: [postprocessing, effect, flowing, light, pass, rendering, worldspace, projection]
-```
+
+tags: [流光, 光带, 空间轨迹, 模型表面, 特效, postprocessing, effect, flowing, light, pass, rendering, worldspace, projection, instanced, performance, 3d, world-space]

package/ai_guides/features/gaussian-blur-pass.md

@@ -198,5 +198,5 @@ console.log('Resolution:', blurPass['material'].uniforms.resolution.value);
 ---
 
 ```yaml
-tags: [postprocessing, shader, effect, blur, pass, rendering]
+tags: [模糊, 高斯模糊, 毛玻璃, 背景虚化, postprocessing, shader, effect, blur, pass, rendering, gaussian, blur-effect]
 ```

package/ai_guides/features/gesture.md

@@ -44,6 +44,7 @@ interface GestureEvent {
 
 Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：
 
+*   **gesture.fire**: 任意事件被触发。
 *   **gesture.pan**: 拖拽/平移。
 *   **gesture.pinch**: 双指缩放。
 *   **gesture.tap**: 点击。
@@ -176,5 +177,5 @@ five.on("gesture.pinch", (event) => {
 ---
 
 ```yaml
-tags: [gesture, event, interaction, tap, pan, pinch]
+tags: [手势, 点击, 拖拽, 缩放, 长按, 鼠标, 触摸, 交互控制, 自定义交互, gesture, event, interaction, tap, pan, pinch, preventDefault]
 ```

package/ai_guides/features/get-screen-pixels.md

@@ -173,10 +173,10 @@ function getCenterColor(five: Five) {
 
 ## Related
 
-*   [api.md](../api.md): Five 核心 API 说明。
+*   [API Reference](../api.md): Five 核心 API 说明。
 
 ---
 
 ```yaml
-tags: [getPixels, magnifier, screenshot, pixel, canvas]
+tags: [截图, 放大镜, 取色器, 颜色拾取, 像素数据, getPixels, magnifier, screenshot, pixel, canvas, screen-capture, color-picker]
 ```

package/ai_guides/features/image-options.md

@@ -155,10 +155,10 @@ console.log(cutUrl);
 
 ## Related
 
-*   [pano-tile.md](./pano-tile.md): 全景图瓦片加载策略与 WorkTile 数据结构说明。
+*   [Pano Tile](./pano-tile.md): 全景图瓦片加载策略与 WorkTile 数据结构说明。
 
 ---
 
 ```yaml
-tags: [imageOptions, configuration, optimization, cdn, private-deployment]
+tags: [图片配置, 图片格式, 域名映射, 多云部署, 私有化, 图片质量, 流量优化, imageOptions, configuration, optimization, cdn, private-deployment, avif, webp]
 ```

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

@@ -78,7 +78,9 @@ Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
 *   `EXT_texture_webp`
 *   `CESIUM_RTC`
 *   `REALSEE_materials_lightmap`
+*   `KHR_gaussian_splatting`
 *   `KHR_gaussian_splatting_compression_spz`
+*   `KHR_gaussian_splatting_compression_spz_2`
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
@@ -341,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

@@ -136,5 +136,5 @@ five.on("pano.texture.error", (event) => {
 ---
 
 ```yaml
-tags: [loading, progress, refined, loaded, event]
+tags: [加载进度, 加载完成, 首屏, 高清, 细化, 全景加载, 模型加载, loading, progress, refined, loaded, event, tile-load, loading-bar]
 ```

package/ai_guides/features/material.md

@@ -82,6 +82,7 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 | `receiveShadow` | `boolean` | `false` | 模型是否接收阴影。 |
 | `useAddBlend` | `boolean` | `false` | 是否使用半透明叠加渲染。 |
 | `customShaders` | `PBMCustomShader[]` | `[]` | 自定义 Shader 配置。 |
+| `panoFilter` | `PBMPanoFilter` | `null` | 全景图滤镜 (亮度、对比度、色温等)。详情见 [Pano Filter](./pano-filter.md)。 |
 | `clippers` | `PBMClipperParameter[]` | `[]` | 模型裁切参数。 |
 | `boundingBox` | `THREE.Box3` | `Infinity` | 模型包围盒。 |
 
@@ -97,7 +98,7 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 | `constantColor` | `THREE.Vector3` | `(0.6, 0.6, 0.6)` | 模型纯色模式下的颜色值。 |
 | `outlineGain` | `number` | `0.0` | 轮廓线增益。 |
 | `distanceGain` | `number` | `0.0` | 距离增益。 |
-| `gsSHDegree` | `number` | `0` | 3D Gaussian Splatting 的球谐阶数。 |
+| `gaussianSplattingSHDegree` | `number` | `0` | 3D Gaussian Splatting 的球谐阶数。 |
 
 ### Internal & Low-Level (内部与底层配置)
 
@@ -122,30 +123,37 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 ### 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 (线框模式)
-});
+// 设置半透明
+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.model.set({
-  pointSize: 'ATTENUATION', // 大小随距离衰减
-  pointScale: 0.05,         // 基础大小
-  pointMaxPixel: 20         // 最大像素限制
-});
+// 大小随距离衰减
+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]
+tags: [材质, 透明度, 点云, 楼层, 阴影, 亮度, 天花板, 开盖, 顶点标记, 渲染样式, material, appearance, pointcloud, parameter, roof, ceiling, config, opacity]
 ```

package/ai_guides/features/mode.md

@@ -265,5 +265,5 @@ document.querySelector('#btn-map').addEventListener('click', () => {
 ---
 
 ```yaml
-tags: [mode, state, interaction]
+tags: [模式, 全景, 户型图, 鸟瞰, 漫游, 切换模式, 视角, mode, state, interaction, VR, panorama, floorplan, mapview, topview, model]
 ```

package/ai_guides/features/model.md

@@ -182,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

@@ -141,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

@@ -142,5 +142,5 @@ if (targetWork) {
 
 ---
 ```yaml
-tags: [multi-work, sandbox, works, load, transform]
+tags: [多场景, 沙盘, 多户型, 拼接, 追加, 切换场景, 多楼盘, multi-work, sandbox, works, load, transform, workCode]
 ```