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

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]
+```

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

@@ -34,6 +34,7 @@ interface BaseLoaderOptions {
   modelUpAxis?: 'Y' | 'Z';    // (部分加载器支持) 原始模型的上轴，用于自动旋转修正
   fetcher?: Fetcher;          // 自定义网络请求 Fetcher
   light?: boolean;            // 是否使用简化/无光照材质 (取决于加载器实现)
+  onDownloadProgress?: (progress: { loaded: number, total: number }) => void; // 下载进度回调
 }
 ```
 
@@ -60,6 +61,21 @@ 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`
+*   `EXT_texture_webp`
+*   `CESIUM_RTC`
+*   `REALSEE_materials_lightmap`
+*   `PBM_mesh`
+*   `KHR_gaussian_splatting_compression_spz`
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |

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/parameter.md

@@ -88,6 +88,13 @@ graph TD
   Model -->|Inherit| Layer2[ViewLayer.parameter]
 ```
 
+> **Global Configuration (全局设置)**:
+> 若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），**请直接配置 `five.modelScene.parameter`**。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。
+>
+> **Why modelScene? (生命周期优势)**:
+> `Model` 实例是跟随 Work 加载生命周期的（需 `five.load(work)` 后才能访问，且切换 Work 会销毁重建）。
+> 相比之下，`ModelScene` 是常驻对象。因此，**使用 `modelScene` 进行配置更安全且持久**，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。
+
 ## Examples
 
 ### 1. 基础配置 (Basic Usage)

package/ai_guides/features/postprocessing.md

@@ -1,6 +1,6 @@
 # 后处理 (Post Processing)
 
-- **Summary**: Five 提供了基于 EffectComposer 的后处理机制，内置了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，并支持开发者编写自定义 Pass。
+- **Summary**: Five 提供了基于 EffectComposer 的后处理机制，默认挂载了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，同时提供多种可选内置 Pass，并支持开发者编写自定义 Pass。
 - **Schema**: `FivePass` 类及 `Pass` 接口。
 - **Concepts**: EffectComposer, G-Buffer, Pass, AdaptiveLuminance, EyeDomeLighting。
 - **Configuration**: 开启内置 Pass 的开关及参数配置。
