@realsee/five-webgpu 1.0.0-alpha.1

package/ai_guides/features/multi-work.md

@@ -0,0 +1,146 @@
+# 多 Work (沙盘) 场景 (Multi-Work / Sandbox)
+
+- **Summary**: 在同一个 Five 实例中加载和管理多个 Work 数据（如沙盘场景），实现多楼盘/多户型的同屏展示与切换。
+- **Schema**: `Work[]`, `LooseWorkWithExtrinsics`, `FiveLoadOptions`.
+- **Concepts**: WorkCode, Works Collection, Coordinate Transform.
+- **Configuration**: `five.load()` 参数配置。
+- **Examples**: 加载多个 Work、动态添加 Work、Work 间切换。
+
+## Schema
+
+> **Definition**: [FiveLoadOptions](../../five/application/fiveLoadOptions.d.ts), [LooseWorkWithExtrinsics](../../five/work/looseWorkType.d.ts)
+
+### 核心类型定义
+
+```typescript
+// 输入数据类型
+type FiveLoadInput =
+  | Work[]
+  | LooseWorkWithExtrinsics[]
+  | string[]; // JSON Strings
+
+// 带位姿信息的 LooseWork (用于调整模型在场景中的位置)
+interface LooseWorkWithExtrinsics {
+  work: LooseWork;      // Work 数据内容
+  transform?: number[]; // 4x4 变换矩阵 (数组格式), 用于整体偏移/旋转该 Work
+  workCode?: string;    // 强制指定 WorkCode (覆盖数据中的默认值)
+}
+
+// 加载选项
+interface FiveLoadOptions {
+  mode?: "replace" | "add"; // 替换当前场景 vs 追加到当前场景
+  // ... 其他常规选项
+}
+```
+
+## Concepts
+
+### 1. Works Collection (数据集)
+当 Five 加载多个 Work 时，它们被存储在 `five.works` 集合中。
+- `five.works` 是一个增强的只读数组 (`ReadonlyArray<Work>`)。
+- 提供了 `getWork(workCode)` 和 `getObserver(panoId)` 等辅助方法。
+
+### 2. WorkCode (唯一标识)
+在多 Work 场景中，`workCode` 是区分不同 Work 的关键。
+- **必须唯一**: 加载的每个 Work 必须有唯一的 `workCode`。如果数据中重复，建议在加载时通过 `ParseOptions` 重写。
+- **状态索引**: `five.state` 和 `five.setState` 中需要通过 `workCode` 来指定目标 Work。
+
+### 3. Coordinate Alignment (坐标对齐)
+不同 Work 的原始模型可能位于其各自的坐标系原点。为了在沙盘中正确排列它们（避免重叠），需要使用 `transform` 矩阵对每个 Work 进行空间变换（平移、旋转）。
+
+## Configuration
+
+`five.load(input, state, options)` 是入口方法。
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `input` | `FiveLoadInput` | Work 数据数组。 |
+| `options.mode` | `"replace" \| "add"` | 默认为 `"replace"` (清空当前场景)。设为 `"add"` 可保留现有场景并追加新 Work。 |
+
+## Examples
+
+### 1. 基础加载 (Basic Loading)
+一次性加载两个 Work。
+
+```typescript
+const works = [workDataA, workDataB];
+
+five.load(works).then(() => {
+  console.log("所有 Work 加载完成");
+  console.log("当前 Works:", five.works);
+});
+```
+
+### 2. 沙盘排布 (Sandbox Layout)
+使用 `transform` 将两个户型并排摆放。
+
+```typescript
+import * as THREE from "three/webgpu";
+
+// 创建变换矩阵：向 X 轴正方向平移 20 米
+const matrixB = new THREE.Matrix4().makeTranslation(20, 0, 0);
+
+const input = [
+  // Work A: 保持在原点
+  { work: workDataA },
+  // Work B: 偏移位置
+  {
+    work: workDataB,
+    transform: matrixB.toArray()
+  }
+];
+
+five.load(input);
+```
+
+### 3. 动态添加 (Dynamic Add)
+在不销毁当前场景的情况下，追加一个新的 Work。
+
+```typescript
+// 假设当前已经加载了 Work A
+// 追加 Work C
+five.load(workDataC, undefined, {
+  mode: "add" // 关键参数
+}).then(() => {
+  console.log("Work C 已加入场景");
+});
+```
+
+### 4. Work 间切换 (Switching Works)
+跳转到指定 Work 的特定点位。
+
+```typescript
+const targetWorkCode = "work-id-b";
+
+// 方式一：指定点位索引
+five.setState({
+  workCode: targetWorkCode,
+  panoIndex: 0, // 目标 Work 的第 0 个点位
+  mode: "Panorama"
+});
+
+// 方式二：查找特定 Work
+const targetWork = five.works.getWork(targetWorkCode);
+if (targetWork) {
+  // 你的业务逻辑
+}
+```
+
+## Common Pitfalls
+
+1.  **WorkCode 冲突**: 如果加载的两个 Work 拥有相同的 `workCode`，SDK 行为可能不可预期。务必确保唯一性。
+    *   *解决*: 在构造 `LooseWorkWithExtrinsics` 时传入 `workCode` 字段强制覆盖。
+2.  **资源隔离**: 每个 Work 的纹理/模型请求是独立的。如果 Work A 和 Work B 引用了相同的 URL 资源，浏览器缓存会生效，但 SDK 内部逻辑仍视为独立资源。
+3.  **内存压力**: 同时加载多个大型模型会显著增加显存占用。建议根据设备性能限制同时加载的 Work 数量。
+4.  **坐标系混淆**: `transform` 仅影响 3D 模型的渲染位置。Work 内部的点位坐标 (`observer.position`) 也会自动应用此变换，但开发者在进行手动射线检测或计算时，需注意区分**原始坐标**和**世界坐标**。
+
+## Related
+
+*   [Five](./five.md): Five 核心类说明。
+*   [State](./state.md): 状态管理说明。
+*   [Work](./work.md): Work 数据结构详解。
+
+---
+```yaml
+tags: [multi-work, sandbox, works, load, transform]
+```

