@realsee/five 6.8.0-alpha.0 → 6.8.0-alpha.10

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

@@ -0,0 +1,420 @@
+# Flowing Light 3D Pass (流光 3D 通道)
+
+- **Summary**: `FlowingLight3DPass` 基于 3D 世界坐标绘制流光效果,使用 InstancedMesh 实例化渲染优化性能,自动投影到屏幕空间,适合沿模型表面、路径或空间轨迹演示动态流动光带。
+- **Schema**: `FlowingLight3DPass` 类及 Line 数据结构。
+- **Concepts**: 基于相机投影的 3D 光带、InstancedMesh 实例化渲染、世界坐标到屏幕坐标映射、头尾追逐动画。
+- **Configuration**: 3D 路径点、颜色、不透明度、线宽、动画周期、延迟。
+- **Examples**: 空间轨迹演示、结合相机动画、多条 3D 路径、高 DPR 场景优化。
+
+## 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 = {
+  id?: string;                   // 可选的唯一标识符,不传则自动生成 UUID
+  points: THREE.Vector3[];      // 世界坐标系路径点
+  totalLength: number;           // 路径总长度(世界单位)
+  color: THREE.Color;            // 光带颜色
+  opacity?: number;              // 光带不透明度(0-1)
+  duration?: number;             // 动画周期(毫秒)
+  delay?: number;                // 动画延迟(毫秒)
+  lineWidth?: number;            // 线宽(像素)
+  tailLengthRatio?: number;      // 尾巴长度比例(0-1),默认 0.2
+};
+
+export class FlowingLight3DPass extends FivePass {
+  constructor(camera: Camera);
+
+  // 设置要渲染的路径列表
+  public setLines(lines: Line[]): void;
+
+  // 修改单条线的参数(通过 id)
+  public setLine(params: { id: string } & Partial<Omit<Line, 'id'>>): void;
+
+  public render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime: number,
+    maskActive?: boolean,
+  ): void;
+
+  public dispose(): void;
+}
+```
+## Concepts
+
+### InstancedMesh 实例化渲染 (Instanced Rendering)
+为了优化高 DPR(Device Pixel Ratio)场景下的性能,该 Pass 使用 InstancedMesh 代替全屏着色器。每个线段作为一个实例,只渲染线段覆盖的区域,避免了对每个像素的全屏检查,显著提升了渲染效率。
+
+### 世界空间路径与投影 (World-space Projection)
+路径点定义在 3D 世界坐标系中。Pass 内部自动根据当前相机投影矩阵将 3D 点映射到屏幕空间,从而实现"随相机变化"的动态光带效果。
+
+### 头尾追逐动画 (Head-Tail Chase Animation)
+流光效果采用"头尾追逐"模式:
+- **头部(Head)**: 光流的前端,沿路径循环移动
+- **尾部(Tail)**: 光流的后端,跟随头部移动
+- **渐变**: 从尾部(透明度 0)到头部(透明度 1)线性渐变
+- **尾长**: 尾部长度由 `tailLengthRatio` 参数控制(默认 0.2,即路径总长的 20%)
+
+光头在路径上循环流动,通过 `gl_FragCoord` 投影到线段上计算每个像素的渐变位置,确保渐变效果准确。尾巴长度会在动画开始时逐渐增长,直到达到 `tailLengthRatio * totalLength`。
+
+### 相机同步
+Pass 自动同步相机的投影矩阵和视图矩阵,无需手动管理。支持相机运动时光带跟随。
+
+### DPR 处理
+自动处理高 DPR 场景,渲染目标尺寸根据 `readBuffer` 自动调整,确保在 Retina 等高分辨率屏幕上位置准确且性能优化。
+
+## Configuration
+
+### Line 配置参数
+
+| Parameter | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `id` | `string` | | 自动生成 UUID | 唯一标识符,用于 `setLine` 方法更新单条线。 |
+| `points` | `THREE.Vector3[]` | ✓ | - | 世界坐标系路径点数组。至少 2 个点。 |
+| `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` 应为世界坐标单位。若不准确,流速会偏差。
+
+## Instance Methods
+
+### `constructor(camera: Camera)`
+初始化 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),
+    new THREE.Vector3(10, 1, 6),
+  ],
+  totalLength: 12,  // 世界坐标单位
+  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 自动调用,无需手动调用。自动同步相机矩阵和渲染目标尺寸。
+
+### `dispose()`
+释放 InstancedMesh、着色材质和渲染目标资源,销毁 Pass 时必须调用。
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+
+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,
+  lineWidth: 3.0,
+}]);
+
+five.addPass(flowing3D);
+
+function animate() {
+  requestAnimationFrame(animate);
+  five.render();
+}
+animate();
+
+
+### 多条 3D 路径
+
+
+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,
+    lineWidth: 3.0,
+  },
+  {
+    points: [
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(0, 10, 5),
+    ],
+    totalLength: 12,
+    color: new THREE.Color(0x00ff00),
+    duration: 2500,
+    delay: 500,
+    lineWidth: 4.0,
+  },
+  {
+    points: [
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(5, 0, 10),
+    ],
+    totalLength: 11,
+    color: new THREE.Color(0x0000ff),
+    duration: 2200,
+    delay: 1000,
+    lineWidth: 2.5,
+  },
+];
+
+pass.setLines(paths);
+
+
+### 计算 3D 路径长度
+
+
+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 points = [
+  new THREE.Vector3(0, 0, 0),
+  new THREE.Vector3(5, 2, 3),
+  new THREE.Vector3(10, 1, 6),
+];
+
+const pathLine = {
+  points: points,
+  totalLength: calculatePath3DLength(points),
+  color: new THREE.Color(0x00ccff),
+  duration: 3000,
+  lineWidth: 3.0,
+};
+
+
+### 结合相机动画
+
+
+// 光带路径随相机移动自动投影
+const pass = new FlowingLight3DPass(camera);
+
+pass.setLines([{
+  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,
+}]);
+
+// 相机动画过程中光带自动跟随投影
+five.setState({
+  mode: Five.Mode.Model,
+  // ... 其他参数
+});
+
+
+### 高 DPR 场景优化
+
+
+// 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` 以改变流速。
+- **位置偏移**: 确认在高 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 资源泄漏。
+5. **DPR 不匹配**: 确保渲染目标尺寸与实际屏幕 DPR 匹配,Pass 会自动处理。
+
+## Related
+
+*   [Postprocessing](./postprocessing.md): 后处理通用概念与 EffectComposer 使用指南。
+*   [Flowing Light 2D Pass](./flowing-light-2d-pass.md): 屏幕空间的流光效果。
+
+---
+
+
+tags: [postprocessing, effect, flowing, light, pass, rendering, worldspace, projection, instanced, performance]

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

