@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.31

package/ai_guides/features/postprocessing.md

@@ -1,6 +1,6 @@
 # 后处理 (Post Processing)
 
-- **Summary**: Five 提供了基于 EffectComposer 的后处理机制，内置了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，并支持开发者编写自定义 Pass。
+- **Summary**: Five 提供了基于 EffectComposer 的后处理机制，默认挂载了自适应亮度 (Auto Exposure) 和眼球穹顶光照 (EDL) 两种效果，同时提供多种可选内置 Pass，并支持开发者编写自定义 Pass。
 - **Schema**: `FivePass` 类及 `Pass` 接口。
 - **Concepts**: EffectComposer, G-Buffer, Pass, AdaptiveLuminance, EyeDomeLighting。
 - **Configuration**: 开启内置 Pass 的开关及参数配置。
@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [FivePass](../../five/renderer/postprocessing/passes/pass.d.ts)
+
 ```typescript
 /**
  * Pass 接口 (兼容 three.js EffectComposer)
@@ -55,7 +57,7 @@ export class FivePass implements Pass {
 
 ## Built-in Passes (内置 Pass)
 
-Five 内置了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭状态。
+Five 默认挂载了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭状态。
 
 ### 1. AdaptiveLuminancePass
 
@@ -78,6 +80,36 @@ Five 内置了两个 Pass 实例，挂载在 `five` 实例上，默认是关闭
     *   `radius` (number): 采样半径，影响阴影的范围。
 *   **注意**: 这是一个基于屏幕空间深度的算法，依赖 Depth Buffer。
 
+### 3. Optional Built-in Passes (可选内置 Pass)
+
+Five 新增了三个可选使用的内置 Pass，这些 Pass 没有预先挂载在 `five` 实例上，需手动导入并添加到渲染链中：
+
+*   **[GaussianBlurPass](gaussian-blur-pass.md)**: 高斯模糊效果。
+*   **[FlowingLight2DPass](flowing-light-2d-pass.md)**: 2D 流光效果（通常用于平面路线流光）。
+*   **[FlowingLight3DPass](flowing-light-3d-pass.md)**: 3D 流光效果（通常用于空间路径流光）。
+
+#### GaussianBlurPass 使用示例
+
+```typescript
+import { GaussianBlurPass } from '@realsee/five';
+
+// 1. 创建 GaussianBlurPass 实例 (需要传入 camera)
+const gaussianBlurPass = new GaussianBlurPass(five.camera);
+
+// 2. 配置参数
+// 设置模糊半径 (默认 4.0)
+gaussianBlurPass.setRadius(6);
+
+// 3. 将 Pass 添加到渲染链
+five.addPass(gaussianBlurPass);
+
+// 4. (可选) 动态开关
+// gaussianBlurPass.enabled = false;
+
+// 5. (可选) 移除 Pass
+// five.removePass(gaussianBlurPass);
+```
+
 ## Custom Pass (自定义 Pass)
 
 如果需要实现自定义的后处理效果（如景深、色彩校正、描边等），建议继承 `FivePass`。
@@ -214,11 +246,14 @@ class FogPass extends FivePass {
 
 ## Related
 
-*   [five.ts](../../lib/five/application/five.ts): 查看 `addPass` 方法的实现。
-*   [pass.ts](../../lib/five/renderer/postprocessing/passes/pass.ts): 查看 `FivePass` 基类定义。
+*   [Gaussian Blur Pass](gaussian-blur-pass.md): 高斯模糊 Pass 文档。
+*   [Flowing Light 2D Pass](flowing-light-2d-pass.md): 2D 流光 Pass 文档。
+*   [Flowing Light 3D Pass](flowing-light-3d-pass.md): 3D 流光 Pass 文档。
+*   [five.ts](../../five/application/five.d.ts): 查看 `addPass` 方法的实现。
+*   [pass.ts](../../five/renderer/postprocessing/passes/pass.d.ts): 查看 `FivePass` 基类定义。
 
 ---
 
 ```yaml
