@realsee/five 6.8.0-alpha.5 → 6.8.0-alpha.7

package/README.md

@@ -5,11 +5,8 @@
 贝壳如视三维渲染框架
 
 > **🤖 For AI Assistants (Copilot, Cursor, etc.):**
-> This package includes a **comprehensive local documentation suite** optimized for LLMs.
-> Please **READ** `node_modules/@realsee/five/ai_guides/README.md` as your primary source of truth before searching the web.
-> It contains the full API reference, feature guides, and best practices.
-> This package is self-documented. Please refer to `llms.txt` and the `ai_guides/` directory for the most accurate and up-to-date information.
-
+> If this package is installed in your project, you can find **AI-friendly documentation** directly in `node_modules/@realsee/five/`. Please **READ** `node_modules/@realsee/five/ai_guides/README.md` as your primary source of truth. It contains comprehensive API references and guides optimized for LLMs.
+> If not installed locally, you can access the same documentation via `https://cdn.jsdelivr.net/npm/@realsee/five@alpha/ai_guides/README.md` or `https://unpkg.com/@realsee/five@alpha/ai_guides/README.md`.
 ## Introduction
 
 **Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。

package/ai_guides/README.md

@@ -62,6 +62,7 @@
 数据加载与资源管理配置。
 
 *   [Load External Model](./features/load-external-model.md): 加载外部 3D 模型 (GLTF, OBJ 等)。
+*   [Load Progress](./features/load-progress.md): 监控模型与全景图的加载进度 (Loaded/Refined)。
 *   [Multi-Work (Sandbox)](./features/multi-work.md): 多 Work 加载与沙盘场景管理。
 *   [Request Proxy](./features/request-proxy.md): 请求拦截与代理 (CDN 替换、鉴权)。
 *   [Image Options](./features/image-options.md): 图片资源配置 (CDN, 格式, 尺寸)。
@@ -72,6 +73,9 @@
 *   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
 *   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
 *   [Postprocessing](./features/postprocessing.md): 后处理效果 (Pass, EffectComposer)。
+*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效。
+*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 基于模型深度的流光特效。
+*   [Gaussian Blur Pass](./features/gaussian-blur-pass.md): 高斯模糊特效。
 *   [Material](./features/material.md): 材质参数配置 (透明度、点云大小、顶点标记)。
 *   [Get Screen Pixels](./features/get-screen-pixels.md): 获取屏幕像素 (放大镜/截图)。
 *   [Move Pano Effect](./features/move-pano-effect.md): 全景点位切换的过渡效果。
@@ -98,6 +102,7 @@
 *   [Support](./support.md): 浏览器兼容性。
 *   [AI Documentation Guidelines](./ai-doc-guidelines.md): AI 文档编写与维护规范 (必读)。
 *   Release Notes: 版本更新记录。
+    *   [6.8](./release_notes/6.8.md)
     *   [6.7](./release_notes/6.7.md)
     *   [6.6](./release_notes/6.6.md)
 

package/ai_guides/api.md

@@ -139,6 +139,16 @@ Get pixel data from the renderer (e.g. for color picking or magnifier).
 - **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.
 
@@ -223,7 +233,10 @@ These events follow a standard naming convention and provide typed event objects
 | :--- | :--- | :--- |
 | `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` |
 

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