package/ai_guides/features/pano-filter.md

@@ -0,0 +1,144 @@
+# Pano Filter (全景图滤镜)
+
+- **Summary**: `PBMPanoFilter` 用于调整全景图的视觉效果，包括亮度、对比度、饱和度、色温、色调等。它作为参数传递给 `ModelScene`，可实时改变全景图的渲染表现。
+- **Schema**: `PBMPanoFilter`, `PBMUpdateable`
+- **Concepts**: Material Filter, Color Correction
+- **Configuration**: Temperature, Tint, Brightness, Contrast, Saturation
+- **Examples**: 滤镜开启与参数调整
+
+## Schema
+
+> **Definition**: [PBMPanoFilter](../../five/model/materials/pbmMaterial.d.ts)
+
+`PBMPanoFilter` 类定义了全景图的滤镜参数。所有属性均为对象引用，直接修改其内部属性即可生效。
+
+```typescript
+import { PBMUpdateable } from "@realsee/five";
+
+export class PBMPanoFilter extends PBMUpdateable {
+  /** 对比度控制 */
+  public readonly contrast: {
+    /** 对比度偏移 [-1, 1] (默认 0) */
+    contrastBias: number;
+  };
+
+  /** 饱和度控制 */
+  public readonly saturation: {
+    /** 饱和度偏移 [-1, 1] (默认 0) */
+    saturationBias: number;
+  };
+
+  /** 颜色控制 (色温与色调) */
+  public readonly color: {
+    /** 色温偏移 [-100, 100] (默认 0) */
+    temperatureBias: number;
+    /** 色调偏移 [-100, 100] (默认 0) */
+    tintBias: number
+  };
+
+  /** 高光与阴影控制 */
+  public readonly highlightShadow: {
+    /** 全局亮度偏移 [-255, 255] (默认 0) */
+    globalBias: number;
+    /** 高光偏移 [-255, 255] (默认 0) */
+    highlightBias: number;
+    /** 阴影偏移 [-255, 255] (默认 0) */
+    shadowBias: number;
+  };
+}
+```
+
+## Concepts
+
+### Parameter Binding (参数绑定)
+滤镜实例需要通过 `five.modelScene.parameter.set('panoFilter', filter)` 绑定到场景中才能生效。
+
+## Configuration
+
+以下参数均通过修改 `PBMPanoFilter` 实例的属性进行配置。
+
+### Color & Tone (色彩与色调)
+
+| Property | Type | Range | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `color.temperatureBias` | `number` | `[-100, 100]` | `0` | **色温**。正值偏暖 (黄)，负值偏冷 (蓝)。 |
+| `color.tintBias` | `number` | `[-100, 100]` | `0` | **色调**。正值偏洋红，负值偏绿。 |
+| `saturation.saturationBias` | `number` | `[-1, 1]` | `0` | **饱和度**。`0` 为原色，`-1` 为黑白。 |
+| `contrast.contrastBias` | `number` | `[-1, 1]` | `0` | **对比度**。正值增强对比，负值降低对比。 |
+
+### Light & Shadow (光影)
+
+| Property | Type | Range | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `highlightShadow.globalBias` | `number` | `[-255, 255]` | `0` | **亮度 (Brightness)**。整体提升或降低画面亮度。 |
+| `highlightShadow.highlightBias` | `number` | `[-255, 255]` | `0` | **高光 (Highlight)**。仅调整画面亮部的亮度。 |
+| `highlightShadow.shadowBias` | `number` | `[-255, 255]` | `0` | **阴影 (Shadow)**。仅调整画面暗部的亮度。 |
+
+## Examples
+
+### Basic Usage (基础用法)
+
+创建一个滤镜实例并应用到 Five 场景中。
+
+```typescript
+import { Five, PBMPanoFilter } from "@realsee/five";
+
+const five = new Five();
+// ... 初始化 five ...
+
+// 1. 创建滤镜实例
+const panoFilter = new PBMPanoFilter();
+
+// 2. 配置参数 (例如：增加一点暖色调和亮度)
+panoFilter.color.temperatureBias = 10; // 暖色
+panoFilter.highlightShadow.globalBias = 20; // 提亮
+
+// 3. 启用滤镜
+five.modelScene.parameter.set('panoFilter', panoFilter);
+
+// 4. (可选) 停用滤镜
+// five.modelScene.parameter.reset('panoFilter');
+```
+
+### Interactive Adjustment (动态调整)
+
+滤镜参数支持实时修改，适合制作调节面板。
+
+```typescript
+import { Five, PBMPanoFilter } from "@realsee/five";
+
+// 假设已经有 five 实例
+const panoFilter = new PBMPanoFilter();
+five.modelScene.parameter.set('panoFilter', panoFilter);
+
+// 模拟 UI 绑定的数据对象
+const filterSettings = {
+  brightness: 0,
+  contrast: 0,
+};
+
+// 监听 UI 变化 (示例伪代码)
+function onBrightnessChange(value: number) {
+  // value range: [-255, 255]
+  panoFilter.highlightShadow.globalBias = value;
+  // 如果 five 没有开启自动渲染 (play: false)，需要手动触发重绘
+  five.needsRender = true;
+}
+
+function onContrastChange(value: number) {
+  // value range: [-1, 1]
+  panoFilter.contrast.contrastBias = value;
+  five.needsRender = true;
+}
+```
+
+## Related
+
+*   [Model](./model.md): 了解 ModelScene 及其参数系统。
+*   [Parameter](./parameter.md): 了解 Five 的全局初始化参数。
+
+---
+
+```yaml
+tags: [filter, material, visual, color, brightness, contrast]
+```