@@ -0,0 +1,202 @@
+# Gaussian Blur Pass (高斯模糊通道)
+
+- **Summary**: GaussianBlurPass 是一个后处理通道，用于对渲染结果应用高斯模糊效果。
+- **Schema**: GaussianBlurPass 类及其关键参数。
+- **Concepts**: 后处理通道 (Pass)、高斯模糊、Shader、EffectComposer。
+- **Configuration**: 模糊半径 (radius) 和标准差 (sigma) 参数。
+- **Examples**: 基础使用、参数调整。
+
+## Schema
+
+> **Definition**: [GaussianBlurPass](../../five/renderer/postprocessing/passes/gaussian-blur-pass.d.ts)
+
+`GaussianBlurPass` 是 `FivePass` 的子类，用于实现高斯模糊效果。其核心接口如下：
+
+```ts
+import * as THREE from 'three';
+import { FivePass } from './pass';
+import { type Camera } from '../../../core/camera';
+
+export class GaussianBlurPass extends FivePass {
+  // 构造函数，传入相机实例
+  constructor(camera: Camera);
+
+  // 设置模糊半径
+  public setRadius(radius: number): void;
+
+  // 渲染方法（由 EffectComposer 调用）
+  public render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime: number,
+    maskActive?: boolean,
+  ): void;
+
+  // 释放资源
+  public dispose(): void;
+}
+```
+
+### Shader Uniforms (内部 Shader 参数)
+
+该通道使用 ShaderMaterial，包含以下 uniforms：
+
+| Uniform | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `colorMap` | `THREE.Texture` | `null` | 输入纹理（来自 readBuffer） |
+| `resolution` | `THREE.Vector2` | `相机分辨率` | 渲染目标的分辨率 |
+| `radius` | `number` | `4.0` | 模糊采样半径（像素数） |
+| `sigma` | `number` | `4.0` | 高斯核的标准差 |
+
+## Concepts
+
+### 后处理通道 (Post-Processing Pass)
+GaussianBlurPass 是 Three.js EffectComposer 生态中的一个通道。它接收前一个通道的输出（readBuffer），进行高斯模糊处理后，输出到下一个通道或屏幕（writeBuffer 或 renderToScreen）。
+
+### 高斯模糊原理
+该通道采用离散高斯核进行模糊。在 fragment shader 中：
+- 对采样范围内的像素（由 `radius` 定义）计算高斯权重
+- 根据 `sigma` 值计算高斯分布的形状
+- 对所有采样点的颜色值加权平均
+
+### 相机依赖
+构造函数需传入 `Camera` 实例，用于获取当前渲染分辨率。通过 `camera.resolution` 自动同步分辨率变化，确保模糊效果在窗口 resize 时保持正确。
+
+## Configuration
+
+### 常用参数
+
+通过 `setRadius()` 方法调整模糊效果强度：
+
+| Parameter | Type | Default | Range | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `radius` | `number` | `4.0` | `0 ~ 8` | 采样半径（像素），值越大模糊越明显 |
+| `sigma` | `number` | `4.0` | `0.1 ~ 10` | 高斯核标准差，控制模糊的柔和度 |
+
+> 注意：当前实现中 `sigma` 固定为 4.0，仅 `radius` 可动态调整。如需修改 `sigma`，需直接访问 `material.uniforms.sigma.value`。
+
+## Instance Methods
+
+### `constructor(camera: Camera)`
+初始化高斯模糊通道，需传入相机实例以获取分辨率信息。
+
+### `setRadius(radius: number)`
+动态调整模糊半径。
+- **参数**: `radius` - 采样半径，建议范围 1 ~ 8
+- **默认值**: 4.0
+- **影响**: 较大的 radius 会增加 GPU 计算成本
+
+### `render(...)`
+由 EffectComposer 在每一帧自动调用，用于执行模糊处理。通常不需要手动调用。
+
+### `dispose()`
+释放 Shader Material 和 FullScreenQuad 资源。在销毁 Pass 时必须调用，以防内存泄漏。
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+```ts
+import { Five } from '@realsee/five';
+import { GaussianBlurPass } from '../../lib/five/renderer/postprocessing';
+
+const five = new Five();
+
+// 使用 Five 的 addPass() 方法添加后处理通道
+const blurPass = new GaussianBlurPass(five.camera);
+five.addPass(blurPass);
+
+// 动画循环由 Five 内部管理
+function animate() {
+  requestAnimationFrame(animate);
+  five.render();
+}
+animate();
+```
+
+### 进阶用法 (Advanced Usage)
+
+#### 动态调整模糊强度
+
+```ts
+const blurPass = new GaussianBlurPass(five.camera);
+five.addPass(blurPass);
+
+// 响应用户输入调整模糊半径
+document.addEventListener('keydown', (e) => {
+  if (e.key === '+') {
+    const current = blurPass['material'].uniforms.radius.value;
+    blurPass.setRadius(Math.min(8, current + 0.5));
+  }
+  if (e.key === '-') {
+    const current = blurPass['material'].uniforms.radius.value;
+    blurPass.setRadius(Math.max(0, current - 0.5));
+  }
+});
+```
+
+#### 多通道组合（模糊 + 其他效果）
+
+```ts
+// Five 的 addPass() 会自动管理后处理链
+const blurPass = new GaussianBlurPass(five.camera);
+five.addPass(blurPass);
+
+// 可添加其他后处理通道
+// five.addPass(otherPass);
+```
+
+#### 修改高斯标准差 (Advanced)
+
+```ts
+const blurPass = new GaussianBlurPass(five.camera);
+five.addPass(blurPass);
+
+// 获取 Material 并直接修改 sigma
+const sigmaMaterial = blurPass['material'] as THREE.ShaderMaterial;
+sigmaMaterial.uniforms.sigma.value = 2.0;  // 调整标准差（更强锐利）
+```
+
+## Debugging
+
+### 检查模糊效果是否生效
+- 确保 `renderToScreen` 为 `true`，或后续通道正确读取该通道的输出。
+- 确保传入的 `camera` 对象有有效的 `resolution` 属性。
+
+### 性能优化建议
+- 大 `radius` 值会导致 GPU 开销增加。建议在性能受限的设备上限制最大 radius（如 ≤ 6）。
+- 考虑在低端设备上禁用该通道（设置 `blurPass.enabled = false`）。
+
+### 可视化调试
+```ts
+// 监控当前模糊参数
+const blurPass = new GaussianBlurPass(five.camera);
+console.log('Blur Radius:', blurPass['material'].uniforms.radius.value);
+console.log('Blur Sigma:', blurPass['material'].uniforms.sigma.value);
+console.log('Resolution:', blurPass['material'].uniforms.resolution.value);
+```
+
+## Common Pitfalls
+
+1. **忘记调用 dispose()**
+   - 销毁 Pass 时，必须调用 `blurPass.dispose()` 释放 Shader 资源，否则会导致内存泄漏。
+
+2. **分辨率变化未更新**
+   - GaussianBlurPass 会自动从 `camera.resolution` 同步分辨率，无需手动处理。但如果使用自定义相机，需确保其 `resolution` 属性始终有效。
+
+3. **设置过大的 radius**
+   - 超过 8 的 radius 值虽然技术上可行，但会显著增加计算成本。建议不超过 8。
+
+4. **与其他 Pass 的 needsSwap 冲突**
+   - 如果通道链中多个 Pass 设置了不同的 `needsSwap` 值，可能导致缓冲区错乱。确保通道顺序和 swap 设置一致。
+
+## Related
+
+*   [Postprocessing](./postprocessing.md): 后处理通用概念与 EffectComposer 使用指南。
+
+---
+
+```yaml
+tags: [postprocessing, shader, effect, blur, pass, rendering]
+```