@realsee/five-webgpu 1.0.0-alpha.1

package/ai_guides/features/state.md

@@ -0,0 +1,101 @@
+# State (状态)
+
+- **Summary**: State 是 Five 的核心状态对象，描述了当前的显示模式、观察点位以及相机的空间姿态。
+- **Schema**: 包含 Pose (相机姿态) 和 Mode (模式) 等属性的接口。
+- **Concepts**: Camera Pose, Coordinate System, Mode Specifics。
+- **Examples**: 状态获取与更新。
+
+## Schema
+
+> **Definition**: [State](../../five/types/state.d.ts)
+
+**State** 类型定义如下（继承自 `Pose`）：
+
+```ts
+import * as THREE from "three/webgpu";
+import { Mode } from "@realsee/five";
+
+interface Pose {
+  /** 相机偏航角 (水平方向)，单位：弧度 */
+  longitude: number;
+  /** 相机俯仰角 (垂直方向)，单位：弧度 */
+  latitude: number;
+  /** 相机垂直视场角，单位：度 */
+  fov: number;
+  /** 相机看向的目标中心点坐标 */
+  offset: THREE.Vector3;
+  /** 相机距离目标中心点的距离 */
+  distance: number;
+}
+
+interface State extends Pose {
+  /** 显示模式 */
+  mode: Mode;
+  /** 当前点位的唯一标识 (workCode) */
+  workCode: string;
+  /** 当前点位在列表中的索引 */
+  panoIndex: number;
+}
+```
+
+## Concepts
+
+*   **Camera Pose (相机姿态)**: Five 使用球坐标系 (Spherical) + 笛卡尔偏移 (Cartesian Offset) 来描述相机位置。
+    *   相机始终位于以 `offset` 为中心、`distance` 为半径的球面上。
+    *   **longitude**: 球面上的经度（水平旋转）。
+    *   **latitude**: 球面上的纬度（垂直旋转）。
+    *   **offset**: 相机“看向”的点，也是球心。
+    *   **distance**: 相机到 `offset` 的距离。
+*   **Coordinate System (坐标系)**:
+    *   采用 Y-Up 右手坐标系（与 Three.js 默认一致）。
+    *   单位长度为米。
+*   **Mode Specifics (模式特性)**:
+    *   **Panorama**: `distance` 通常为 0，即相机位置与 `offset` 重合（第一人称视角）。
+    *   **Floorplan/Mapview**: `offset` 通常位于模型中心，`distance` 大于模型包围盒半径（第三人称上帝视角）。
+*   **State vs CurrentState**:
+    *   **five.state**: **目标状态**。表示相机最终应该到达的状态。当调用 `setState` 或用户交互结束时，此值即为最终结果。通常用于 UI 同步（如高亮当前模式按钮）。
+    *   **five.getCurrentState()**: **瞬时状态**。表示当前渲染帧相机的实际状态。在动画过渡过程中，`currentState` 会不断变化直至追赶上 `state`。通常用于需要实时反馈的场景（如罗盘旋转）。
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+使用 `setState` 更新状态：
+
+```ts
+// 切换到户型图模式，并旋转相机到 45 度
+five.setState({
+  mode: 'Floorplan',
+  longitude: Math.PI / 4
+});
+```
+
+### 详细示例 (Detailed Example)
+
+获取当前状态并基于此修改：
+
+```ts
+const state = five.state;
+
+// 在当前状态基础上，向右旋转 90 度，并略微拉远距离
+five.setState({
+  longitude: tate.longitude + Math.PI / 2,
+  distance: tate.distance + 2.0
+});
+```
+
+## Common Pitfalls
+
+1.  **单位混淆**: `longitude` 和 `latitude` 使用**弧度**，而 `fov` 使用**角度**（度）。
+2.  **Offset 类型**: `offset` 必须是 `THREE.Vector3` 实例。如果在 React 等框架中使用纯对象（Plain Object），Five 内部会自动转换，但在 TypeScript 中需注意类型匹配。
+3.  **异步更新**: `setState` 触发的相机运动是异步动画过程。如果需要立即无动画跳转，可传递第二个参数 `immediately: true`。
+
+## Related
+
+*   [Mode - 模式](./mode.md): 详细了解各种 Mode 的区别。
+
+---
+
+```yaml
+tags: [camera, state, pose, interaction]
+```

