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

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 点映射到屏幕空间,从而实现"随相机变化"的动态光带效果。
 
-### 循环流动 (Looping Flow)
-默认使用循环模式（`LOOP = true`），光头在路径上循环流动，无起点/终点的区分。尾部长度为路径总长的 1/4。
+### 头尾追逐动画 (Head-Tail Chase Animation)
+流光效果采用"头尾追逐"模式:
+- **头部(Head)**: 光流的前端,沿路径循环移动
+- **尾部(Tail)**: 光流的后端,跟随头部移动
+- **渐变**: 从尾部(透明度 0)到头部(透明度 1)线性渐变
+- **尾长**: 尾部长度由 `tailLengthRatio` 参数控制(默认 0.2,即路径总长的 20%)
+
+光头在路径上循环流动,通过 `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
+
 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);
@@ -136,11 +215,11 @@ function animate() {
   five.render();
 }
 animate();
-```
+
 
 ### 多条 3D 路径
 
-```ts
+
 const pass = new FlowingLight3DPass(camera);
 
 const paths = [
@@ -152,6 +231,7 @@ const paths = [
     totalLength: 11,
     color: new THREE.Color(0xff0000),
     duration: 2000,
+    lineWidth: 3.0,
   },
   {
     points: [
@@ -161,6 +241,8 @@ const paths = [
     totalLength: 12,
     color: new THREE.Color(0x00ff00),
     duration: 2500,
+    delay: 500,
+    lineWidth: 4.0,
   },
   {
     points: [
@@ -170,15 +252,17 @@ const paths = [
     totalLength: 11,
     color: new THREE.Color(0x0000ff),
     duration: 2200,
+    delay: 1000,
+    lineWidth: 2.5,
   },
 ];
 
 pass.setLines(paths);
-```
+
 
 ### 计算 3D 路径长度
 
