@realsee/five-webgpu 1.0.0-alpha.5 → 1.0.0-alpha.7

package/ai_guides/api.md

@@ -24,7 +24,7 @@ const five = new Five(initArgs?: FiveInitArgs);
 | `five.scene` | `THREE.Scene` | The Three.js scene used for non-model elements. |
 | `five.modelScene` | `ModelScene` | The Three.js scene used for the model. |
 | `five.camera` | `Camera` | The internal camera. |
-| `five.renderer` | `THREE.WebGLRenderer` | The WebGL renderer. |
+| `five.renderer` | `THREE.WebGPURenderer` | The WebGPU renderer. |
 | `five.needsRender` | `boolean` | Set to `true` to request a render frame in the next loop. |
 | `five.plugins` | `Object` | Access to registered plugins. |
 
@@ -32,7 +32,7 @@ const five = new Five(initArgs?: FiveInitArgs);
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
-| `Five.Mode` | `Enum` | Available modes: `Panorama`, `Model`, `Floorplan`, `Topview`, `Mapview`, `VRPanorama`, `XRPanorama`. |
+| `Five.Mode` | `Enum` | Available modes: `Panorama`, `Model`, `Floorplan`, `Topview`, `Mapview`, `VRPanorama`. |
 
 ## Initialization Configuration (`FiveInitArgs`)
 
