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

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";
+
+// 创建变换矩阵：向 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-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]
+```

package/ai_guides/features/parameter.md

@@ -0,0 +1,153 @@
+# Parameter (配置系统)
+
+- **Summary**: Five 用于控制三维模型渲染表现的核心配置系统，采用树形继承设计。
+- **Schema**: 是所有配置项的容器，通过继承机制管理 Material 和 3DTile 等子配置。
+- **Concepts**: Hierarchy (树形继承), Override (覆盖), Resolution (解析)。
+- **Examples**: 全局配置、局部覆盖、参数重置。
+
+## Schema
+
+> **Definition**: [Parameter](../../five/model/parameter.d.ts)
+
+`Parameter` 类是配置的入口。它并不直接包含所有配置字段的定义，而是将它们组织在不同的接口中。
+
+### Parameter Categories (参数分类)
+
+为了便于理解，我们将参数分为两大类：
+
+| Category | Description | Link |
+| :--- | :--- | :--- |
+| **Material & Appearance** | 控制“长什么样”。包括材质、颜色、楼层显示、阴影、点云样式等。 | [Material Params](./material.md) |
+| **3DTile & Performance** | 控制“怎么加载”。包括 LOD (细节层级)、显存配额、网络并发、SSE 阈值等。 | [3DTile Params](./3dtile.md) |
+
+### Parameter Class API
+
+#### 1. Getting Values (获取值)
+
+获取参数值**不使用** `get()` 方法，而是直接访问属性。
+
+*   **Direct Access (直接访问)**: 获取当前 `Parameter` 实例上设置的值。如果未设置，返回 `undefined`。
+*   **Resolve Value (计算最终值)**: 获取经过树形继承计算后的最终生效值。
+    *   如果不传参，则基于默认值计算 (Default -> Current)。
+    *   如果传入上游 Parameter，则基于默认值 + 上游 Parameter 计算 (Default -> Upstream -> Current)。
+
+```typescript
+// 方式 A: 直接访问 (获取当前层级配置)
+const currentVal = parameter.maxMemoryUsage;
+
+// 方式 B: 计算最终值 (包含继承逻辑)
+
+// 1. 基础用法：仅继承默认值
+const finalVal = parameter.resolveValue().maxMemoryUsage;
+
+// 2. 进阶用法：指定继承源 (例如 ViewLayer 继承自 Model)
+const inheritedVal = viewLayerParam.resolveValue(parentParameter).maxMemoryUsage;
+```
+
+#### 2. Methods (方法)
+
+`Parameter` 实例提供了以下核心方法来管理配置：
+
+```typescript
+class Parameter {
+  /**
+   * 设置配置项
+   * @param key 参数名 (如 'opacity', 'maxMemoryUsage')
+   * @param value 参数值
+   */
+  set(key: string, value: any): void;
+
+  /**
+   * 重置配置项（移除当前层级的设置，恢复继承上游的值）
+   * @param keys 要重置的参数名列表
+   */
+  reset(...keys: string[]): void;
+
+  /**
+   * 获取经过继承计算后的最终值
+   * @param upstream 上游 Parameter 对象列表（通常由引擎自动传入）
+   */
+  resolveValue(...upstream: Parameter[]): ResolvedParameterValue;
+}
+```
+
+## Concepts
+
+### 树形继承关系 (Hierarchy)
+
+Parameter 遵循 **“就近原则” (Override)** 的继承逻辑。
+
+1.  **ViewLayer Parameter**: 最具体，优先级最高。通常对应一个具体的 `.gltf` 文件或数据块。
+2.  **Model Parameter**: 覆盖该 Model 下的所有 ViewLayer。一个 Model 可能包含多个 ViewLayer (如 Mesh 层和 PointCloud 层)。
+3.  **ModelScene Parameter**: 全局默认值，优先级最低。影响整个场景。
+
+```mermaid
+graph TD
+  Scene[ModelScene.parameter] -->|Inherit| Model[Model.parameter]
+  Model -->|Inherit| Layer1[ViewLayer.parameter]
+  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)
+
+```typescript
+// 1. 设置全局最大显存 (影响所有模型)
+five.modelScene.parameter.set('maxMemoryUsage', 512);
+
+// 2. 设置全局半透明
+five.modelScene.parameter.set('opacity', 0.5);
+```
+
+### 2. 局部覆盖 (Override)
+
+```typescript
+// 场景中大部分模型不产生阴影
+five.modelScene.parameter.set('castShadow', false);
+
+// 但让特定的“主角”模型产生阴影
+const heroModel = five.models[0];
+heroModel.parameter.set('castShadow', true);
+```
+
+### 3. 重置配置 (Reset)
+
+```typescript
+// 假设之前设置了 opacity
+five.modelScene.parameter.set('opacity', 0.5);
+
+// ... 一段时间后 ...
+
+// 移除该设置，恢复默认值 (或继承值)
+five.modelScene.parameter.reset('opacity');
+```
+
+### 4. 获取配置 (Get Value)
+
+```typescript
+// 获取当前对象上的配置（如果未设置，则为 undefined）
+const ownOpacity = five.modelScene.parameter.opacity;
+
+// 获取最终生效的配置（计算继承链后的值）
+const finalOpacity = five.modelScene.parameter.resolveValue().opacity;
+```
+
+## Related
+
+*   [Material Parameters](./material.md): 材质与外观参数详情。
+*   [3DTile Parameters](./3dtile.md): 性能与加载参数详情。
+*   [Model](./model.md): Parameter 的宿主。
+
+---
+
+```yaml
+tags: [parameter, config, hierarchy, api]
+```