package/ai_guides/features/ultra-hdr.md

@@ -0,0 +1,204 @@
+# UltraHDR / GainMap 渲染
+
+本篇说明 five-webgpu 如何用 UltraHDR（GainMap）方案还原全景图的高动态范围，重点是**最终 RGB 是如何算出来的**。
+
+## 基本原理
+
+UltraHDR 不直接存 HDR 像素，而是拆成两部分：
+
+- **SDR 底图（base / color）**：普通的 8bit 全景图，直接可显示。
+- **GainMap（增益图）**：每个像素存一个 `[0,1]` 的增益值，表示该像素相对 SDR 需要放大多少亮度。
+
+渲染时的公式是：
+
+```
+finalRGB = sdrRGB * boost(gain)
+```
+
+`boost` 是由 GainMap 值加上一组元数据（HDR config）算出的每通道增益系数。当没有 HDR（增益全为 1 / 未启用）时 `boost = 1`，退化为普通 SDR。
+
+## 相关数据结构
+
+GainMap 元数据来自每个点位的 `hdrConfig`（`HDRCfgData`）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `maxContentBoost` | 内容侧最大亮度增益（gain=1 时对应的放大倍数） |
+| `minContentBoost` | 内容侧最小亮度增益（gain=0 时对应，通常为 1） |
+| `hdrCapacityMin` | 显示器 HDR 容量下限（通常为 1） |
+| `hdrCapacityMax` | 显示器 HDR 容量上限 |
+| `gamma` | GainMap 的编码 gamma（解码用 `1/gamma`） |
+| `offsetSdr` | SDR 偏移，默认 0（Adobe 规范默认 `1/64`） |
+| `offsetHdr` | HDR 偏移，默认 0（Adobe 规范默认 `1/64`） |
+
+另外还有一个运行时可调参数：
+
+- `maxDisplayBoost`：当前显示器 / 场景允许的最大显示增益，决定实际能还原多少 HDR。可通过 `five.modelScene.parameter.set('maxDisplayBoost', value)` 实时调整。
+
+## 最终 RGB 的计算步骤
+
+对应实现见 `PanoSourceNode.computeHDRBoost`（以及瓦片路径下等价的 `tiling.ts#computeHDRBoostNode`）。
+
+### 1. 计算显示权重 weight
+
+根据显示器容量把 `maxDisplayBoost` 归一化到 `[0,1]`：
+
+```
+weight = clamp(
+  (log2(maxDisplayBoost) - log2(hdrCapacityMin)) /
+  (log2(hdrCapacityMax) - log2(hdrCapacityMin)),
+  0, 1
+)
+```
+
+- `weight = 0`：显示器不支持超出 SDR 的亮度 → 完全不增益。
+- `weight = 1`：显示器能力达到内容上限 → 全量增益。
+- 中间值：按比例插值。
+
+> 瓦片路径（`computeHDRBoostNode`）对分母做了保护：`max(denom, 1e-6)` 并乘以 `step(1e-6, denom)`，避免非 HDR（capacity 全为 1）时除零产生 NaN。
+
+### 2. GainMap 解码（gamma）
+
+GainMap 采样值经 gamma 还原为线性增益量（每通道独立），解码使用 gamma 的倒数：
+
+```
+gainLinear = pow(gainRGB, 1/gamma)   // 对 r/g/b 分别做 pow，与 Adobe 规范一致
+```
+
+### 3. 在 log 域插值出增益
+
+用 `min/maxContentBoost` 在 log2 空间对 `gainLinear` 做线性插值，得到该像素的对数增益：
+
+```
+logGain = log2(minContentBoost)
+        + gainLinear * (log2(maxContentBoost) - log2(minContentBoost))
+```
+
+### 4. 应用显示权重并还原到线性倍数
+
+用第 1 步的 `weight` 缩放对数增益，再指数还原为倍数：
+
+```
+boost = exp2(logGain * weight)     // 每通道
+```
+
+### 5. 得到最终颜色
+
+应用 GainMap 偏移得到最终 HDR 颜色（`offset` 为 0 时退化为 `sdr * boost`）：
+
+```
+finalRGB = (sdrRGB + offsetSdr) * boost - offsetHdr
+finalA   = sdrA
+```
+
+在瓦片材质（`TileMaterial`）里，还用 `enabled` 开关做了混合，未启用时退化为 SDR：
+
+```
+hdrRgb = mix(texColor.rgb, texColor.rgb * boost, enabled)
+```
+
+## 完整公式汇总
+
+```
+weight   = clamp( (log2(maxDisplayBoost) - log2(hdrCapacityMin))
+                  / (log2(hdrCapacityMax) - log2(hdrCapacityMin)), 0, 1 )
+
+gainLin  = pow(gainRGB, 1/gamma)
+
+logGain  = log2(minContentBoost)
+         + gainLin * (log2(maxContentBoost) - log2(minContentBoost))
+
+boost    = exp2(logGain * weight)
+
+finalRGB = (sdrRGB + offsetSdr) * boost - offsetHdr
+```
+
+## 官方参考公式
+
+以下公式来自两个权威开源实现，可作为校验基准。内容已改写以符合许可要求。
+
+### 1) Google `libultrahdr`（C++，`gainmapmath.cpp`）
+
+解码端 `applyGain`（带 displayBoost 的重载）核心逻辑：
+
+```cpp
+logBoost   = log2(minContentBoost) * (1 - gain) + log2(maxContentBoost) * gain;
+gainFactor = exp2(logBoost * displayBoost / maxContentBoost);
+finalRGB   = sdr * gainFactor;
+```
+
+说明：
+- `gain` 是 GainMap 采样值（`[0,1]`）。该库固定 `gamma = 1.0`、`offsetSdr = offsetHdr = 0`、`hdrCapacityMin = 1`、`hdrCapacityMax = maxContentBoost`，所以权重简化成 `displayBoost / maxContentBoost`。
+- 元数据里的 `minContentBoost` / `maxContentBoost` 是**线性倍数**（非 log），在着色器里才取 `log2`。
+- 来源：[ittiam-systems/libultrahdr](https://github.com/ittiam-systems/libultrahdr) / [AOSP libultrahdr](https://android.googlesource.com/platform/external/libultrahdr)。内容为改写。
+
+### 2) MONOGRID `gainmap-js` v3.4.0（Adobe GainMap 规范的 three.js 移植）
+
+解码 fragment shader 原式（等价重排）：
+
+```glsl
+logRecovery = pow(recovery, gamma);        // gamma uniform = 1.0 / metadataGamma
+logBoost    = gainMapMin * (1 - logRecovery) + gainMapMax * logRecovery;
+hdrColor    = (sdr + offsetSdr) * exp2(logBoost * weightFactor) - offsetHdr;
+
+weightFactor = clamp(
+  (log2(maxDisplayBoost) - hdrCapacityMin) / (hdrCapacityMax - hdrCapacityMin),
+  0, 1
+);
+```
+
+说明（这是最贴近 Adobe 官方规范的实现）：
+- `gainMapMin` / `gainMapMax` 就是 `log2(minContentBoost)` / `log2(maxContentBoost)`，**元数据里已经是 log2 空间**，所以 shader 里不再取 log。
+- 同理 `hdrCapacityMin` / `hdrCapacityMax` **也是 log2 空间**的值，所以 `weightFactor` 里直接用、不再套 `log2`。
+- `gamma` uniform 传入的是 `1/metadataGamma`（解码用倒数）。
+- 带 `offsetSdr` / `offsetHdr` 偏移（Adobe 默认 `1/64`）。
+- 来源：[MONOGRID/gainmap-js](https://github.com/MONOGRID/gainmap-js)。内容为改写。
+
+## 本项目公式 vs 官方公式（差异核对）
+
+结论：本项目 `computeHDRBoost` 的**结构是正确的**——它等价于 libultrahdr 的 log 域插值，加上 Adobe 规范的通用 `weight` 公式。以下三处约定/取舍需要留意：
+
+1. **元数据空间约定（最关键，仍需确认）**
+   - 本项目对 `minContentBoost / maxContentBoost / hdrCapacityMin / hdrCapacityMax` 在 shader 内部统一取 `log2`，说明这些字段在数据里是**线性倍数**（如 `maxContentBoost = 100`、`hdrCapacityMax = 1000`）。这与 **libultrahdr 约定一致**。
+   - 但 **Adobe / gainmap-js 约定相反**：这些字段在元数据里就已经是 **log2 空间**。
+   - 风险：如果 GainMap 资源是按 Adobe/UltraHDR 标准（XMP `hdrgm`）导出的，那里的 `HDRCapacityMin/Max`、`GainMapMin/Max` 已经是 log2 值，本项目再套一次 `log2` 就会**二次取对数**导致结果错误。务必确认打包侧写入的到底是线性倍数还是 log2 值。
+
+2. **gamma 方向（✅ 已修复）**
+   - 现在解码使用 `pow(gainRGB, 1/gamma)`，与 Adobe / gainmap-js 规范一致。
+   - `gamma = 1`（当前默认）时与旧行为相同，无回归；`gamma ≠ 1` 时结果才会正确。
+   - 同时修正了 `PanoSourceNode.update` 里 `gamma ?? 1000` 的可疑默认值为 `?? 1`。
+
+3. **offset 偏移（✅ 已支持）**
+   - 完整式：`hdr = (sdr + offsetSdr) * boost - offsetHdr`，由 `applyHDROffset` / `applyHDROffsetNode` 统一应用。
+   - `offsetSdr` / `offsetHdr` 已加入 `HDRCfgData` 与瓦片 uniform，可从 `hdrConfig` 读取。
+   - **默认值为 0**（等价于 `sdr * boost`，与历史行为一致）。注意 Adobe 规范默认是 `1/64`；若资源按非零 offset 编码，需在配置里显式提供对应值，暗部才能严格还原。
+
+### weight 公式对比
+
+本项目的 weight 与 gainmap-js 完全一致（只是 gainmap-js 的 capacity 已在 log2 空间，省掉了外层 `log2`）：
+
+```
+# 本项目（capacity 为线性倍数）
+weight = clamp( (log2(maxDisplayBoost) - log2(hdrCapacityMin))
+               / (log2(hdrCapacityMax) - log2(hdrCapacityMin)), 0, 1 )
+
+# gainmap-js（capacity 已是 log2 值）
+weight = clamp( (log2(maxDisplayBoost) - hdrCapacityMin)
+               / (hdrCapacityMax - hdrCapacityMin), 0, 1 )
+```
+
+两式在“capacity 线性 vs log2”约定统一后是同一个公式。
+
+## 关键代码位置
+
+- `lib/five/model/materials/nodes/PanoSourceNode.ts`
+  - `computeHDRBoost(gainRGB, maxDisplayBoost)`：增益系数计算（TSL 节点）。
+  - `sampleHDR(cameraDirection, maxDisplayBoost, rgba?)`：采样 SDR 底图与 GainMap 并输出 `sdrColor.rgb * boost`。
+- `lib/five/core/tiling.ts`
+  - `computeHDRBoostNode(gainRGB, uniforms)`：瓦片细化路径下的等价实现（带除零保护）。
+  - `TileMaterial.setupNode()`：`mix(sdr, sdr*boost, enabled)` 的烘焙逻辑。
+- `lib/five/utils/hdr-data.ts`：`HDRCfgData` 定义与 `parseHDRCfgData` 解析。
+
+## 使用示例
+
+参见 `examples/hdr/index.ts` 与 `examples/_tools/hdr-viewer/panes/hdr.ts`：到达点位后从 `observer.images.hdrConfig` 拉取元数据，`maxDisplayBoost` 可实时调节以观察增益变化。

package/ai_guides/features/view-layer.md

@@ -0,0 +1,187 @@
+# ViewLayer (视图层)
+
+- **Summary**: ViewLayer 是 Model 的组成部分，负责管理具体的 3D 资源（如 Mesh 或 PointCloud），支持独立的渲染配置和可见性控制。
+- **Schema**: 继承自 `Tile3D`，由 `Model` 统一管理。
+- **Concepts**: Layer Fallback, 3DTile Integration, Parameter Inheritance.
+- **Examples**: 可见性控制、参数配置、事件监听。
+
+## Schema
+
+> **Definition**: [ViewLayer](../../five/model/view-layer.d.ts), [ViewLayerInit](../../five/model/view-layer.d.ts)
+
+ViewLayer 是一个具体的渲染图层，它对应一个具体的 3D 数据源（通常是一个 `.gltf` / `.b3dm` / `.pnts` 等 Tileset 入口）。
+
+```typescript
+// 简化定义
+interface ViewLayer extends Tile3D {
+  /** 图层名称 (如 'mesh', 'point_cloud') */
+  name: string;
+  /** 图层类型 */
+  type: "point_cloud" | "mesh" | "gaussian_splatting";
+  /** 独立的参数配置对象 */
+  parameter: Parameter;
+  /** 是否可见 */
+  visible: boolean;
+  /** 对应的 Tileset URL */
+  tilesetUrl: string;
+}
+```
+
+## Concepts
+
+### 1. ViewLayer vs Work.Model
+
+`ViewLayer` 的生成逻辑严格依赖于 `Work` 数据中的定义，但也包含了向后兼容的 Fallback 机制。
+
+#### 数据来源 (Data Source)
+
+1.  **优先使用 `work.model.layers`**:
+    这是标准的定义方式。`work.model.layers` 是一个数组，每个元素显式定义了一个 Layer 的 `name`, `type`, `tileset` (URL) 等信息。
+    Five 会遍历这个数组，为每一项创建一个 `ViewLayer` 实例。
+
+2.  **Fallback to `work.model.file`**:
+    如果 `work.model.layers` 中没有定义 `mesh` 类型的层，且 `work.model.file` 存在（旧版数据字段），Five 会自动创建一个 **虚拟的 Mesh Layer**。
+    *   **Name**: 默认为 `model` (或其他内部标识)。
+    *   **Type**: `mesh`。
+    *   **URL**: 指向 `work.model.file`。
+    *   **UpAxis**: 根据文件后缀自动推断 (如 `.obj` 可能需要特殊处理)。
+
+> **总结**: `ViewLayer` 是 `work.model` 数据的运行时表现。`layers` 字段提供了精细的控制，而 `file` 字段提供了旧数据的兼容支持。
+
+### 2. ViewLayer vs 3DTile
+
+`ViewLayer` 本质上是一个 **3DTile** 加载器实例（继承自 `Tile3D`）。
+
+*   **加载机制**: 每个 ViewLayer 独立维护一个 3DTiles 的遍历器 (Traverser) 和调度器 (Scheduler)。这意味着 Mesh 层、PointCloud 层和 GaussianSplatting 层是独立加载、独立计算 LOD (Level of Detail) 的。
+*   **空间变换**: ViewLayer 负责处理数据的坐标系转换 (如 ECEF 转 ENU，Y-Up 转 Z-Up)，确保不同格式的数据在 Five 场景中正确对齐。
+
+### 3. ViewLayer, Model, ModelScene & Parameter
+
+这是 Five 渲染架构的核心层级关系，`Parameter` 在其中起到了“胶水”的作用。
+
+#### 层级关系 (Hierarchy)
+
+```mermaid
+graph TD
+  Scene[ModelScene] -->|包含| Model[Model]
+  Model -->|包含| LayerA[ViewLayer (Mesh)]
+  Model -->|包含| LayerB[ViewLayer (PointCloud)]
+```
+
+#### Parameter 的作用 (Inheritance)
+
+`Parameter` 系统贯穿了上述三层，实现了**“配置继承与覆盖”**。
+
+1.  **ModelScene (全局配置)**:
+    *   持有 `five.modelScene.parameter`。
+    *   定义了场景级的默认值（如：默认显存上限 `512MB`）。
+2.  **Model (模型级配置)**:
+    *   持有 `model.parameter`。
+    *   可以覆盖全局配置（如：特定模型需要 `1024MB` 显存）。
+3.  **ViewLayer (图层级配置)**:
+    *   持有 `viewLayer.parameter`。
+    *   **最具体的控制点**。它在计算最终值时，会依次继承 `Model` 和 `ModelScene` 的配置。
+
+**示例场景**:
+*   如果你想让**整个场景**变暗，设置 `modelScene.parameter.set('opacity', 0.5)`。
+*   如果你只想让**点云层**变暗，保留模型层亮度，设置 `pointCloudLayer.parameter.set('opacity', 0.5)`。
+
+### 4. Visibility Control (可见性控制)
+
+默认情况下，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', 'point_cloud']` 可以强制同时显示模型和点云）。
+
+2.  **运行时控制 (Runtime Control)**:
+    加载完成后，可以直接修改 `viewLayer.visible` 属性来切换可见性。
+
+## Configuration
+
+ViewLayer 的配置主要通过其 `parameter` 属性进行。
+
+### Common Configuration
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `visible` | `boolean` | 控制图层的可见性 (也可直接修改 `viewLayer.visible`)。 |
+| `opacity` | `number` | 图层透明度 (0.0 - 1.0)。 |
+| `pointSize` | `number` | (仅点云) 点的大小。 |
+
+> 更多配置项请参考 [Parameter](./parameter.md) 和 [3DTile Params](./3dtile.md)。
+
+## Examples
+
+### 1. 访问 ViewLayer
+
+```typescript
+// 获取当前模型
+const model = five.model;
+
+// 遍历所有图层
+model.viewLayers.forEach(layer => {
+  console.log(`Layer Name: ${layer.name}, Type: ${layer.type}`);
+});
+
+// 查找特定的图层 (例如点云层)
+const pointCloudLayer = model.viewLayers.find(layer => layer.type === 'point_cloud');
+```
+
+### 2. 独立控制图层可见性
+
+```typescript
+// 方式 A: 运行时控制
+const meshLayer = five.model.viewLayers.find(layer => layer.type === 'mesh');
+
+if (meshLayer) {
+  // 隐藏模型层，只看点云
+  meshLayer.visible = false;
+  // 或者通过 parameter 设置
+  // meshLayer.parameter.set('visible', false);
+}
+
+// 方式 B: 加载时控制 (初始化时仅显示 mesh)
+five.load(work, {
+  model: {
+    "3d-tiles": {
+      showLayers: ['mesh'] // 仅显示 mesh 层，隐藏 point_cloud 等其他层
+    }
+  }
+});
+```
+
+### 3. 修改特定图层的渲染参数
+
+```typescript
+const pointCloudLayer = five.model.viewLayers.find(layer => layer.type === 'point_cloud');
+
+if (pointCloudLayer) {
+  // 仅修改点云层的点大小，不影响其他模型
+  pointCloudLayer.parameter.set('pointSize', 2.0);
+
+  // 仅修改点云层的最大显存占用
+  pointCloudLayer.parameter.set('maxMemoryUsage', 128);
+}
+```
+
+## Related
+
+*   [Model](./model.md): ViewLayer 的父级容器。
+*   [Work](./work.md): 定义 ViewLayer 数据结构的数据源。
+*   [Parameter](./parameter.md): 控制 ViewLayer 渲染表现的配置系统。
+*   [3DTile](./3dtile.md): ViewLayer 的底层技术实现。
+
+---
+
+```yaml
+tags: [viewlayer, model, 3dtile, parameter, layer]
+```