@@ -57,7 +57,7 @@ export class FivePass implements Pass {
 
 ## Built-in Passes (内置 Pass)
 
-Five 内置了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭状态。
+Five 默认挂载了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭状态。
 
 ### 1. AdaptiveLuminancePass
 
@@ -80,6 +80,36 @@ Five 内置了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭
     *   `radius` (number): 采样半径，影响阴影的范围。
 *   **注意**: 这是一个基于屏幕空间深度的算法，依赖 Depth Buffer。
 
+### 3. Optional Built-in Passes (可选内置 Pass)
+
+Five 新增了三个可选使用的内置 Pass，这些 Pass 没有预先挂载在 `five` 实例上，需手动导入并添加到渲染链中：
+
+*   **[GaussianBlurPass](gaussian-blur-pass.md)**: 高斯模糊效果。
+*   **[FlowingLight2DPass](flowing-light-2d-pass.md)**: 2D 流光效果（通常用于平面路线流光）。
+*   **[FlowingLight3DPass](flowing-light-3d-pass.md)**: 3D 流光效果（通常用于空间路径流光）。
+
+#### GaussianBlurPass 使用示例
+
+```typescript
+import { GaussianBlurPass } from '@realsee/five';
+
+// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)
+const gaussianBlurPass = new GaussianBlurPass(five.camera);
+
+// 2. 配置参数
+// 设置模糊半径 (默认 4.0)
+gaussianBlurPass.setRadius(6);
+
+// 3. 将 Pass 添加到渲染链
+five.addPass(gaussianBlurPass);
+
+// 4. (可选) 动态开关
+// gaussianBlurPass.enabled = false;
+
+// 5. (可选) 移除 Pass
+// five.removePass(gaussianBlurPass);
+```
+
 ## Custom Pass (自定义 Pass)
 
 如果需要实现自定义的后处理效果（如景深、色彩校正、描边等），建议继承 `FivePass`。
@@ -216,6 +246,9 @@ class FogPass extends FivePass {
 
 ## Related
 
+*   [Gaussian Blur Pass](gaussian-blur-pass.md): 高斯模糊 Pass 文档。
+*   [Flowing Light 2D Pass](flowing-light-2d-pass.md): 2D 流光 Pass 文档。
+*   [Flowing Light 3D Pass](flowing-light-3d-pass.md): 3D 流光 Pass 文档。
 *   [five.ts](../../five/application/five.d.ts): 查看 `addPass` 方法的实现。
 *   [pass.ts](../../five/renderer/postprocessing/passes/pass.d.ts): 查看 `FivePass` 基类定义。
 

package/ai_guides/features/raycast.md

@@ -43,6 +43,15 @@ declare module 'three' {
      */
     floorIndex?: number;
   }
+
+  export interface Intersection {
+    /** 命中的具体 Tile 对象 (仅 3DTiles) */
+    tile?: Tile;
+    /** 命中的 ViewLayer 对象 */
+    viewLayer?: ViewLayer;
+    /** 命中的 Model 对象 */
+    model?: Model;
+  }
 }
 ```
 

package/ai_guides/features/view-layer.md

@@ -88,14 +88,19 @@ graph TD
 
 ### 4. Visibility Control (可见性控制)
 
-默认情况下，**所有**定义在 `work.model.layers` 中的图层都会被加载并显示。
+默认情况下，Five **不会**加载所有图层，而是根据优先级**仅加载一个**图层，以节省资源。
+优先级顺序：`mesh` > `point_cloud` > 其他类型。
+
+**可见性与内存管理 (Visibility & Memory)**:
+*   **显示 (Show)**: 当图层设置为可见 (`visible = true`) 时，Five 会开始加载该图层的资源。
+*   **隐藏 (Hide)**: 当图层设置为隐藏 (`visible = false`) 时，Five 会**释放该图层占用的所有内存资源** (Geometry, Texture 等)。这意味着“隐藏”等同于“卸载”。
 
 Five 提供了两种层级的可见性控制方式：
 
 1.  **初始化配置 (Load Options)**:
     在 `five.load` 时，通过 `model["3d-tiles"].showLayers` 参数指定初始显示的图层。
-    *   `true` (默认): 显示所有图层。
-    *   `string[]`: 仅显示名称在数组中的图层（例如 `['mesh']` 只显示模型，隐藏点云）。
+    *   `true` (默认): 使用上述的默认优先级策略（仅加载一个最佳图层）。
+    *   `string[]`: 仅显示名称在数组中的图层（例如 `['mesh', 'point_cloud']` 可以强制同时显示模型和点云）。
 
 2.  **运行时控制 (Runtime Control)**:
     加载完成后，可以直接修改 `viewLayer.visible` 属性来切换可见性。

package/ai_guides/features/work.md

@@ -15,6 +15,8 @@
 import * as THREE from "three";
 import type { Mode } from "@realsee/five";
 
+type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
+
 /** Work 实体：VR 项目的根对象 */
 export interface Work {
   /** 唯一标识 (Work ID) */
@@ -74,6 +76,21 @@ export interface WorkObserver {
 
   /** 点位全景图资源信息 */
   images: WorkImage;
+
+  /** 获取点位的全局坐标 */
+  getWorldPosition(this: WorkObserver): THREE.Vector3;
+
+  /** 获取点位的全局地面坐标 */
+  getWorldStandingPosition(this: WorkObserver): THREE.Vector3;
+
+  /** 将方向向量转化为全景图 uv */
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  /** 将全景图 uv 转化为方向向量 */
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  /** 将方向向量转化为获六视图 uv */
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];
+  /** 将六视图 uv 转化为方向向量 */
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
 }
 
 /** 初始化位姿参数 */

package/ai_guides/glossary.md

@@ -58,6 +58,23 @@ Five 定义的五种浏览状态：
 ### G-Buffer / Geometry Buffer
 用于后处理的几何缓冲区，包含深度 (Depth)、法线 (Normal)、ID 等信息，用于实现高级特效（如轮廓线、SSAO）。
 
+### ViewLayer
+管理 `Model` 内部特定 3D 资源（如 Mesh、PointCloud、Gaussian Splatting）的图层。
+- 继承自 `Tile3D`。
+- 拥有独立的 `Parameter` 配置（覆盖上层配置）。
+- 支持可见性控制 (`visible`) 和优先级加载。
+
+### Gaussian Splatting (3DGS)
+一种基于点的 3D 渲染技术，通过各向异性高斯球（Splat）来表示场景。
+- 相比传统 Mesh，能更真实地还原复杂光照和细节。
+- Five 支持 `.spz` 和 `.splat` 格式的 3DGS 渲染。
+
+### 3D Tiles Refinement (细化)
+3D Tiles 加载过程中的状态概念：
+- **Loaded (已加载)**: 瓦片的基本数据已下载并解析，满足最低显示要求 (`minLevelOfDetail`)。
+- **Refined (已细化)**: 瓦片已加载最高质量数据，满足当前视角的屏幕空间误差要求 (`maxScreenSpaceError`)。
+- `five.model.refineProgress` 可用于监控当前视角的细化进度。
+
 ## Interaction (交互)
 
 ### Raycast (射线检测)

package/ai_guides/release_notes/6.8.md

@@ -0,0 +1,81 @@
+# Release Note 6.8.x
+> 6.8.x 版本发布日志
+
+```shell
+npm install @realsee/five@6.8
+```
+
+## Gaussian Splatting (3DGS) 支持
+> Five 现已支持 Gaussian Splatting (3DGS) 渲染管线。这是一种基于点的渲染技术，能够提供高质量的实时渲染效果。
+
+*   **前提条件**: 仅在 WebGL2 环境下可用。
+*   **数据支持**:
+    *   支持 `3dtiles` 中包含 3DGS 数据。
+    *   支持加载 `.spz` (version 2) 或 `.splat` 格式的数据。
+    *   支持通过 glTF 扩展加载 content 为 `.spz` 的 glTF/glb 文件。
+*   **功能特性**:
+    *   支持透视相机与正交相机渲染。
+    *   支持 BVH 构建，支持射线检测 (Raycast)。
+    *   `pbmGSObject` 继承自 `THREE.Points`。
+
+### 配置球谐光照阶数 (SH Degree)
+可以通过 `five.parameter.gsSHDegree` 设置球谐光照阶数，支持 0, 1, 2 阶，默认为 0 阶。
+
+```ts
+const five = new Five({
+    parameters: {
+        gsSHDegree: 1 // 设置为 1 阶 SH
+    }
+});
+```
+
+## ViewLayer 加载策略优化
+> 优化了 ViewLayer 的加载和显隐逻辑，以减少内存占用并提高性能。
+
+### 默认加载策略变更
+默认情况下，Five **不再加载所有图层**，而是根据优先级**仅加载一个**图层。
+优先级顺序：`mesh` > `point_cloud` > 其他类型。
+
+### 显隐与内存管理
+*   **显示**: 当 `viewLayer.visible = true` 时，开始加载资源。
+*   **隐藏**: 当 `viewLayer.visible = false` 时，**释放该图层占用的所有内存资源**。
+
+### 加载进度
+新增 `tile.content.loadProgress` 属性，用于查看每个瓦片的加载进度 (0-1)。
+新增 `tile.content.byteLength` 属性，可在加载过程中获取瓦片内容的字节长度。
+同时，`model.tileLoad` 和 `model.tileUnload` 事件被添加，用于监控瓦片的生命周期。
+
+### 下载进度回调
+外部模型加载函数（`loadGltf`, `loadPly` 等）现在支持 `onDownloadProgress` 回调，用于监控文件下载进度。
+
+### 射线检测增强
+*   `Intersection` 对象新增了 `tile`, `model`, `viewLayer` 字段，便于在射线检测时获取更详细的上下文信息。
+*   `raycaster.hitFilter` 回调函数的参数类型定义已更新，包含 `model`, `viewLayer`, `tile` 等上下文信息。
+
+## AI 友好文档 (AI Guides)
+> 全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。
+
+*   文档目录迁移至 `ai_guides/`，并在 `package.json` 中新增 `ai` 字段指向该目录。
+*   文档内容包含源码链接 (`source` 字段)，直接指向对应的 `.ts` 定义文件。
+*   提供了更清晰的 API 定义和概念说明，例如新增了 [ViewLayer](../features/view-layer.md) 的详细文档。
+
+## 新增后处理效果 (Post-Processing Passes)
+> 新增了三个可选的内置后处理 Pass，用于增强视觉效果。
+
+*   **[FlowingLight2DPass](../features/flowing-light-2d-pass.md)**: 2D 流光效果，通常用于在屏幕空间绘制流动的光线（如道路流光）。
+*   **[FlowingLight3DPass](../features/flowing-light-3d-pass.md)**: 3D 流光效果，基于深度缓冲区在三维模型表面绘制流光。
+*   **[GaussianBlurPass](../features/gaussian-blur-pass.md)**: 高斯模糊效果，可用于实现毛玻璃等视觉特效。
+
+## 其他优化
+*   **点云渲染**: 计算点位透明度时，现在会排除不活跃的点，提升渲染正确性。
+*   **TypeScript 支持**: 优化了 `.d.ts` 打包方式，声明文件现在与源码文件一一对应，提升了 IDE 的跳转体验。
+
+## glTF 支持**: 新增 `KHR_animation_pointer` 和 `KHR_node_visibility` 扩展支持
+*   `KHR_animation_pointer` 扩展 允许动画通道指向 glTF 资产中任何对象的任何属性，而不仅仅是节点的平移、旋转和缩放。
+*   `KHR_node_visibility` 扩展 允许设置节点的可见性属性。
+
+## work 提供 uv 转化函数。
+*   `vectorToEquirectangularUv` 方法将方向向量转化为全景图 uv。
+*   `equirectangularUvToVector` 方法将全景图 uv 转化为方向向量。
+*   `vectorToCubemapUv` 方法将方向向量转化为立方体贴图 uv。
+*   `cubemapUvToVector` 方法将立方体贴图 uv 转化为方向向量。

package/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "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"
+window.hierarchyData = "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"