@@ -40,8 +40,8 @@ Configuration object passed to the `Five` constructor.
 
 ```typescript
 interface FiveInitArgs {
-  /** External WebGLRenderer. If provided, internal renderer creation is skipped. */
-  renderer?: THREE.WebGLRenderer;
+  /** External WebGPURenderer. If provided, internal renderer creation is skipped. */
+  renderer?: THREE.WebGPURenderer;
 
   /** Width/Height of the viewport relative to container (0-1). */
   viewport?: { left: number; bottom: number; width: number; height: number };
@@ -80,12 +80,13 @@ interface FiveInitArgs {
 
 ## Core Methods
 
-### `load(work, state?, options?)`
+### `load(inputWork, state?, options?, userAction?)`
 Loads a "Work" (dataset) into the Five instance.
 
-- **work**: The data object (`LooseWork` or `Work`) containing scene information.
+- **inputWork**: The data object (`LooseWork` or `Work`) containing scene information.
 - **state**: Initial state overrides. `"inherit"`, `"initial"`, or a `State` object.
 - **options**: Loading options (e.g., transition duration).
+- **userAction**: Whether the load was triggered by a user action. Defaults to `true`.
 
 ### `appendTo(element, size?)`
 Mounts the Five canvas to a DOM element.
@@ -243,8 +244,8 @@ These events follow a standard naming convention and provide typed event objects
 | :--- | :--- | :--- |
 | `works.load` | Triggered when work data starts loading. | `WorksEvent` |
 | `models.load` | Triggered when models are loaded. | `ModelSceneEvent` |
-| `model.tileLoad` | Triggered when a 3D tile is loaded. | `Tile` |
-| `model.tileUnload` | Triggered when a 3D tile is unloaded. | `Tile` |
+| `models.tileLoad` | Triggered when a 3D tile is loaded. | `ModelTileEvent` |
+| `models.tileUnload` | Triggered when a 3D tile is unloaded. | `ModelTileEvent` |
 | `pano.arrived` | Triggered when arrival at a panorama node. | `PanoEvent` |
 | `pano.texture.progress` | Triggered when panorama texture loading progresses. | `{ progress, panoIndex }` |
 | `render` | Triggered after each render frame. | `RenderEvent` |

package/ai_guides/features/camera-animation.md

@@ -104,7 +104,7 @@ five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
 
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `modeChangeDuration` | `number` | `1000` | 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。 |
+| `modeChangeDuration` | `number` | `800` | 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。 |
 
 ### MovePanoOptions Configuration (移动参数)
 

package/ai_guides/features/event.md

@@ -70,7 +70,6 @@ Five 的事件系统将事件主要分为以下几类：
 
 - `pano.arrived`: 成功到达新点位（移动动画结束）。
 - `pano.moving`: 正在移动到新点位（动画进行中）。
-- `pano.willChange`: 即将发生点位变更（旧版兼容）。
 - `pano.error`: 点位加载或移动出错。
 
 ### State Events (状态变更)

package/ai_guides/features/five.md

@@ -17,7 +17,7 @@
 ```typescript
 interface FiveInitArgs {
   /** 外部传入的渲染器 (如果传入，部分渲染配置将失效) */
-  renderer?: THREE.WebGLRenderer;
+  renderer?: THREE.WebGPURenderer;
   /**
    * 屏幕渲染区域 { left, bottom, width, height }
    * 必须配合外部 renderer 使用
@@ -35,7 +35,7 @@ interface FiveInitArgs {
   textureOptions?: TextureOptions;
   /** 是否按需渲染 (默认 true, 推荐开启以节省性能) */
   onlyRenderIfNeeds?: boolean;
-  /** 模式切换动画时长 (ms, 默认 1000) */
+  /** 模式切换动画时长 (ms, 默认 800) */
   modeChangeDuration?: number;
   /** 是否支持滚轮缩放 (默认 true) */
   enableWheel?: boolean;
@@ -43,6 +43,17 @@ interface FiveInitArgs {
   plugins?: FivePlugin[];
   /** 是否显示 Powered by Realsee */
   poweredByRealsee?: boolean;
+  /**
+   * 强制使用 WebGL2 回落后端（默认 false）
+   * 进入 XRPanorama（WebXR 头显全景）的前置条件。
+   * 只在构造期生效，后端无法在运行时切换，设备检测必须在 new Five() 之前完成。
+   * 详见下方《forceWebGL 与 XR 回落后端》。
+   */
+  forceWebGL?: boolean;
+  /**
+   * @deprecated 在 five-webgpu 中未接线、无效。需要 WebGL2 后端请使用 `forceWebGL`。
+   */
+  webgl2?: boolean;
 }
 ```
 
@@ -55,7 +66,7 @@ Five 实例是整个 3D 场景的入口。
 
 ### Rendering Loop (渲染循环)
 Five 内部维护了一个 `requestAnimationFrame` 循环。
-- **按需渲染**: 默认开启 `onlyRenderIfNeeds`，仅在画面发生变化（如视角移动、数据加载）时才触发 WebGL 绘制，大幅降低能耗。
+- **按需渲染**: 默认开启 `onlyRenderIfNeeds`，仅在画面发生变化（如视角移动、数据加载）时才触发渲染，大幅降低能耗。
 - **手动触发**: 可以通过 `five.needsRender = true` 强制下一帧进行渲染。
 
 ### Resource Loading (资源加载)
@@ -71,8 +82,66 @@ Five 内部维护了一个 `requestAnimationFrame` 循环。
 | `textureOptions` | `TextureOptions` | `{}` | 贴图加载策略，同上 |
 | `onlyRenderIfNeeds` | `boolean` | `true` | 是否仅在需要时渲染，建议保持 `true` |
 | `antialias` | `boolean` | `false` | 抗锯齿，开启会增加性能消耗 |
-| `modeChangeDuration` | `number` | `1000` | 模式切换动画时长 (ms) |
+| `modeChangeDuration` | `number` | `800` | 模式切换动画时长 (ms) |
 | `enableWheel` | `boolean` | `true` | 是否支持滚轮缩放 |
+| `forceWebGL` | `boolean` | `false` | 强制使用 WebGL2 回落后端，进入 `XRPanorama` 的前置条件，详见下文 |
+| `webgl2` | `boolean` | — | **已废弃**，在 five-webgpu 中未接线。需要 WebGL2 请用 `forceWebGL` |
+
+### forceWebGL 与 XR 回落后端
+
+`forceWebGL` 让 five-webgpu 强制走 WebGL2 回落后端，而不是默认的 WebGPU 后端。它存在的唯一原因是 **进入 `XRPanorama`（WebXR 头显全景）模式**：`three` 的 WebGPU 后端目前不支持 WebXR，而 WebGL2 后端下 `renderer.xr` 完整可用。
+
+**语义与使用约束**
+
+- **语义**：`forceWebGL: true` 时，内部 `WebGPURenderer` 以 `{ forceWebGL: true }` 构造，使用 `WebGLBackend` 而非 WebGPU。
+- **必须在 `new Five()` 时决定**：后端在 renderer 构造期定死，**运行时无法切换**。因此业务侧的「是否需要进入 XR」的设备检测必须发生在 `new Five()` 之前，不能等实例创建后再改。
+- **与 `enableHDR` 互斥**：当 `forceWebGL` 为 `true` 时 `enableHDR` 不生效（`five.enableHDR` 会被置为 `false`），因为 XR 的 projection layer 固定 `colorFormat: RGBA8`，HDR 没有落地路径。
+- **传入外部 `renderer` 时不生效**：如果通过 `renderer` 参数传入了外部渲染器，`forceWebGL` 不会对其生效，需由调用方自行在构造该 renderer 时设置 `forceWebGL`（与 `antialias` 等参数一致）。
+- **`webgl2` 已废弃**：遗留的 `webgl2` 参数在 five-webgpu 中未接线、无任何效果；需要 WebGL2 后端请改用 `forceWebGL`。
+
+**能力降级限制**（开启 `forceWebGL` 后不可规避）
+
+1. **XR 下没有后处理**：`XRPanorama` 模式会整体旁路 `FiveRenderer` 的后处理链路（合成 / EffectComposer 全屏 pass 均不参与），滤镜、泛光等后处理在头显中不生效。
+2. **点云走 NodeMaterial 路径**：`forceWebGL` 下点云不再走 WebGPU compute 光栅化，而是退回 NodeMaterial 渲染路径。
+3. **3DGS 走 CPU 排序，且 VR 中性能预期需放低**：`forceWebGL` 下 3DGS 只能走 CPU 排序（`RASTER_CPU_SORT`）；在 XR 中还要叠加双眼渲染开销，务必对点数 / 显示做降级，不要期待与 WebGPU 后端相同的帧率。
+
+```typescript
+import { Five } from "@realsee/five-webgpu";
+
+// 设备检测需在 new Five() 之前完成
+const needXR = detectNeedXR();
+
+const five = new Five({
+  forceWebGL: needXR, // 一旦创建就无法再切换后端
+});
+
+five.load(workData);
+
+// 进入 XR（需在用户手势回调中调用，会触发 WebXR 权限请求）
+button.addEventListener("click", () => {
+  five.changeMode("XRPanorama").catch((error) => {
+    // 后端非 WebGL2 或浏览器不支持 WebXR 时，这里会收到含 forceWebGL 字样的中文错误
+    console.error(error);
+  });
+});
+
+// 用户摘下头显 / 退出 XR 时切回普通全景
+five.on("xr.session.end", () => five.changeMode("Panorama"));
+```
+
+也可以直接使用内置的 `XRButton`，样式与 API 同原始 five 保持一致（`XRButton.createButton(onClickHook)`）：
+
+```typescript
+import { Five, XRButton } from "@realsee/five-webgpu";
+
+const button = XRButton.createButton(() => five.changeMode("XRPanorama"));
+document.body.appendChild(button);
+```
+
+- 浏览器没有 `navigator.xr` 时显示 `WEBXR NOT AVAILABLE`（非 HTTPS 时显示 `WEBXR NEEDS HTTPS`），不支持 `immersive-vr` 时显示 `VR NOT SUPPORTED`。
+- 回调返回 Promise 时，`XRButton` 会接住 reject。若失败原因是没有开启 `forceWebGL`（后端是 WebGPU），按钮文案会临时变为「需降级到 WebGL2」，3 秒后恢复。其他失败原因不改变按钮，错误通过 `five.on("error")` 上报。
+
+> 更多模式说明（含 `XRPanorama` 与 `VRPanorama` 的区别）见 [mode.md](./mode.md)，可运行示例参见 `examples/xr`。
 
 ## Examples
 
@@ -103,7 +172,7 @@ five.load(workData);
 import * as THREE from "three/webgpu";
 import { Five } from "@realsee/five-webgpu";
 
-const renderer = new THREE.WebGLRenderer();
+const renderer = new THREE.WebGPURenderer();
 renderer.setSize(window.innerWidth, window.innerHeight);
 document.body.appendChild(renderer.domElement);
 
@@ -152,8 +221,8 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 ### 实例方法 (Instance Methods)
 
 - **`appendTo(element: HTMLElement)`**: 将 canvas 挂载到指定 DOM 元素。
-- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [work.md](./work.md)。
-- **`dispose()`**: 销毁实例，释放 WebGL 上下文与内存。
+- **`load(inputWork, state?: "inherit" | "initial" | Partial<State>, options?: number | FiveLoadOptions, userAction?: boolean)`**: 加载场景数据。详见 [work.md](./work.md)。
+- **`dispose()`**: 销毁实例并释放相关渲染资源。
 - **`updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean)`**: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。
 - **`updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)`**: 通过关键帧动画移动相机。
 - **`refresh()`**: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。
@@ -164,7 +233,7 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
     1. **状态同步**：相机姿态已通过动画过渡到目标状态（`stateSynced` 为 true）。
     2. **模型加载**：如果是 Floorplan/Topview/Mapview/Model 模态，需等待模型加载完成 (`modelScene.loaded`)。
     3. **瓦片加载**：如果是 Panorama 模态且传入了 `{ tile: true }`，需等待当前视角的瓦片加载完成。
-- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
+- **`setState(state: Partial<State>, immediately?: boolean, userAction?: boolean)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
 - **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [event.md](./event.md)。
 
 ## Related
@@ -180,5 +249,5 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 ---
 
 ```yaml
-tags: [five, initialization, core, instance, lifecycle]
+tags: [five, initialization, core, instance, lifecycle, forceWebGL, webgl2, xr, webxr]
 ```

package/ai_guides/features/gesture.md

@@ -44,7 +44,7 @@ interface GestureEvent {
 
 Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：
 
-*   **gesture.create**: 所有事件创建时。
+*   **gesture.fire**: 任意事件被触发。
 *   **gesture.pan**: 拖拽/平移。
 *   **gesture.pinch**: 双指缩放。
 *   **gesture.tap**: 点击。

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;            // 是否使用简化/无光照材质 (取决于加载器实现)
@@ -44,15 +44,15 @@ interface BaseLoaderOptions {
 这些加载函数（如 `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`。
@@ -241,7 +241,7 @@ 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);

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)
@@ -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/state.md

@@ -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` 可实时调节以观察增益变化。