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;
}
Copy

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)]
Copy

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');
Copy

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 等其他层
    }
  }
});
Copy

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);
}
Copy

Related

• Model: ViewLayer 的父级容器。
• Work: 定义 ViewLayer 数据结构的数据源。
• Parameter: 控制 ViewLayer 渲染表现的配置系统。
• 3DTile: ViewLayer 的底层技术实现。

---

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