# ViewLayer (视图层)

- Summary: ViewLayer 是 Model 的组成部分，负责管理具体的 3D 资源（如 Mesh 或 PointCloud），支持独立的渲染配置和可见性控制。
- Schema: 继承自 `Tile3D`，由 `Model` 统一管理。
- Concepts: Layer Fallback, 3DTile Integration, Parameter Inheritance.
- Examples: 可见性控制、参数配置、事件监听。

## Schema

> Definition: ViewLayer, ViewLayerInit

ViewLayer 是一个具体的渲染图层，它对应一个具体的 3D 数据源（通常是一个 `.gltf` / `.b3dm` / `.pnts` 等 Tileset 入口）。

    // 简化定义
    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)

    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 和 3DTile Params。

## Examples

### 1. 访问 ViewLayer

    // 获取当前模型
    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. 独立控制图层可见性

    // 方式 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. 修改特定图层的渲染参数

    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: ViewLayer 的父级容器。
- Work: 定义 ViewLayer 数据结构的数据源。
- Parameter: 控制 ViewLayer 渲染表现的配置系统。
- 3DTile: ViewLayer 的底层技术实现。

    tags: [图层, 视图层, 可见性, 显隐控制, 图层切换, 分层渲染, viewlayer, model, 3dtile, parameter, layer, mesh, point-cloud, gaussian-splatting]