@@ -0,0 +1,218 @@
+# Flowing Light 2D Pass (流光 2D 通道)
+
+- **Summary**: `FlowingLight2DPass` 提供屏幕空间的流光（光带）特效，沿着 2D 路径点绘制动态光流，适用于突出导航路径、指示线或动态路径演示。
+- **Schema**: `FlowingLight2DPass` 类及 Line 数据结构。
+- **Concepts**: 后处理通道、屏幕空间光带、路径数据驱动、时间动画。
+- **Configuration**: 路径点集合、颜色、不透明度、动画时长。
+- **Examples**: 基础集成、多条路径、动态更新。
+
+## Schema
+
+> **Definition**: [FlowingLight2DPass](../../five/renderer/postprocessing/passes/flowing-light-2d-pass.d.ts)
+
+`FlowingLight2DPass` 是 `FivePass` 的子类，核心接口如下：
+
+```ts
+import * as THREE from 'three';
+import { FivePass } from './pass';
+import { type Camera } from '../../../core/camera';
+
+type Line = {
+  points: THREE.Vector2[];      // 屏幕空间路径点 [x, y]
+  totalLength: number;           // 路径总长度（像素）
+  color: THREE.Color;            // 光带颜色
+  opacity?: number;              // 光带不透明度（0-1）
+  duration?: number;             // 动画时长（毫秒）
+};
+
+export class FlowingLight2DPass extends FivePass {
+  constructor(camera: Camera);
+
+  // 设置要渲染的路径列表
+  public setLines(lines: Line[]): void;
+
+  public render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime: number,
+    maskActive?: boolean,
+  ): void;
+
+  public dispose(): void;
+}
+```
+
+## Concepts
+
+### 屏幕空间路径 (Screen-space Lines)
+路径点在屏幕坐标系中定义（像素单位），不受 3D 场景变化影响。光流沿路径顶点顺序流动，自动计算相邻顶点间距离。
+
+### 时间驱动光头 (Time-driven Head)
+光带"头部"根据 `duration` 和经过时间循环移动。`duration` 定义一个完整周期（从起点到终点再回到起点）所需的毫秒数。光带尾部长度固定为路径总长的 1/4。
+
+### 数据纹理驱动 (Data Texture)
+路径数据编码为 Float32 纹理上传到 GPU，使 shader 能高效计算光效。支持同时渲染多条路径。
+
+## Configuration
+
+### Line 配置参数
+
+| Parameter | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `points` | `THREE.Vector2[]` | ✓ | - | 屏幕空间路径点数组。至少 2 个点。 |
+| `totalLength` | `number` | ✓ | - | 路径总长度（像素）。通常为所有相邻点间距离之和。 |
+| `color` | `THREE.Color` | ✓ | - | 光带颜色（RGB）。 |
+| `opacity` | `number` | | `1` | 光带不透明度（0-1）。控制与背景的混合强度。 |
+| `duration` | `number` | | `1000` | 动画周期（毫秒）。光头从路径起点完成一个周期的时长。 |
+
+> **注意**: `totalLength` 应精确计算。若传入错误值，光流速度会显著偏差。
+
+## Instance Methods
+
+### `constructor(camera: Camera)`
+初始化 Pass，需传入相机以获取屏幕分辨率。
+
+### `setLines(lines: Line[])`
+更新要渲染的路径列表。可随时调用以修改或新增路径。
+
+**示例**：
+```ts
+const pathLine: Line = {
+  points: [
+    new THREE.Vector2(100, 100),
+    new THREE.Vector2(300, 150),
+    new THREE.Vector2(500, 100),
+  ],
+  totalLength: 400,  // 实际路径总长度
+  color: new THREE.Color(0x00c2ff),
+  opacity: 0.8,
+  duration: 2000,
+};
+pass.setLines([pathLine]);
+```
+
+### `render(...)`
+由 EffectComposer 自动调用，无需手动调用。
+
+### `dispose()`
+释放着色材质和纹理资源，避免内存泄漏。销毁 Pass 时必须调用。
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+```ts
+import { Five } from '@realsee/five';
+import { FlowingLight2DPass } from '../../lib/five/renderer/postprocessing';
+import * as THREE from 'three';
+
+const five = new Five();
+
+// 创建 2D 流光通道
+const flowing2D = new FlowingLight2DPass(five.camera);
+
+// 定义一条屏幕空间的路径
+const path = [
+  new THREE.Vector2(100, 100),
+  new THREE.Vector2(300, 200),
+  new THREE.Vector2(500, 100),
+  new THREE.Vector2(700, 250),
+];
+const totalLen = 600; // 近似路径长度
+
+flowing2D.setLines([{
+  points: path,
+  totalLength: totalLen,
+  color: new THREE.Color(0x00ff00),
+  opacity: 0.9,
+  duration: 2000,
+}]);
+
+five.addPass(flowing2D);
+
+function animate() {
+  requestAnimationFrame(animate);
+  five.render();
+}
+animate();
+```
+
+### 多条路径 & 动态更新
+
+```ts
+const pass = new FlowingLight2DPass(five.camera);
+
+// 初始路径集合
+const paths = [
+  {
+    points: [...],
+    totalLength: 500,
+    color: new THREE.Color(0xff6600),
+    duration: 1500,
+  },
+  {
+    points: [...],
+    totalLength: 400,
+    color: new THREE.Color(0x0066ff),
+    opacity: 0.7,
+    duration: 2000,
+  },
+];
+
+pass.setLines(paths);
+five.addPass(pass);
+
+// 响应用户交互动态更新路径
+document.addEventListener('click', (e) => {
+  const newPath = {
+    points: [/* 鼠标点击生成的路径点 */],
+    totalLength: 300,
+    color: new THREE.Color(Math.random() * 0xffffff),
+    duration: 1200,
+  };
+  pass.setLines([...paths, newPath]);
+});
+```
+
+### 计算路径总长度
+
+```ts
+function calculatePathLength(points: THREE.Vector2[]): number {
+  let length = 0;
+  for (let i = 1; i < points.length; i++) {
+    length += points[i].distanceTo(points[i - 1]);
+  }
+  return length;
+}
+
+const pathLine = {
+  points: [...],
+  totalLength: calculatePathLength(points),
+  color: new THREE.Color(0x00ffff),
+  duration: 2000,
+};
+```
+
+## Debugging
+
+- **光带不出现**：检查 `color` 和 `opacity`，确保非全透明；验证 `points` 至少 2 个。
+- **流速不对**：检查 `totalLength` 计算是否准确；若流速过快/过慢，调整 `duration`。
+- **性能问题**：降低路径点数或使用更简单的路径。
+
+## Common Pitfalls
+
+1. **totalLength 计算错误**：光流速度直接依赖 `totalLength`。手动计算时务必精确。
+2. **屏幕坐标系混淆**：`points` 使用屏幕坐标（原点通常在左下角），不是 Canvas 默认坐标系。
+3. **未及时 dispose()**：移除 Pass 时必须调用 `dispose()`，否则 GPU 纹理资源泄漏。
+
+## Related
+
+*   [Postprocessing](./postprocessing.md): 后处理通用概念与 EffectComposer 使用指南。
+*   [Flowing Light 3D Pass](./flowing-light-3d-pass.md): 基于 3D 世界坐标的流光效果。
+
+---
+
+```yaml
+tags: [postprocessing, effect, flowing, light, pass, rendering, screenspace]
+```

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