-tags: [postprocessing, shader, effect, adaptive-luminance, edl]
+tags: [后处理, 特效, 自定义shader, 滤镜, 描边, 景深, 色彩校正, 渲染管线, postprocessing, shader, effect, adaptive-luminance, edl, effect-composer, addPass]
 ```

package/ai_guides/features/raycast.md

@@ -7,6 +7,8 @@
 
 ## Schema: Three.js Raycaster Extensions
 
+> **Definition**: [Raycaster](../../five/declare.d.ts)
+
 Five 对 Three.js 的 `Raycaster` 进行了扩展，在 `declare module 'three'` 中增加了以下属性：
 
 ```typescript
@@ -41,6 +43,15 @@ declare module 'three' {
      */
     floorIndex?: number;
   }
+
+  export interface Intersection {
+    /** 命中的具体 Tile 对象 (仅 3DTiles) */
+    tile?: Tile;
+    /** 命中的 ViewLayer 对象 */
+    viewLayer?: ViewLayer;
+    /** 命中的 Model 对象 */
+    model?: Model;
+  }
 }
 ```
 
@@ -155,10 +166,13 @@ const intersects = five.model.intersectRaycaster(raycaster);
 
 ## Related
 
-*   [parameter.md](./parameter.md): 了解模型参数配置。
+*   [Parameter](./parameter.md): 了解模型参数配置。
+*   [Screen Project](./screen-project.md): 屏幕坐标与空间坐标转换（标签、拾取的前置步骤）。
+*   [Event](./event.md): 手势事件系统，获取点击坐标的来源。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解 NDC 与世界坐标。
 
 ---
 
 ```yaml
