@realsee/five-webgpu 1.0.0-alpha.1 → 1.0.0-alpha.10

package/ai_guides/features/image-options.md

@@ -103,7 +103,7 @@ SDK 内置了图片格式兼容性检测（`imageSupport`）。
 启用 AVIF 格式并设置初始尺寸为 `512`，适用于大多数场景。
 
 ```typescript
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
 const five = new Five({
   imageOptions: {
@@ -117,7 +117,7 @@ const five = new Five({
 将数据中的 `custom-oss-public.ljcdn.com` 域名映射到对应的资源专用 OSS 域名。
 
 ```typescript
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
 const five = new Five({
   imageOptions: {
@@ -139,7 +139,7 @@ const five = new Five({
 使用 SDK 提供的 `defaultImageURLTransform` 工具函数（通常导出为 `defaultImageURLTransform`，可重命名为 `imageURL`），结合 `cut` 参数获取全景图特定区域（例如获取前方图片的中心 512x512 区域）。
 
 ```typescript
-import { defaultImageURLTransform as imageURL } from "@realsee/five";
+import { defaultImageURLTransform as imageURL } from "@realsee/five-webgpu";
 
 const originalUrl = "https://vr-public.realsee-cdn.com/.../pano_f.jpg";
 

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

@@ -30,7 +30,7 @@ export type LoadResultType<Scene = THREE.Object3D> = {
 
 // 通用配置项接口
 interface BaseLoaderOptions {
-  upAxis?: 'Y' | 'Z';         // 期望输出的上轴，默认为 'Z' (Five 坐标系)
+  upAxis?: 'Y' | 'Z';         // 期望输出的上轴，默认为 'Z'（加载器输出坐标系）
   modelUpAxis?: 'Y' | 'Z';    // (部分加载器支持) 原始模型的上轴，用于自动旋转修正
   fetcher?: Fetcher;          // 自定义网络请求 Fetcher
   light?: boolean;            // 是否使用简化/无光照材质 (取决于加载器实现)
@@ -41,18 +41,18 @@ interface BaseLoaderOptions {
 ## Concepts
 
 ### 独立加载函数 (Standalone Functions)
-这些加载函数（如 `loadGltf`, `loadPly`）是 `@realsee/five` 包导出的**独立函数**，而非 `Five` 实例的方法。你需要单独引入它们使用。
+这些加载函数（如 `loadGltf`, `loadPly`）是 `@realsee/five-webgpu` 包导出的**独立函数**，而非 `Five` 实例的方法。你需要单独引入它们使用。
 
 ### 坐标系转换 (Up-Axis Conversion)
-Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
+Five 运行时场景使用 **Y-up** (Y 轴向上) 的右手坐标系；加载器默认输出通常为 **Z-up**。
 许多外部模型（如 standard GLTF, FBX）通常是 **Y-up** 的。
 加载器提供了 `upAxis` 和 `modelUpAxis` 选项来自动处理旋转：
-- `upAxis`: 你期望得到的结果坐标系上轴（通常保持默认 'Z'）。
+- `upAxis`: 你期望得到的加载器输出坐标系上轴（通常保持默认 'Z'）。
 - `modelUpAxis`: 原始文件的上轴（如 GLTF 默认为 'Y'，PLY 默认为 'Z'）。
-如果不指定，加载器会尝试使用合理的默认值将模型旋转到 Z 轴向上。
+如果不指定，加载器会使用各自的默认值；将结果直接添加到 `five.scene` 时，应按需设置 `upAxis: 'Y'` 与 Five 的运行时坐标系对齐。
 
 ### 资源销毁 (Disposal)
-加载的模型包含 Geometry、Material 和 Texture 等 WebGL 资源。当你不再需要该模型时（例如切换场景或移除物体），**必须**调用返回结果中的 `dispose()` 方法来释放内存，否则会导致内存泄漏。
+加载的模型包含 Geometry、Material 和 Texture 等 GPU 资源。当你不再需要该模型时（例如切换场景或移除物体），**必须**调用返回结果中的 `dispose()` 方法来释放资源，否则会导致内存泄漏。
 
 ### Fetcher
 所有加载器支持传入自定义 `fetcher`。这在需要鉴权、自定义 Header 或处理特定 CDN 逻辑时非常有用。如果不传，默认使用内部的 `internalFetcher`。
@@ -206,8 +206,8 @@ Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
 ### 基础用法：加载 GLTF 模型 (Basic Usage)
 
 ```typescript
-import { Five, FivePlugin } from '@realsee/five';
-import { loadGltf } from '@realsee/five';
+import { Five, FivePlugin } from '@realsee/five-webgpu';
+import { loadGltf } from '@realsee/five-webgpu';
 import * as THREE from 'three';
 
 const five = new Five({/*...*/});
@@ -237,11 +237,11 @@ loadGltf('https://example.com/model.glb').then((result) => {
 ### 进阶用法：加载高斯泼溅 (Gaussian Splat)
 
 ```typescript
-import { loadSplat } from '@realsee/five';
+import { loadSplat } from '@realsee/five-webgpu';
 
 loadSplat('https://example.com/scene.splat', {
   modelUpAxis: 'Y', // 假设原始数据是 Y-up
-  upAxis: 'Z',      // 转换到 Five 的 Z-up
+  upAxis: 'Y',      // 转换到 Five 的 Y-up 运行时坐标系
 }).then((result) => {
   const splatMesh = result.scene;
   five.scene.add(splatMesh);
@@ -252,7 +252,7 @@ loadSplat('https://example.com/scene.splat', {
 ### 进阶用法：自定义 PLY 属性映射 (Custom PLY Properties)
 
 ```typescript
-import { loadPly } from '@realsee/five';
+import { loadPly } from '@realsee/five-webgpu';
 
 loadPly('https://example.com/data.ply', {
   type: 'pbmPointCloud',
@@ -272,7 +272,7 @@ loadPly('https://example.com/data.ply', {
 ### 基础用法：加载 OBJ 模型 (Basic Usage - OBJ)
 
 ```typescript
-import { loadObj } from '@realsee/five';
+import { loadObj } from '@realsee/five-webgpu';
 
 loadObj('https://example.com/model.obj', {
   modelUpAxis: 'Z', // OBJ 默认通常是 Z-up (或根据实际情况调整)
@@ -285,7 +285,7 @@ loadObj('https://example.com/model.obj', {
 ### 基础用法：加载 FBX 模型
 
 ```typescript
-import { loadFbx } from '@realsee/five';
+import { loadFbx } from '@realsee/five-webgpu';
 
 loadFbx('https://example.com/model.fbx').then((result) => {
   five.scene.add(result.scene);
@@ -296,7 +296,7 @@ loadFbx('https://example.com/model.fbx').then((result) => {
 ### 进阶用法：加载 Dome 全景 (Panorama)
 
 ```typescript
-import { loadDome } from '@realsee/five';
+import { loadDome } from '@realsee/five-webgpu';
 
 // 加载 .dome 或 .domez 格式
 loadDome('https://example.com/panorama.domez', {
@@ -313,7 +313,7 @@ loadDome('https://example.com/panorama.domez', {
 ### 进阶用法：加载压缩模型 (AT3D)
 
 ```typescript
-import { loadAt3d } from '@realsee/five';
+import { loadAt3d } from '@realsee/five-webgpu';
 
 loadAt3d('https://example.com/model.at3d', {
   light: false,

package/ai_guides/features/load-progress.md

@@ -85,11 +85,11 @@ const progress = tile.content.loadProgress; // [0, 1]
 监控单个 Tile 的加载与卸载事件，用于更精细的调试或资源统计。
 
 ```ts
-five.on("model.tileLoad", (tile) => {
+five.on("models.tileLoad", ({ tile }) => {
   console.log(`Tile loaded: ${tile.debugLabel}, Size: ${tile.content.byteLength}`);
 });
 
-five.on("model.tileUnload", (tile) => {
+five.on("models.tileUnload", ({ tile }) => {
   console.log(`Tile unloaded: ${tile.debugLabel}`);
 });
 ```

package/ai_guides/features/material.md

@@ -51,12 +51,19 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 
 ### 4. Vertex Marks & Semantic Filtering (顶点标记与语义过滤)
 
-`vertexMarks` 是一个**全局开关**，用于控制是否启用模型顶点上的语义标记（`_feature_id_rsmask`）逻辑。
-
-*   **机制**: 模型顶点预置了 `_feature_id_rsmask` 属性，不同的值代表不同的语义部分。
-*   **当前支持**: 目前主要支持 `_feature_id_rsmask=1`（通常标记为天花板/房顶）。
-    *   当 `vertexMarks` 开启时，标记为 `1` 的顶点部分会在特定视角（如俯视）下自动隐藏，实现“开盖”效果，优化室内布局观测体验。
-*   **未来扩展**: 该机制设计支持更多标记值，未来可能用于控制其他特定模型部件的显示效果。
+`vertexMarks` 用于控制模型顶点上的语义标记（`_feature_id_rsmask`）逻辑。它是一个**按位掩码（bit flag）**，可以独立开关多类标注，而不再是单一的全局 `boolean` 开关。
+
+*   **机制**: 模型顶点预置了 `_feature_id_rsmask` 属性，不同的值代表不同的语义部分；每一类标注对应掩码中的一位，可按位独立启用。
+*   **标志位 (`PBMVertexMarkFlag`)**:
+    *   `PBMVertexMarkFlag.roof` (`0b00000010`): 开盖标注（`_feature_id_rsmask=1`）。开启后，命中屋顶标记的顶点会按 `roofStyle` 裁切：`AUTO` 随相机俯仰角渐进隐藏，`HIDE` 始终隐藏。
+    *   `PBMVertexMarkFlag.hidden` (`0b00000100`): 隐藏标注（`_feature_id_rsmask=2`）。开启后，命中隐藏标记且超过高度阈值的顶点会被裁掉。
+    *   `PBMVertexMarkFlag.none` (`0b00000000`): 不启用任何标注。
+    *   `PBMVertexMarkFlag.all` (`0b11111111`): 启用全部标注（默认全开，且包含未来新增的标注档位）。
+*   **按位组合**: 使用按位或组合多个标志，例如同时开启开盖与隐藏：
+    `PBMVertexMarkFlag.roof | PBMVertexMarkFlag.hidden`。
+*   **向后兼容**: `vertexMarks` 仍接受 `boolean`。传入 `true` 等价于 `PBMVertexMarkFlag.all`（全开），`false` 等价于 `PBMVertexMarkFlag.none`（全关）。
+*   **与自定义节点的关系**: 节点上下文中的 `isRoof` / `isHidden` 等标记判定**始终可用**，不受本开关影响；`vertexMarks` 只门控管线内置的自动裁切。
+*   **未来扩展**: 新增标注档位时，只需在 `PBMVertexMarkFlag` 中追加一个新的位，不影响现有标志。
 
 ## Configuration
 
@@ -74,7 +81,7 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 | `pointMinPixel` | `number` | `0` | 点云最小像素尺寸。 |
 | `pointMaxPixel` | `number` | `40` | 点云最大像素尺寸。 |
 | `pointAppearAnimation` | `boolean` | `true` | 是否开启点云出现动画。 |
-| `vertexMarks` | `boolean` | `true` | 是否显示/生效标注。 |
+| `vertexMarks` | `boolean \| number` | `true` | 顶点标注开关，按位控制（见 Concepts）。`PBMVertexMarkFlag` 位掩码；传入 `boolean` 时 `true`=全开、`false`=全关。 |
 | `brightness` | `number` | `1.0` | 场景亮度倍数。 |
 | `floorStyle` | `PBMFloorStyle` | `'OPACITY'` | 楼层显示样式。 |
 | `shownFloorIndex` | `number` | `-1` | 当前显示的楼层索引。`-1` 表示显示所有楼层。 |
@@ -140,6 +147,26 @@ five.model.set({
 });
 ```
 
+### 3. Toggling Vertex Marks (控制顶点标注)
+
+```typescript
+import { PBMVertexMarkFlag } from '@realsee/five-webgpu';
+
+// 仅开启“开盖”标注
+five.model.set({ vertexMarks: PBMVertexMarkFlag.roof });
+
+// 同时开启“开盖”与“隐藏”标注
+five.model.set({
+  vertexMarks: PBMVertexMarkFlag.roof | PBMVertexMarkFlag.hidden,
+});
+
+// 关闭全部标注
+five.model.set({ vertexMarks: PBMVertexMarkFlag.none });
+
+// 向后兼容：true 等价于全开，false 等价于全关
+five.model.set({ vertexMarks: true });
+```
+
 ## Related
 
 *   [Parameter](./parameter.md): 配置系统入口与继承逻辑。
@@ -149,5 +176,5 @@ five.model.set({
 ---
 
 ```yaml
-tags: [material, appearance, pointcloud, parameter, roof, ceiling, config]
+tags: [material, appearance, pointcloud, parameter, roof, hidden, ceiling, 开盖, 隐藏, 顶点标记, 位掩码, bitmask, vertex-mark, config]
 ```

package/ai_guides/features/mode.md

@@ -1,8 +1,8 @@
 # Mode (模式)
 
-- **Summary**: Five 支持多种交互模式，包括全景漫游、模型浏览、VR/XR 等，适用于不同的看房场景。
-- **Schema**: 字符串枚举类型，定义了 6 种交互模式。
-- **Concepts**: Panorama, Mapview, Floorplan, Topview, Model, VR/XR。
+- **Summary**: Five 支持全景漫游、模型浏览等五种交互模式，适用于不同的看房场景。
+- **Schema**: 字符串枚举类型，定义了 5 种交互模式。
+- **Concepts**: Panorama, Mapview, Floorplan, Topview, Model。
 - **Examples**: 模式切换与事件监听。
 
 ## Schema
@@ -13,13 +13,12 @@
 
 ```ts
 type Mode =
-  | "Panorama"   // 全景图游走模式
-  | "Mapview"    // 模型地图模式
-  | "Floorplan"  // 模型户型图模式
-  | "Topview"    // 模型平面图模式
-  | "Model"      // 模型游走模式
-  | "VRPanorama" // Cardboard VR 眼镜模式
-  | "XRPanorama" // WebXR 虚拟现实 VR 眼镜模式
+  | "Panorama"    // 全景图游走模式
+  | "Mapview"     // 模型地图模式
+  | "Floorplan"   // 模型户型图模式
+  | "Topview"     // 模型平面图模式
+  | "Model"       // 模型游走模式
+  | "VRPanorama"  // 手机 Cardboard 分屏全景模式（陀螺仪驱动）
 ```
 
 ## Concepts
@@ -34,8 +33,12 @@ type Mode =
     *   交互：鼠标拖拽 / Pan手势平移相机；滚轮 / Pinch手势缩放画面；点击 / Tap切换到最近全景点。
 *   **Model (模型漫游)**: 适用于第一人称在场景中自由游览。交互同 Panorama，但不限制相机只能在观察点位置。
     *   交互：鼠标拖拽 / Pan手势旋转视角；滚轮 / Pinch手势缩放视场角；点击 / Tap移动到指定位置。
-*   **VRPanorama / XRPanorama**: 适配 VR 设备（如 Google Cardboard, Apple Vision Pro 等）的沉浸式模式。
-    *   交互：配合设备手柄或头部追踪，基本交互逻辑同 Panorama。
+*   **XRPanorama (WebXR 头显全景)**: 适用于通过 WebXR 在 VR 头显（Pico / Quest / Apple Vision Pro 等）中沉浸式浏览全景。头显朝向决定看景方向，用手柄 / 注视射线指向并走动到全景点位。
+    *   交互：头显朝向看景；手柄指向射线（或 Vision Pro 的注视射线）拾取；手柄按键 tap / press 走点与触发事件。
+    *   前置条件：**必须在 `new Five({ forceWebGL: true })` 时开启 WebGL2 回落后端**（`three` 的 WebGPU 后端目前不支持 WebXR）；浏览器需支持 WebXR（存在 `navigator.xr`）。
+    *   进入：`five.changeMode('XRPanorama')` 或 `five.setState({ mode: 'XRPanorama' })`，会触发一次 XR 会话权限请求（需在用户手势中调用）。
+    *   退出：监听 `xr.session.end` 事件后切回其他模式（如 `Panorama`）。
+*   **VRPanorama (Cardboard 分屏全景)**: 适用于手机配合 Cardboard 眼镜的分屏体验。使用陀螺仪驱动视角，左右眼分屏渲染。**不需要头显设备，也不需要 `forceWebGL`**。
 
 ## Configuration
 
@@ -135,22 +138,6 @@ interface ModelConfig {
 }
 ```
 
-### VRPanorama / XRPanorama (VR 模式)
-
-继承自 Panorama 配置，但移除了俯仰角限制（`maxLatitude`, `minLatitude`），因为 VR 模式下视角由设备姿态控制。
-
-```typescript
-interface VRPanoramaConfig {
-  // ... 同 Panorama 基础配置
-  // 移除: maxLatitude, minLatitude
-}
-
-interface XRPanoramaConfig {
-  // ... 同 Panorama 基础配置
-  // 移除: maxLatitude, minLatitude
-}
-```
-
 ## Examples
 
 ### 快速上手 (Quick Example)
@@ -167,7 +154,7 @@ five.setState({ mode: 'Mapview' });
 在 `new Five()` 时配置各个模式的默认参数：
 
 ```typescript
-import { Five, PanoCircleMeshSolid } from '@realsee/five';
+import { Five, PanoCircleMeshSolid } from '@realsee/five-webgpu';
 
 const five = new Five({
   // 全景模式配置
@@ -225,7 +212,7 @@ five.updateConfiguration({
 使用 `changeMode` 精准控制切换过程，并监听完成时机：
 
 ```ts
-import { Five, Mode } from '@realsee/five';
+import { Five, Mode } from '@realsee/five-webgpu';
 
 const five = new Five();
 
@@ -255,15 +242,25 @@ document.querySelector('#btn-map').addEventListener('click', () => {
 1.  **相机类型差异**：`Topview` 模式使用的是正交相机 (OrthographicCamera)，而其他模式使用的是透视相机 (PerspectiveCamera)。在进行自定义渲染或计算时需注意投影矩阵的差异。
 2.  **切换动画**：`setState` 触发的切换动画是自动规划的，而 `changeMode` 允许更细粒度的控制。如果需要精确控制动画时长或回调，请使用 `changeMode`。
 3.  **全景加载**：`Panorama` 模式下会自动使用瓦片（tile）方式加载全景图以平衡效率和清晰度，而其他模式（如 `Mapview`）主要展示模型几何。
+4.  **`XRPanorama` 与 `VRPanorama` 不要混淆**：
+    *   `VRPanorama` 是手机 Cardboard 分屏 + 陀螺仪方案，**不需要头显、不需要 `forceWebGL`**，面向的是把手机塞进纸盒眼镜的场景。
+    *   `XRPanorama` 走的是真正的 WebXR 头显设备（Pico / Quest / Apple Vision Pro 等），**必须 `new Five({ forceWebGL: true })`**，面向的是独立 VR 头显。
+    *   两者的驱动源（陀螺仪 vs WebXR viewer pose）、渲染路径（分屏 quad vs XR projection layer）、输入方式（无手柄 vs 手柄 / 注视射线）都不同，切换前请先确认目标设备。
+5.  **`XRPanorama` 的能力降级限制**（均源自 `forceWebGL` 的 WebGL2 回落后端，无法规避）：
+    *   **XR 下没有后处理**：XR 模式会整体旁路 `FiveRenderer` 的后处理链路（合成 / EffectComposer 全屏 pass 都不参与），滤镜、泛光等后处理效果在头显中不生效。
+    *   **点云走 NodeMaterial 路径**：`forceWebGL` 下点云不再走 WebGPU compute 光栅化，而是退回 NodeMaterial 渲染路径。
+    *   **3DGS 走 CPU 排序，且 VR 中性能预期需放低**：`forceWebGL` 下 3DGS 只能走 CPU 排序（`RASTER_CPU_SORT`）；在 XR 中还叠加了双眼渲染的开销，务必对点数 / 显示做降级，不要期待与 WebGPU 后端相同的帧率。
 
 ## Related
 
 *   [State - 状态](./state.md): 了解 Mode 在 State 中的位置及其他状态属性。
 *   [Gesture - 手势](./gesture.md): 了解不同模式下的手势交互逻辑。
 *   [Event - 事件](./event.md): 了解模式切换等相关事件。
+*   [Five - 核心类](./five.md): 了解 `forceWebGL` 初始化参数（进入 `XRPanorama` 的前置条件）。
+*   XR 示例：参见 `examples/xr`（`forceWebGL: true` + 按钮进入 `XRPanorama`）。
 
 ---
 
 ```yaml
-tags: [mode, state, interaction]
+tags: [mode, state, interaction, xr, webxr, vr, forceWebGL, XRPanorama, VRPanorama]
 ```

package/ai_guides/features/model.md

@@ -146,7 +146,7 @@ if (model) {
   console.log("模型是否细化完成:", model.refined);
 
   // 监听模型细化事件
-  five.on("model.refined", () => {
+  five.on("models.refined", () => {
     console.log("模型高清资源加载完毕");
   });
 }

package/ai_guides/features/pano-filter.md

@@ -13,7 +13,7 @@
 `PBMPanoFilter` 类定义了全景图的滤镜参数。所有属性均为对象引用，直接修改其内部属性即可生效。
 
 ```typescript
-import { PBMUpdateable } from "@realsee/five";
+import { PBMUpdateable } from "@realsee/five-webgpu";
 
 export class PBMPanoFilter extends PBMUpdateable {
   /** 对比度控制 */
@@ -81,7 +81,7 @@ export class PBMPanoFilter extends PBMUpdateable {
 创建一个滤镜实例并应用到 Five 场景中。
 
 ```typescript
-import { Five, PBMPanoFilter } from "@realsee/five";
+import { Five, PBMPanoFilter } from "@realsee/five-webgpu";
 
 const five = new Five();
 // ... 初始化 five ...
@@ -105,7 +105,7 @@ five.modelScene.parameter.set('panoFilter', panoFilter);
 滤镜参数支持实时修改，适合制作调节面板。
 
 ```typescript
-import { Five, PBMPanoFilter } from "@realsee/five";
+import { Five, PBMPanoFilter } from "@realsee/five-webgpu";
 
 // 假设已经有 five 实例
 const panoFilter = new PBMPanoFilter();

package/ai_guides/features/pano-tile.md

@@ -76,7 +76,7 @@ interface ImageOptions {
 ### 查看瓦片数据结构
 
 ```typescript
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
 const five = new Five();
 
@@ -94,7 +94,7 @@ five.on("loaded", () => {
 ### 配置瓦片加载策略与图片参数
 
 ```typescript
-import { Five } from "@realsee/five";
+import { Five } from "@realsee/five-webgpu";
 
 const five = new Five({
   // 自定义瓦片层级选择策略

package/ai_guides/features/raycast.md

@@ -83,7 +83,7 @@ Five 提供了 `model.intersectRaycaster` 方法，与 Three.js 原生的 `rayca
 
 ```typescript
 import * as THREE from 'three';
-import { Five } from '@realsee/five';
+import { Five } from '@realsee/five-webgpu';
 
 const five = new Five();
 // ... 初始化 ...

package/ai_guides/features/screen-project.md

@@ -55,7 +55,7 @@ interface Five {
 最典型的应用场景是在 3D 场景中的某个物体上方显示一个 HTML 标签。
 
 ```typescript
-import { Five, Mode } from "@realsee/five";
+import { Five, Mode } from "@realsee/five-webgpu";
 import * as THREE from "three/webgpu";
 
 const five = new Five();

package/ai_guides/features/state.md

@@ -13,7 +13,7 @@
 
 ```ts
 import * as THREE from "three/webgpu";
-import { Mode } from "@realsee/five";
+import { Mode } from "@realsee/five-webgpu";
 
 interface Pose {
   /** 相机偏航角 (水平方向)，单位：弧度 */
@@ -79,8 +79,8 @@ const state = five.state;
 
 // 在当前状态基础上，向右旋转 90 度，并略微拉远距离
 five.setState({
-  longitude: tate.longitude + Math.PI / 2,
-  distance: tate.distance + 2.0
+  longitude: state.longitude + Math.PI / 2,
+  distance: state.distance + 2.0
 });
 ```
 

package/ai_guides/features/ultra-hdr.md

@@ -1,13 +1,13 @@
-# UltraHDR / GainMap 渲染
+# UltraHDR / gainmap 渲染
 
-本篇说明 five-webgpu 如何用 UltraHDR（GainMap）方案还原全景图的高动态范围，重点是**最终 RGB 是如何算出来的**。
+本篇说明 five-webgpu 如何用 UltraHDR（gainmap）方案还原全景图的高动态范围，重点是**最终 RGB 是如何算出来的**。
 
 ## 基本原理
 
 UltraHDR 不直接存 HDR 像素，而是拆成两部分：
 
 - **SDR 底图（base / color）**：普通的 8bit 全景图，直接可显示。
-- **GainMap（增益图）**：每个像素存一个 `[0,1]` 的增益值，表示该像素相对 SDR 需要放大多少亮度。
+- **gainmap（增益图）**：每个像素存一个 `[0,1]` 的增益值，表示该像素相对 SDR 需要放大多少亮度。
 
 渲染时的公式是：
 
@@ -15,11 +15,11 @@ UltraHDR 不直接存 HDR 像素，而是拆成两部分：
 finalRGB = sdrRGB * boost(gain)
 ```
 
-`boost` 是由 GainMap 值加上一组元数据（HDR config）算出的每通道增益系数。当没有 HDR（增益全为 1 / 未启用）时 `boost = 1`，退化为普通 SDR。
+`boost` 是由 gainmap 值加上一组元数据（HDR config）算出的每通道增益系数。当没有 HDR（增益全为 1 / 未启用）时 `boost = 1`，退化为普通 SDR。
 
 ## 相关数据结构
 
-GainMap 元数据来自每个点位的 `hdrConfig`（`HDRCfgData`）：
+gainmap 元数据来自每个点位的 `observer.images.gainmap?.cfg`（`GainmapCfgData`）：该点位无 HDR 数据时 `images.gainmap` 字段不存在。
 
 | 字段 | 含义 |
 | --- | --- |
@@ -27,9 +27,9 @@ GainMap 元数据来自每个点位的 `hdrConfig`（`HDRCfgData`）：
 | `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`） |
+| `gamma` | gainmap 的编码 gamma（解码用 `1/gamma`） |
+| `offsetSdr` | SDR 偏移，缺省 `1/64`（UltraHDR 规范默认值） |
+| `offsetHdr` | HDR 偏移，缺省 `1/64`（UltraHDR 规范默认值） |
 
 另外还有一个运行时可调参数：
 
@@ -37,7 +37,7 @@ GainMap 元数据来自每个点位的 `hdrConfig`（`HDRCfgData`）：
 
 ## 最终 RGB 的计算步骤
 
-对应实现见 `PanoSourceNode.computeHDRBoost`（以及瓦片路径下等价的 `tiling.ts#computeHDRBoostNode`）。
+对应实现见 `lib/five/model/materials/tsl/utils.ts#hdrBoost` / `#hdrOffset`（以及瓦片路径下等价的 `lib/five/core/tiling.ts#computeHDRBoostNode`）。
 
 ### 1. 计算显示权重 weight
 
@@ -55,11 +55,11 @@ weight = clamp(
 - `weight = 1`：显示器能力达到内容上限 → 全量增益。
 - 中间值：按比例插值。
 
-> 瓦片路径（`computeHDRBoostNode`）对分母做了保护：`max(denom, 1e-6)` 并乘以 `step(1e-6, denom)`，避免非 HDR（capacity 全为 1）时除零产生 NaN。
+> 两条路径都对分母做了保护：`max(denom, 1e-6)` 并乘以 `step(1e-6, denom)`，避免非 HDR（capacity 全为 1）时除零产生 NaN（此时权重取 0，退化为 SDR）。
 
-### 2. GainMap 解码（gamma）
+### 2. gainmap 解码（gamma）
 
-GainMap 采样值经 gamma 还原为线性增益量（每通道独立），解码使用 gamma 的倒数：
+gainmap 采样值经 gamma 还原为线性增益量（每通道独立），解码使用 gamma 的倒数：
 
 ```
 gainLinear = pow(gainRGB, 1/gamma)   // 对 r/g/b 分别做 pow，与 Adobe 规范一致
@@ -84,7 +84,7 @@ boost = exp2(logGain * weight)     // 每通道
 
 ### 5. 得到最终颜色
 
-应用 GainMap 偏移得到最终 HDR 颜色（`offset` 为 0 时退化为 `sdr * boost`）：
+应用 gainmap 偏移得到最终 HDR 颜色（`offset` 为 0 时退化为 `sdr * boost`）：
 
 ```
 finalRGB = (sdrRGB + offsetSdr) * boost - offsetHdr
@@ -121,22 +121,22 @@ finalRGB = (sdrRGB + offsetSdr) * boost - offsetHdr
 
 解码端 `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`。
+- `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 移植）
+### 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;
@@ -161,17 +161,24 @@ weightFactor = clamp(
 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 值。
+   - 风险：如果 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`。
+2. **gamma 方向（✅ 已修复，pano 与瓦片两条路径一致）**
+   - 解码使用 `pow(gainRGB, 1/gamma)`（规范：`log_recovery = pow(recovery, 1.0 / map_gamma)`），与 Adobe / gainmap-js 规范一致；`gamma` 做了 `> 0` 保护，`gain` 先 clamp 到 `[0,1]`。
+   - `gamma = 1`（当前数据默认）时与旧行为相同，无回归；`gamma ≠ 1` 时结果才会正确。
+   - 注意：`PanoSourceNode` 已删除，公式现在在 `tsl/utils.ts#hdrBoost` 与 `tiling.ts#computeHDRBoostNode` 各有一份，改动需同步。
 
 3. **offset 偏移（✅ 已支持）**
-   - 完整式：`hdr = (sdr + offsetSdr) * boost - offsetHdr`，由 `applyHDROffset` / `applyHDROffsetNode` 统一应用。
-   - `offsetSdr` / `offsetHdr` 已加入 `HDRCfgData` 与瓦片 uniform，可从 `hdrConfig` 读取。
-   - **默认值为 0**（等价于 `sdr * boost`，与历史行为一致）。注意 Adobe 规范默认是 `1/64`；若资源按非零 offset 编码，需在配置里显式提供对应值，暗部才能严格还原。
+   - 完整式：`hdr = (sdr + offsetSdr) * boost - offsetHdr`，由 `tsl/utils.ts#hdrOffset`（pano 路径）与 `tiling.ts#hdrOffsetNode`（瓦片路径）应用，不需要额外的 `applyHDROffset` 包装。
+   - `offsetSdr` / `offsetHdr` 已加入 `GainmapCfgData`（支持 `offset_sdr` / `offset_hdr` 下划线写法）、pano 材质 uniform（`pano0HdrOffsetSdr` 等）与瓦片 uniform，可从 `images.gainmap.cfg` 读取。
+   - **缺省值为 `1/64`**（见导出的 `DEFAULT_GAINMAP_CFG_DATA`，与 UltraHDR 规范默认一致）：cfg 里没有该字段时按 `1/64` 解码。
+   - ⚠️ 编码/解码 offset 必须一致：若打包侧按 `offsetSdr = offsetHdr = 0` 生成 gain map，需在 cfg 里显式写 `0`（否则近黑会略有抬升）；反之若按规范 `1/64` 编码，现在的默认值正好匹配。因此**建议打包侧始终在 cfg 中显式写入这两个字段**。
+
+4. **gainmap 纹理的色彩空间（✅ 已改为 `NoColorSpace`）**
+   - 规范要求 gain map 直接使用 `encoded_recovery / 255`（其自带的色彩配置文件不生效）。
+   - 现在 pano 路径（`panorama` / `floorplan` / `mapview` 的 `loadCubeTexture`）与瓦片路径（`core/tiling.ts` 的 `loadTexture`）都显式传 `colorSpace: THREE.NoColorSpace`；SDR 底图仍为 `SRGBColorSpace`。
+   - three 的 GPU 纹理格式在**首次创建时**按 colorSpace 决定（WebGPU：sRGB → `rgba8unorm-srgb` 做硬件解码），之后只重传像素、不重建格式。因此瓦片纹理池改为按 `尺寸 + colorSpace` 分桶，避免色图与 gainmap 串用同一张池化纹理。
+   - 观感变化：gainmap 中间调不再被 sRGB 曲线压低（`maxDisplayBoost=4`、`maxContentBoost=100`、capacity `1..1000` 时，gain=0.5 的 boost 由约 1.22 → 1.59），亮部更亮；gain=0 与 gain=1 两端不变。若打包侧曾把 `recovery` 按 sRGB 预补偿写进 JPEG（非标准做法），需回退此项。
 
 ### weight 公式对比
 
@@ -191,14 +198,16 @@ weight = clamp( (log2(maxDisplayBoost) - hdrCapacityMin)
 
 ## 关键代码位置
 
-- `lib/five/model/materials/nodes/PanoSourceNode.ts`
-  - `computeHDRBoost(gainRGB, maxDisplayBoost)`：增益系数计算（TSL 节点）。
-  - `sampleHDR(cameraDirection, maxDisplayBoost, rgba?)`：采样 SDR 底图与 GainMap 并输出 `sdrColor.rgb * boost`。
+- `lib/five/model/materials/tsl/utils.ts`
+  - `hdrBoost(gainRGB, maxDisplayBoost, maxContentBoost, minContentBoost, capacityMin, capacityMax, gamma)`：增益系数计算（TSL 节点，含 gamma 解码与容量权重）。
+  - `hdrOffset(sdrRGB, boost, offsetSdr, offsetHdr)`：应用 offset 得到最终 HDR 颜色。
+- `lib/five/model/materials/tsl/defines.ts`
+  - `pano0HdrColor` / `pano1HdrColor`：拼接 `hdrBoost` 与 `hdrOffset`，材质 uniform 由 `pbmMaterial.ts` 的 `pano0Hdr*` / `pano1Hdr*` 属性驱动。
 - `lib/five/core/tiling.ts`
-  - `computeHDRBoostNode(gainRGB, uniforms)`：瓦片细化路径下的等价实现（带除零保护）。
-  - `TileMaterial.setupNode()`：`mix(sdr, sdr*boost, enabled)` 的烘焙逻辑。
-- `lib/five/utils/hdr-data.ts`：`HDRCfgData` 定义与 `parseHDRCfgData` 解析。
+  - `computeHDRBoostNode(gainRGB, uniforms)` / `hdrOffsetNode(...)`：瓦片细化路径下的等价实现（带除零保护）。
+  - `TileMaterial.setupNode()` / `BoundingMaterial`：`mix(sdr, (sdr + offsetSdr) * boost - offsetHdr, enabled)` 的烘焙逻辑。
+- `lib/five/utils/gainmap-data.ts`：`GainmapCfgData` 定义与 `parseGainmapCfgData` 解析（兼容 camelCase 与下划线 key）。
 
 ## 使用示例
 
-参见 `examples/hdr/index.ts` 与 `examples/_tools/hdr-viewer/panes/hdr.ts`：到达点位后从 `observer.images.hdrConfig` 拉取元数据，`maxDisplayBoost` 可实时调节以观察增益变化。
+参见 `examples/hdr/index.ts` 与 `examples/_tools/hdr-viewer/panes/hdr.ts`：到达点位后从 `observer.images.gainmap?.cfg` 拉取元数据（无 HDR 时该字段不存在），`maxDisplayBoost` 可实时调节以观察增益变化。

package/ai_guides/features/work.md

@@ -13,7 +13,7 @@
 
 ```ts
 import * as THREE from "three/webgpu";
-import type { Mode } from "@realsee/five";
+import type { Mode } from "@realsee/five-webgpu";
 
 type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
 
@@ -221,7 +221,7 @@ Observer 是 VR 空间中预设的观察位置。在 **Panorama (全景)** 模
 最基础的用法是从 API 获取数据并加载。
 
 ```ts
-import { Five, parseWork } from "@realsee/five";
+import { Five, parseWork } from "@realsee/five-webgpu";
 
 const five = new Five();
 five.appendTo(document.getElementById("app"));

package/ai_guides/quick-start.md

@@ -7,9 +7,9 @@
 通过 npm 或 yarn 安装：
 
 ```bash
-npm install three@^0.117.1 @realsee/five
+npm install three@^0.183.2 @realsee/five-webgpu
 # or
-yarn add three@^0.117.1 @realsee/five
+yarn add three@^0.183.2 @realsee/five-webgpu
 ```
 
 > **注意**: Five 依赖 `three`，请确保安装了兼容的版本。
@@ -19,7 +19,7 @@ yarn add three@^0.117.1 @realsee/five
 初始化 Five 实例并加载 Work 数据：
 
 ```typescript
-import { Five, parseWork } from "@realsee/five";
+import { Five, parseWork } from "@realsee/five-webgpu";
 
 // 1. 创建 Five 实例
 const five = new Five();