@@ -0,0 +1,240 @@
+# Flowing Light 3D Pass (流光 3D 通道)
+
+- **Summary**: `FlowingLight3DPass` 基于 3D 世界坐标绘制流光效果，自动投影到屏幕空间，适合沿模型表面、路径或空间轨迹演示动态流动光带。
+- **Schema**: `FlowingLight3DPass` 类及 Line 数据结构。
+- **Concepts**: 基于相机投影的 3D 光带、世界坐标到屏幕坐标映射、动画驱动。
+- **Configuration**: 3D 路径点、颜色、不透明度、动画周期。
+- **Examples**: 空间轨迹演示、结合相机动画、多条 3D 路径。
+
+## Schema
+
+> **Definition**: [FlowingLight3DPass](../../five/renderer/postprocessing/passes/flowing-light-3d-pass.d.ts)
+
+`FlowingLight3DPass` 继承自 `FivePass`，支持投影到当前相机视锥。核心接口如下：
+
+```ts
+import * as THREE from 'three';
+import { FivePass } from './pass';
+import { type Camera } from '../../../core/camera';
+
+type Line = {
+  points: THREE.Vector3[];      // 世界坐标系路径点
+  totalLength: number;           // 路径总长度（世界单位）
+  color: THREE.Color;            // 光带颜色
+  opacity?: number;              // 光带不透明度（0-1）
+  duration?: number;             // 动画周期（毫秒）
+};
+
+export class FlowingLight3DPass extends FivePass {
+  constructor(camera: Camera);
+
+  // 设置要渲染的路径列表
+  public setLines(lines: Line[]): void;
+
+  public render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime: number,
+    maskActive?: boolean,
+  ): void;
+
+  public dispose(): void;
+}
+```
+
+## Concepts
+
+### 世界空间路径与投影 (World-space Projection)
+路径点定义在 3D 世界坐标系中。Pass 内部自动根据当前相机投影矩阵将 3D 点映射到屏幕空间，从而实现"随相机变化"的动态光带效果。
+
+### 循环流动 (Looping Flow)
+默认使用循环模式（`LOOP = true`），光头在路径上循环流动，无起点/终点的区分。尾部长度为路径总长的 1/4。
+
+### 相机同步
+Pass 自动同步相机的投影矩阵和视图矩阵，无需手动管理。支持相机运动时光带跟随。
+
+## Configuration
+
+### Line 配置参数
+
+| Parameter | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `points` | `THREE.Vector3[]` | ✓ | - | 世界坐标系路径点数组。至少 2 个点。 |
+| `totalLength` | `number` | ✓ | - | 路径总长度（世界单位）。通常为所有相邻点间距离之和。 |
+| `color` | `THREE.Color` | ✓ | - | 光带颜色（RGB）。 |
+| `opacity` | `number` | | `1` | 光带不透明度（0-1）。控制与背景的混合强度。 |
+| `duration` | `number` | | `1000` | 动画周期（毫秒）。光头完成一个循环所需时长。 |
+
+> **注意**: `totalLength` 应为世界坐标单位。若不准确，流速会偏差。
+
+## Instance Methods
+
+### `constructor(camera: Camera)`
+初始化 Pass，需传入相机以获取投影矩阵和视图矩阵。
+
+### `setLines(lines: Line[])`
+更新要渲染的路径列表。支持运行时动态更改。
+
+**示例**：
+```ts
+const pathLine: Line = {
+  points: [
+    new THREE.Vector3(0, 0, 0),
+    new THREE.Vector3(5, 2, 3),
+    new THREE.Vector3(10, 1, 6),
+  ],
+  totalLength: 12,  // 世界坐标单位
+  color: new THREE.Color(0xff6600),
+  opacity: 0.85,
+  duration: 3000,
+};
+pass.setLines([pathLine]);
+```
+
+### `render(...)`
+由 EffectComposer 自动调用，无需手动调用。自动同步相机矩阵。
+
+### `dispose()`
+释放着色材质和数据纹理资源，销毁 Pass 时必须调用。
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+```ts
+import { Five } from '@realsee/five';
+import { FlowingLight3DPass } from '../../lib/five/renderer/postprocessing';
+import * as THREE from 'three';
+
+const five = new Five();
+
+// 创建 3D 流光通道
+const flowing3D = new FlowingLight3DPass(five.camera);
+
+// 定义一条 3D 路径（世界坐标）
+const path = [
+  new THREE.Vector3(-5, 0, 0),
+  new THREE.Vector3(-2, 3, 2),
+  new THREE.Vector3(2, 3, -2),
+  new THREE.Vector3(5, 0, 0),
+];
+const totalLen = 15;  // 世界单位
+
+flowing3D.setLines([{
+  points: path,
+  totalLength: totalLen,
+  color: new THREE.Color(0x00ff88),
+  opacity: 0.8,
+  duration: 4000,
+}]);
+
+five.addPass(flowing3D);
+
+function animate() {
+  requestAnimationFrame(animate);
+  five.render();
+}
+animate();
+```
+
+### 多条 3D 路径
+
+```ts
+const pass = new FlowingLight3DPass(camera);
+
+const paths = [
+  {
+    points: [
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(10, 5, 0),
+    ],
+    totalLength: 11,
+    color: new THREE.Color(0xff0000),
+    duration: 2000,
+  },
+  {
+    points: [
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(0, 10, 5),
+    ],
+    totalLength: 12,
+    color: new THREE.Color(0x00ff00),
+    duration: 2500,
+  },
+  {
+    points: [
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(5, 0, 10),
+    ],
+    totalLength: 11,
+    color: new THREE.Color(0x0000ff),
+    duration: 2200,
+  },
+];
+
+pass.setLines(paths);
+```
+
+### 计算 3D 路径长度
+
+```ts
+function calculatePath3DLength(points: THREE.Vector3[]): number {
+  let length = 0;
+  for (let i = 1; i < points.length; i++) {
+    length += points[i].distanceTo(points[i - 1]);
+  }
+  return length;
+}
+
+const pathLine = {
+  points: [...],
+  totalLength: calculatePath3DLength(points),
+  color: new THREE.Color(0x00ccff),
+  duration: 3000,
+};
+```
+
+### 结合相机动画
+
+```ts
+// 光带路径随相机移动自动投影
+const pass = new FlowingLight3DPass(camera);
+
+pass.setLines([{
+  points: [...],
+  totalLength: 20,
+  color: new THREE.Color(0xffff00),
+  duration: 3000,
+}]);
+
+// 相机动画过程中光带自动跟随投影
+five.setState({
+  mode: Five.Mode.Model,
+  // ... 其他参数
+});
+```
+
+## Debugging
+
+- **光带不可见**：检查路径点是否在相机视锥内；验证 `color` 和 `opacity` 非全透明。
+- **光带抖动或消失**：确认路径在相机背面时自动丢弃（3D 投影的预期行为）。
+- **流速不对**：检查 `totalLength` 计算是否为世界单位；调整 `duration` 以改变流速。
+
+## Common Pitfalls
+
+1. **totalLength 单位混淆**：必须使用世界坐标单位，不能混用屏幕像素或其他单位。
+2. **投影失败**：确保相机矩阵有效，相机在构造时已初始化。
+3. **路径在背面**：相机背后的点自动投影到屏幕外，无需手动处理。
+4. **未调用 dispose()**：销毁 Pass 时必须调用 `dispose()`，避免 GPU 资源泄漏。
+
+## Related
+
+*   [Postprocessing](./postprocessing.md): 后处理通用概念与 EffectComposer 使用指南。
+*   [Flowing Light 2D Pass](./flowing-light-2d-pass.md): 屏幕空间的流光效果。
+
+---
+
+```yaml
+tags: [postprocessing, effect, flowing, light, pass, rendering, worldspace, projection]
+```