-tags: [raycast, bvh, interaction, performance]
+tags: [点击, 拾取, 碰撞检测, 物体选择, raycast, bvh, interaction, performance, picking, hit-test, click, floor-detection]
 ```

package/ai_guides/features/request-proxy.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
 ```typescript
 interface FiveInitArgs {
   /**
@@ -106,5 +108,5 @@ const five = new Five({
 ---
 
 ```yaml
-tags: [configuration, network, proxy, authentication]
+tags: [请求代理, 鉴权, 域名替换, 私有化, 请求拦截, configuration, network, proxy, authentication, CDN, token, url-rewrite, cors]
 ```

package/ai_guides/features/screen-project.md

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [Five](../../five/application/five.d.ts)
+
 ```typescript
 // defined in Five class
 interface Five {
@@ -155,9 +157,10 @@ container.addEventListener("click", (event) => {
 *   [Raycast](./raycast.md): 详细的射线检测文档。
 *   [Five](./five.md): Five 核心类说明。
 *   [State](./state.md): 了解相机位姿 (Pose)。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解世界坐标与屏幕坐标的关系。
 
 ---
 
 ```yaml
-tags: [coordinate, screen, project, label, ui]
+tags: [标签, 坐标转换, 信息面板, coordinate, screen, project, label, ui, tag, HUD, 3D转2D, overlay, tooltip]
 ```

package/ai_guides/features/state.md

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [State](../../five/types/state.d.ts)
+
 **State** 类型定义如下（继承自 `Pose`）：
 
 ```ts
@@ -77,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
 });
 ```
 
@@ -87,13 +89,33 @@ five.setState({
 1.  **单位混淆**: `longitude` 和 `latitude` 使用**弧度**，而 `fov` 使用**角度**（度）。
 2.  **Offset 类型**: `offset` 必须是 `THREE.Vector3` 实例。如果在 React 等框架中使用纯对象（Plain Object），Five 内部会自动转换，但在 TypeScript 中需注意类型匹配。
 3.  **异步更新**: `setState` 触发的相机运动是异步动画过程。如果需要立即无动画跳转，可传递第二个参数 `immediately: true`。
+4.  **JSON 序列化**: `State` 中的 `offset` 是 `THREE.Vector3` 实例，不能直接 `JSON.stringify`。保存时需手动提取 `{ x, y, z }`，恢复时需重新构造 `new THREE.Vector3(x, y, z)`。
+
+```typescript
+// 保存
+const snapshot = {
+  ...five.state,
+  offset: { x: five.state.offset.x, y: five.state.offset.y, z: five.state.offset.z }
+};
+localStorage.setItem('fiveState', JSON.stringify(snapshot));
+
+// 恢复
+const saved = JSON.parse(localStorage.getItem('fiveState')!);
+five.setState({
+  ...saved,
+  offset: new THREE.Vector3(saved.offset.x, saved.offset.y, saved.offset.z)
+}, true);
+```
 
 ## Related
 
 *   [Mode - 模式](./mode.md): 详细了解各种 Mode 的区别。
+*   [Camera Animation](./camera-animation.md): 基于 State 的相机动画控制。
+*   [Five](./five.md): Five 核心类，`setState` / `getCurrentState` 的宿主。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义。
 
 ---
 
 ```yaml
-tags: [camera, state, pose, interaction]
+tags: [状态保存, 状态恢复, 场景还原, 快照, camera, state, pose, interaction, save, restore, snapshot]
 ```

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, mesh, point-cloud, gaussian-splatting]
+```

package/ai_guides/features/work.md

@@ -7,12 +7,16 @@
 
 ## Schema
 
+> **Definition**: [Work](../../five/work/work.d.ts), [LooseWork](../../five/work/looseWorkType.d.ts), [WorkJson](../../five/work/workJsonType.d.ts)
+
 `Work` 及其相关核心接口定义如下：
 
 ```ts
 import * as THREE from "three";
 import type { Mode } from "@realsee/five";
 
+type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
+
 /** Work 实体：VR 项目的根对象 */
 export interface Work {
   /** 唯一标识 (Work ID) */
@@ -72,6 +76,21 @@ export interface WorkObserver {
 
   /** 点位全景图资源信息 */
   images: WorkImage;
+
+  /** 获取点位的全局坐标 */
+  getWorldPosition(this: WorkObserver): THREE.Vector3;
+
+  /** 获取点位的全局地面坐标 */
+  getWorldStandingPosition(this: WorkObserver): THREE.Vector3;
+
+  /** 将方向向量转化为全景图 uv */
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  /** 将全景图 uv 转化为方向向量 */
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  /** 将方向向量转化为获六视图 uv */
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];
+  /** 将六视图 uv 转化为方向向量 */
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
 }
 
 /** 初始化位姿参数 */
@@ -113,8 +132,8 @@ export interface WorkModel {
 export interface WorkModelLayer {
   /** work */
   work: Work;
-  /** 模型类型 point_cloud mesh */
-  type: 'point_cloud' | 'mesh';
+  /** 模型类型 point_cloud mesh gaussian_splatting */
+  type: 'point_cloud' | 'mesh' | 'gaussian_splatting';
   /** 模型名称 */
   name: string;
   /** 指定上方向 */
@@ -140,6 +159,48 @@ export interface WorkImage {
 ### Work Entity (项目实体)
 Work 是 Five 渲染内容的基石。它不仅包含资源地址，还包含空间结构数据。由于数据通常带有数字签名（防止篡改），开发者**不应手动修改** Work 对象中的属性，尤其是资源路径和坐标数据。
 
+### Data Types (数据类型)
+Five 中有三种与 Work 相关的类型，它们分别对应不同的使用场景：
+
+*   **LooseWork (宽泛数据)**:
+    *   **来源**: 通常是服务端下发的原始 JSON 数据。
+    *   **特点**: 结构宽松，允许缺省值（如使用默认模态）、简写（如 URL 模板）和非标准类型（如数组表示向量）。
+    *   **用途**: 作为 `parseWork(json)` 的输入。
+*   **Work (运行时实体)**:
+    *   **来源**: 由 `parseWork` 解析生成。
+    *   **特点**: 结构严谨，数据已标准化（如 URL 已补全，向量转为 `THREE.Vector3`），且被冻结（不可变）。
+    *   **用途**: Five 内部渲染使用的核心对象，传给 `five.load(work)`。
+*   **WorkJson (标准序列化)**:
+    *   **来源**: 由 `workToJson(work)` 生成。
+    *   **特点**: 纯 JSON 结构，去除了运行时对象（如 THREE.Vector3），但保留了标准化的数据结构。
+    *   **用途**: 用于数据持久化存储或跨端传输。
+
+### Layers vs File (数据源关系)
+
+`WorkModel` 提供了两种定义模型数据的方式，其中 `layers` 是现代标准，`file` 主要用于兼容旧数据或简单场景。
+
+*   **`layers`**: (推荐) 数组结构，用于定义多层级、多类型的模型资源。
+    *   支持 **3DTiles** 格式的分块加载。
+    *   支持多种类型混合：`mesh` (模型), `point_cloud` (点云), `gaussian_splatting` (高斯泼溅)。
+    *   **默认行为**: 列表中的所有图层默认都会被加载并显示。
+*   **`file`**: (兼容) 字符串路径，用于定义单文件的 Mesh 模型。
+    *   仅支持部分格式（如 `.at3d`, `.obj`, `.glb`）。
+    *   不支持点云或高斯泼溅。
+
+**加载优先级与兼容逻辑 (Fallback)**:
+
+Five 在运行时会将 `file` 视为一个虚拟的 `mesh` 图层。加载逻辑如下：
+
+1.  **优先加载 Layers**:
+    Five 会遍历 `work.model.layers` 并加载其中定义的所有图层（包括 Mesh, PointCloud, GaussianSplatting 等）。
+
+2.  **File 的条件加载**:
+    检查当前已加载的图层中是否存在 `type: 'mesh'` 的图层。
+    *   **存在 Mesh 层**: 忽略 `work.model.file` 字段（认为 `layers` 已经提供了更高精度的模型）。
+    *   **不存在 Mesh 层**: 如果 `work.model.file` 有值，Five 会自动创建一个临时的 Mesh ViewLayer 来加载该文件。
+
+
+
 ### Observer (观察点)
 Observer 是 VR 空间中预设的观察位置。在 **Panorama (全景)** 模式下，相机必须停留在某个 Observer 上。
 *   **position**: 相机镜头的物理位置。
@@ -238,5 +299,5 @@ five.load(work3, "inherit", { mode: "replace" });
 ---
 
 ```yaml
-tags: [work, core, entity, observer]
+tags: [VR数据, 数据加载, 点位, 全景点, 数据结构, 多work, work, core, entity, observer, parseWork, workCode, JSON, load]
 ```

package/ai_guides/glossary.md

@@ -9,11 +9,15 @@
 SDK 的核心入口类。一个 `Five` 实例对应一个 `<canvas>` 渲染上下文，负责管理场景生命周期、渲染循环、用户交互和状态更新。
 
 ### Work
-VR 看房的**原始数据载体**。通常是一个 JSON 对象，包含了重建三维空间所需的所有信息，包括：
-- **Observers**: 全景拍摄点位信息。
-- **Panorama**: 全景图资源地址。
-- **Model**: 三维模型数据 (Mesh, Material)。
-- **Plan**: 户型图数据 (SVG, 标尺)。
+VR 看房的**运行时实体**。通常指经过 `parseWork` 解析后生成的标准化数据对象。
+- **LooseWork**: 服务端下发的原始 JSON 数据，结构较宽松。
+- **WorkJson**: `workToJson` 生成的标准序列化数据，用于存储。
+- **包含内容**: Observers, Panorama, Model, Plan 等。
+
+### Vertex Marks (顶点标记)
+在模型顶点上通过 `_feature_id_rsmask` 属性进行的标记。
+- 用于在特定视角（如俯视）下控制 Mesh 的显隐（例如隐藏天花板）。
+- 属于材质配置的一部分。
 
 ### Observer
 **观察点**。对应现实空间中拍摄全景图的一个物理位置。
@@ -48,12 +52,29 @@ Five 定义的五种浏览状态：
 ### Pano Tile (全景瓦片)
 为了在移动端快速加载高分辨率全景图（如 8K/16K），将全景图切分为多个小块（瓦片）。Five 会根据当前视角按需加载可见区域的瓦片。
 
-### Quasi / Mesh
+### Mesh (三维网格)
 **三维模型**。通过激光扫描或视觉算法重建的空间几何结构。在 Five 中，全景图贴在几何模型上，从而实现“从全景中看出立体感”的效果。
 
 ### G-Buffer / Geometry Buffer
 用于后处理的几何缓冲区，包含深度 (Depth)、法线 (Normal)、ID 等信息，用于实现高级特效（如轮廓线、SSAO）。
 
+### ViewLayer
+管理 `Model` 内部特定 3D 资源（如 Mesh、PointCloud、Gaussian Splatting）的图层。
+- 继承自 `Tile3D`。
+- 拥有独立的 `Parameter` 配置（覆盖上层配置）。
+- 支持可见性控制 (`visible`) 和优先级加载。
+
+### Gaussian Splatting
+一种基于点的 3D 渲染技术，通过各向异性高斯球（Splat）来表示场景。
+- 相比传统 Mesh，能更真实地还原复杂光照和细节。
+- Five 支持 `.spz` 和 `.splat` 格式的 Gaussian Splatting 渲染。
+
+### 3D Tiles Refinement (细化)
+3D Tiles 加载过程中的状态概念：
+- **Loaded (已加载)**: 瓦片的基本数据已下载并解析，满足最低显示要求 (`minLevelOfDetail`)。
+- **Refined (已细化)**: 瓦片已加载最高质量数据，满足当前视角的屏幕空间误差要求 (`maxScreenSpaceError`)。
+- `five.model.refineProgress` 可用于监控当前视角的细化进度。
+
 ## Interaction (交互)
 
 ### Raycast (射线检测)
@@ -68,5 +89,5 @@ Five 封装的手势事件：
 
 ---
 ```yaml
-tags: [glossary, terminology, definitions]
+tags: [术语, 概念, glossary, terminology, definitions, observer, pose, mode, work, panoindex, fov, viewlayer, gaussian-splatting, 3dtile]
 ```

package/ai_guides/intro.md

@@ -8,7 +8,7 @@
 
 *   **全景浏览**: 支持高分辨率全景图的高效加载与平滑浏览。详见 [Pano Tile](./features/pano-tile.md)。
 *   **空间漫游**: 支持在三维模型中自由行走、跳转。详见 [Mode](./features/mode.md)。
-*   **模型渲染**: 内置高效的模型加载策略 (3DTile)。详见 [Model](./features/model.md)。
+*   **模型渲染**: 内置高效的模型加载策略 (3DTile) 与灵活的材质配置。详见 [Model](./features/model.md) 与 [Material](./features/material.md)。
 *   **交互事件**: 完善的事件系统，支持手势、射线检测等。详见 [Event](./features/event.md) 与 [Raycast](./features/raycast.md)。
 *   **状态管理**: 统一的 State 设计，便于状态保存与还原。详见 [State](./features/state.md)。
 

package/ai_guides/quick-start.md

@@ -60,6 +60,7 @@ fetch(workURL)
 *   **控制视角与移动**: 了解如何通过代码控制相机。 -> [Five.updateCamera](./features/five.md) / [State](./features/state.md)
 *   **切换模态**: 在全景、模型、平面图之间切换。 -> [Mode](./features/mode.md)
 *   **监听事件**: 响应用户的点击和交互。 -> [Event](./features/event.md)
+*   **视觉调整**: 修改材质参数或开启后处理效果。 -> [Material](./features/material.md) / [Postprocessing](./features/postprocessing.md)
 *   **自定义配置**: 修改图片加载参数或渲染效果。 -> [ImageOptions](./features/image-options.md)
 
 ## Related