-```ts
+
 function calculatePath3DLength(points: THREE.Vector3[]): number {
   let length = 0;
   for (let i = 1; i < points.length; i++) {
@@ -187,25 +271,37 @@ 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
+
 // 光带路径随相机移动自动投影
 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,
 }]);
 
 // 相机动画过程中光带自动跟随投影
@@ -213,20 +309,105 @@ 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` 以改变流速。
+- **光带不可见**: 检查路径点是否在相机视锥内;验证 `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 +416,5 @@ five.setState({
 
 ---
 
-```yaml
-tags: [postprocessing, effect, flowing, light, pass, rendering, worldspace, projection]
-```
+
+tags: [postprocessing, effect, flowing, light, pass, rendering, worldspace, projection, instanced, performance]

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

@@ -71,10 +71,13 @@ Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
 *   `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`
-*   `PBM_mesh`
 *   `KHR_gaussian_splatting_compression_spz`
 
 | 参数 | 类型 | 默认值 | 说明 |

package/ai_guides/features/pano-uv.md

@@ -0,0 +1,131 @@
+# 全景图 UV 与方向转换 (Panorama UV Conversion)
+
+- **Summary**: 提供了一组工具方法，用于在**全景图 UV 坐标** (Equirectangular UV / Cubemap UV) 与**三维空间方向向量** (Vector3) 之间进行转换。
+- **Schema**: 依赖 `WorkObserver` 实例，提供四个核心转换方法。
+- **Concepts**: Equirectangular Projection, Cubemap Projection, UV Origin, Coordinate Systems.
+- **Configuration**: `uvOrigin` (UV 原点设置).
+- **Examples**: 向量转全景 UV、UV 转向量、Cubemap 转换。
+
+## Schema
+
+> **Definition**: [WorkObserver](../../five/work/work.d.ts)
+
+这些方法挂载在 `WorkObserver` 实例上，依赖当前观察点 (Observer) 的位姿信息 (Position & Quaternion) 以及 `work.transform` 进行计算。
+
+```typescript
+interface WorkObserver {
+  /**
+   * 将方向向量转化为全景图 uv
+   * @param vector - 全局方向向量 (World Space)
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+
+  /**
+   * 将全景图 uv 转化为方向向量
+   * @param uv - 全景图 UV 坐标 [0, 1]
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+
+  /**
+   * 将方向向量转化为六视图 uv
+   * @param vector - 全局方向向量 (World Space)
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];
+
+  /**
+   * 将六视图 uv 转化为方向向量
+   * @param cubeFace - 立方体面 ('up' | 'down' | 'left' | 'right' | 'front' | 'back')
+   * @param uv - 该面上的 UV 坐标 [0, 1]
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+}
+
+type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
+```
+
+## Concepts
+
+### 1. 坐标系转换 (Coordinate Transformation)
+转换过程会自动处理以下坐标空间的变换：
+1.  **World Space (世界坐标系)**: `vector` 参数所处的坐标系。
+2.  **Work Space (Work 坐标系)**: 考虑 `work.transform` 带来的整体旋转。
+3.  **Observer Space (观察者坐标系)**: 考虑 `observer.quaternion` 带来的观察点旋转。
+4.  **Panorama Space (全景图空间)**: 最终映射到 2D 图片上的 UV 坐标。
+
+### 2. 投影方式 (Projection Types)
+*   **Equirectangular (等距柱状投影)**: 将球体展开为 2:1 的矩形图片。常用于全景图预览。
+*   **Cubemap (立方体贴图)**: 将球体投影到立方体的六个面上。常用于高清全景浏览。
+
+### 3. UV 原点 (UV Origin)
+*   **top-left (默认)**: 原点 `(0, 0)` 在图片**左上角**。U 轴向右，V 轴向下。符合大多数 Web 图片处理习惯 (Canvas, DOM)。
+*   **bottom-left**: 原点 `(0, 0)` 在图片**左下角**。U 轴向右，V 轴向上。符合 WebGL / OpenGL 纹理坐标习惯。
+
+## Configuration
+
+所有方法均包含可选参数 `uvOrigin`。
+
+### Common Configuration
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `uvOrigin` | `'top-left' \| 'bottom-left'` | `'top-left'` | 指定 UV 坐标系的原点位置。 |
+
+## Examples
+
+### 1. 点击全景图获取空间方向 (Click to Vector)
+假设你有一个全景图的点击事件，获取到了点击位置的 UV：
+
+```typescript
+const observer = five.work.observers[0];
+// 假设这是用户点击全景图后归一化得到的 UV (0~1)
+const clickUv = new THREE.Vector2(0.5, 0.5);
+
+// 转换为世界空间的方向向量
+const direction = observer.equirectangularUvToVector(clickUv);
+
+console.log('点击方向:', direction);
+```
+
+### 2. 将空间点映射到全景图上 (World Point to UV)
+假设场景中有一个 3D 物体，你想知道它在当前全景图上的位置（例如打标签）：
+
+```typescript
+const observer = five.work.observers[0];
+const objectPosition = new THREE.Vector3(10, 2, 5);
+
+// 计算物体相对于观察点的方向向量
+const direction = objectPosition.clone().sub(observer.position).normalize();
+
+// 获取全景图 UV
+const uv = observer.vectorToEquirectangularUv(direction);
+
+console.log(`物体在全景图上的位置: u=${uv.x}, v=${uv.y}`);
+```
+
+### 3. 处理 Cubemap 坐标 (Cubemap Conversion)
+如果你使用的是六面体全景图资源：
+
+```typescript
+const observer = five.work.observers[0];
+const direction = new THREE.Vector3(0, 0, -1); // 正前方
+
+// 获取对应的面和 UV
+const [face, uv] = observer.vectorToCubemapUv(direction);
+
+console.log(`正前方对应 Cubemap 的 ${face} 面，UV 为`, uv);
+```
+
+## Related
+
+*   [Work](./work.md): 了解 WorkObserver 的数据结构。
+*   [Coordinate System](./coordinate-system.md): 了解 Five 的坐标系定义。
+
+---
+
+```yaml
+tags: [work, observer, uv, projection, math]
+```

package/ai_guides/release_notes/6.8.md

@@ -52,12 +52,24 @@ const five = new Five({
 *   `Intersection` 对象新增了 `tile`, `model`, `viewLayer` 字段，便于在射线检测时获取更详细的上下文信息。
 *   `raycaster.hitFilter` 回调函数的参数类型定义已更新，包含 `model`, `viewLayer`, `tile` 等上下文信息。
 
-## AI 友好文档 (AI Guides)
-> 全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。
+## glTF 模型支持增强
+> 新增了对更多 glTF 扩展的支持，提升了模型的表现力和动画能力。
 
-*   文档目录迁移至 `ai_guides/`，并在 `package.json` 中新增 `ai` 字段指向该目录。
-*   文档内容包含源码链接 (`source` 字段)，直接指向对应的 `.ts` 定义文件。
-*   提供了更清晰的 API 定义和概念说明，例如新增了 [ViewLayer](../features/view-layer.md) 的详细文档。
+### 新增扩展支持
+*   **KHR_animation_pointer**: 允许动画通道指向 glTF 资产中任何对象的任何属性，而不仅仅是节点的平移、旋转和缩放。
+*   **KHR_node_visibility**: 允许设置节点的可见性属性。
+*   **KHR_materials_clearcoat** 用于在材质上添加一层透明涂层，模拟车漆、碳纤维、清漆木材等真实世界中的表面效果。
+*   **KHR_materials_sheen** 绒面 / 绒毛类表面效果。
+*   **KHR_materials_transmission** 物理透光材质扩展，用于实现光线真正穿过物体的透明 / 半透明效果。
+
+## Work 核心能力增强
+> 为 WorkObserver 提供了更多实用的工具函数，便于进行坐标和 UV 转换。
+
+### UV 转换工具函数
+*   `vectorToEquirectangularUv`: 将方向向量转化为全景图 uv。
+*   `equirectangularUvToVector`: 将全景图 uv 转化为方向向量。
+*   `vectorToCubemapUv`: 将方向向量转化为立方体贴图 uv。
+*   `cubemapUvToVector`: 将立方体贴图 uv 转化为方向向量。
 
 ## 新增后处理效果 (Post-Processing Passes)
 > 新增了三个可选的内置后处理 Pass，用于增强视觉效果。
@@ -66,16 +78,13 @@ const five = new Five({
 *   **[FlowingLight3DPass](../features/flowing-light-3d-pass.md)**: 3D 流光效果，基于深度缓冲区在三维模型表面绘制流光。
 *   **[GaussianBlurPass](../features/gaussian-blur-pass.md)**: 高斯模糊效果，可用于实现毛玻璃等视觉特效。
 
+## AI 友好文档 (AI Guides)
+> 全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。
+
+*   文档目录迁移至 `ai_guides/`，并在 `package.json` 中新增 `ai` 字段指向该目录。
+*   文档内容包含源码链接 (`source` 字段)，直接指向对应的 `.ts` 定义文件。
+*   提供了更清晰的 API 定义和概念说明，例如新增了 [ViewLayer](../features/view-layer.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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"