@realsee/five 6.8.0-alpha.2 → 6.8.0-alpha.21

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]
+```

package/ai_guides/features/plugin.md

@@ -0,0 +1,210 @@
+# 插件系统 (Plugin System)
+
+- **Summary**: Five 插件系统基于 `BasePlugin` 命名空间构建，提供了一套标准化的状态管理、生命周期控制和事件通信机制。
+- **Schema**: 核心类型定义位于 `BasePlugin` 命名空间。
+- **Concepts**: BasePlugin, State, Lifecycle, Controller.
+- **Configuration**: 插件特定的参数配置。
+- **Examples**: 标准插件开发示例。
+
+## Schema
+
+> **Definition**: [BasePlugin](../../plugins/BasePlugin/index.d.ts)
+
+`BasePlugin` 是一个命名空间，包含 `Controller` (抽象基类), `State` (状态接口), `EventMap` (事件映射) 等核心定义。
+
+```typescript
+export namespace BasePlugin {
+  export interface State {
+    enabled: boolean
+    visible?: boolean
+    config?: unknown
+  }
+  export abstract class Controller<PluginState, PluginEventMap, PluginServerData, PluginData> {
+    public five: Five
+    public abstract state: PluginState
+    public hooks: Subscribe<PluginEventMap>
+    // ...
+  }
+}
+```
+
+## Concepts
+
+### Directory Structure (目录结构)
+
+一个标准的插件通常包含以下文件：
+
+```text
+PluginName/
+  ├── index.ts        # 插件入口，导出工厂函数和类型
+  ├── Controller.ts   # 插件控制器，核心逻辑实现
+  └── typing.ts       # 类型定义
+```
+
+### BasePlugin
+
+所有插件推荐继承 `BasePlugin.Controller`。它定义了规范的泛型接口：
+
+- `PluginState`: 插件状态类型，继承自 `BasePlugin.State`。
+- `PluginEventMap`: 插件事件类型，继承自 `BasePlugin.EventMap`。
+- `PluginServerData`: 服务端原始数据类型。
+- `PluginData`: 解析后的插件数据类型。
+
+### State (状态)
+
+插件的状态驱动其行为。`BasePlugin.State` 定义了最基本的状态：
+
+- `enabled`: 是否启用。
+- `visible`: UI 是否可见。
+- `config`: 配置项。
+
+### Lifecycle (生命周期)
+
+插件的主要生命周期方法：
+
+- **constructor**: 初始化配置和初始状态。
+- **load**: 加载和解析数据。
+- **enable**: 启用插件，注册事件监听，添加副作用。
+- **disable**: 禁用插件，移除事件监听，清理副作用。
+- **dispose**: 销毁插件，彻底清理资源。
+
+## Configuration
+
+### BasePlugin Configuration
+
+`BasePlugin` 控制器构造函数接受可选的配置对象：
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `staticPrefix` | `string` | `'//vr-image-4.realsee-cdn.cn'` | 静态资源前缀。 |
+| `i18n` | `(key: string) => string` | `undefined` | 国际化转换函数。 |
+
+## Examples
+
+### Plugin Development Walkthrough (插件开发指南)
+
+以创建一个 `MyPlugin` 为例。
+
+#### 1. 定义类型 (typing.ts)
+
+定义插件所需的参数、状态、数据和事件类型。
+
+```typescript
+import { BasePlugin } from '../BasePlugin'
+
+// 1. 定义参数
+export interface Params extends BasePlugin.Config {
+  initialState?: Partial<State>
+  config?: Config
+}
+
+// 2. 定义配置
+export interface Config {
+  color?: string
+}
+
+// 3. 定义状态 (继承 BasePlugin.State)
+export interface State extends BasePlugin.State {
+  activeId?: string
+}
+
+// 4. 定义数据类型
+export interface ServerData { /* 服务端数据结构 */ }
+export interface PluginData { /* 解析后的数据结构 */ }
+
+// 5. 定义事件 (继承 BasePlugin.EventMap)
+export interface EventMap extends BasePlugin.EventMap<State, PluginData> {
+  click: (id: string) => void
+}
+```
+
+#### 2. 实现控制器 (Controller.ts)
+
+继承 `BasePlugin.Controller` 并实现核心逻辑。
+
+```typescript
+import { Five } from '@realsee/five'
+import { BasePlugin } from '../BasePlugin'
+import * as MyPluginType from './typing'
+
+export class Controller extends BasePlugin.Controller<
+  MyPluginType.State,
+  MyPluginType.EventMap,
+  MyPluginType.ServerData,
+  MyPluginType.PluginData
+> {
+  public state: MyPluginType.State
+
+  constructor(five: Five, params?: MyPluginType.Params) {
+    super(five)
+    this.state = {
+      enabled: true,
+      visible: true,
+      ...params?.initialState
+    }
+    if (this.state.enabled) {
+      this._enable()
+    }
+  }
+
+  public async load(serverData: MyPluginType.ServerData) {
+    // 解析数据
+  }
+
+  public enable() {
+    if (this.state.enabled) return
+    this.state.enabled = true
+    this._enable()
+    this.hooks.emit('stateChange', { state: this.state, userAction: true })
+  }
+
+  public disable() {
+    if (!this.state.enabled) return
+    this.state.enabled = false
+    this._disable()
+    this.hooks.emit('stateChange', { state: this.state, userAction: true })
+  }
+
+  public dispose = () => {
+    this.disable()
+    this.hooks.emit('dispose')
+  }
+
+  private _enable() {
+    // five.scene.add(...)
+    // five.on('tap', this.onTap)
+  }
+
+  private _disable() {
+    // five.scene.remove(...)
+    // five.off('tap', this.onTap)
+  }
+}
+```
+
+#### 3. 导出插件 (index.ts)
+
+提供一个工厂函数。
+
+```typescript
+import { Five } from '@realsee/five'
+import { Controller } from './Controller'
+import * as MyPluginType from './typing'
+
+export const MyPlugin = (five: Five, params?: MyPluginType.Params) =>
+  new Controller(five, params)
+
+export type { MyPluginType, Controller as MyPluginController }
+```
+
+## Common Pitfalls (最佳实践)
+
+1. **状态驱动**: 始终通过修改 `state` 来驱动插件行为，而不是直接操作 DOM 或 3D 对象。
+2. **清理资源**: 在 `disable` 和 `dispose` 中务必清理所有事件监听和副作用，防止内存泄漏。
+3. **类型安全**: 充分利用 TypeScript 泛型，确保事件和状态的类型安全。
+
+---
+
+```yaml
+tags: [plugin, baseplugin, development, guide]
+```

package/{guides → 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,8 +246,11 @@ 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` 基类定义。
 
 ---
 

package/{guides → 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;
+  }
 }
 ```
 

package/{guides → ai_guides}/features/request-proxy.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
 ```typescript
 interface FiveInitArgs {
   /**

package/{guides → 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 {

package/{guides → ai_guides}/features/state.md

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [State](../../five/types/state.d.ts)
+
 **State** 类型定义如下（继承自 `Pose`）：
 
 ```ts

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]
+```