package/ai_guides/features/pano-tile.md

@@ -0,0 +1,132 @@
+# Panorama Tile
+
+- **Summary**: 全景模式下的瓦片加载策略，支持多分辨率层级（LOD）和视锥体裁剪，以优化全景浏览的性能和清晰度。
+- **Schema**: WorkTile 接口及相关配置参数。
+- **Concepts**: LOD (Level of Detail), Frustum Culling, Tile URL Generation.
+- **Configuration**: tileLevelForFov, tileMaxRequest, imageOptions.
+- **Examples**: 瓦片数据结构查看与 Five 初始化配置。
+
+## Schema
+
+> **Definition**: [WorkImage](../../five/work/work.d.ts), [ImageOptions](../../five/types/imageOptions.d.ts)
+
+### WorkObserver.images
+点位全景图数据结构，包含瓦片列表。
+
+```typescript
+interface WorkImage {
+  /** 分辨率列表 */
+  sizeList: readonly number[];
+  /** 瓦片信息列表，按 level 排序 */
+  tiles: readonly WorkTile[];
+  // ... 其他基础图片 URL
+}
+```
+
+### ImageOptions
+全景图及瓦片的图片处理配置。
+
+```typescript
+interface ImageOptions {
+  /** 图片尺寸参数 (例如 512, 1024...) */
+  size?: number;
+  /** 图片质量参数 (0-100) */
+  quality?: number;
+  /** 图片格式参数 */
+  format?: "jpg" | "jpeg" | "png" | "heif" | "heic" | "webp" | "avif";
+  /** URL 转换函数 */
+  transform?: (url: string, options: ImageURLOptions) => string;
+}
+```
+
+## Concepts
+
+### Tile Parsing (瓦片解析)
+在 `Five` 加载 `Work` 数据时，`WorkParser` 会解析 `panorama.size_list` (或 `panorama.tiles`) 字段。
+- **Level 计算**: `level = log2(size / 512)`。
+- **URL 生成**:
+  - 如果 `size > baseSize` (通常是初始全景图大小)，URL 中的 `/cube_{size}/` 部分会被动态替换（通过 `replaceImageSize` 函数）。
+  - 如果 `size <= baseSize`，直接使用基础全景图 URL，并设置 `scale`。
+- **排序**: 解析后的 `tiles` 数组会按 `level` 升序排列。
+
+### sizeList
+- **类型**: `readonly number[]`
+- **说明**: 包含所有可用的分辨率（以像素为单位）。
+- **示例**: `[2048, 6144]` 表示该点位全景图有两个层级，分别是 2048px 和 6144px。
+- **图片路径**: 每个层级的图片路径都是 `cube_{size}`，`{size}` 是层级分辨率，必须与 `sizeList` 中的值对应。并必须存在 2048px 层级的图片。
+
+### Level of Detail (LOD) & Loading Strategy
+`PanoramaController` 使用 `Tiling` 类来管理瓦片加载：
+- **LOD 选择**: 根据当前的视场角 (`FOV`) 和视图大小 (`viewSize`)，计算所需的最佳瓦片层级。默认策略会优先保证画面清晰度，同时考虑网络开销。
+- **视锥体裁剪 (Frustum Culling)**: 仅加载当前相机视锥体可见范围内的瓦片面。
+- **并发控制**: 通过 `tileMaxRequest` 限制同时进行的网络请求数量，避免阻塞。
+
+## Configuration
+
+在初始化 `Five` 时，可以通过 `panorama` 配置参数来配置瓦片加载行为。
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `tileLevelForFov` | `(fov: number, viewSize: Vector2) => number` \| `false` | `undefined` | 自定义函数，用于根据当前 FOV 和视图尺寸决定加载哪个层级的瓦片。返回 `level` 数值。如果设置为 `false`，则禁用动态瓦片加载。默认使用内部策略。 |
+| `tileMaxRequest` | `number` | `3` | 最大的瓦片图片并发请求数。增加此值可能加快加载速度，但也可能导致网络拥塞。 |
+| `imageOptions` | `ImageOptions` | `undefined` | 全景图及瓦片的图片处理配置。可用于全局控制图片的加载格式（如强制使用 WebP）、质量压缩比例或通过 `transform` 函数自定义图片 URL。 |
+
+## Examples
+
+### 查看瓦片数据结构
+
+```typescript
+import { Five } from "@realsee/five";
+
+const five = new Five();
+
+five.on("loaded", () => {
+  const observer = five.work.observers[0];
+  if (observer && observer.images && observer.images.tiles) {
+    console.log("Available Tiles:", observer.images.tiles);
+    observer.images.tiles.forEach(tile => {
+      console.log(`Level: ${tile.level}, Size: ${tile.size}, Scale: ${tile.scale}`);
+    });
+  }
+});
+```
+
+### 配置瓦片加载策略与图片参数
+
+```typescript
+import { Five } from "@realsee/five";
+
+const five = new Five({
+  // 自定义瓦片层级选择策略
+  tileLevelForFov: (fov, viewSize) => {
+    // 简单示例：FOV 小于 60 度时强制使用 Level 2，否则使用 Level 1
+    if (fov < 60) {
+      return 2;
+    }
+    return 1;
+  },
+  // 限制并发请求数
+  tileMaxRequest: 6,
+  // 图片加载配置
+  imageOptions: {
+    // 强制请求 WebP 格式的图片
+    format: "webp",
+    // 图片质量设置为 80%
+    quality: 80,
+    // (可选) 自定义 URL 转换逻辑
+    // transform: (url, options) => {
+    //   return url + `?x-oss-process=image/format,webp/quality,q_80`;
+    // }
+  }
+});
+```
+
+## Related
+- [Mode](./mode.md): 了解不同模态下 Work 数据的表现。
+- [ImageOptions](./image-options.md): 了解图片加载配置选项。
+
+---
+
+```yaml
+tags: [pano-tile, observer]
+```

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