SuperMap iClient3D for WebGL实战：两种模型属性查询方法详解（附完整代码）

SuperMap iClient3D for WebGL实战：两种模型属性查询方法详解（附完整代码）

在三维GIS开发中，模型属性查询是最基础也最核心的功能之一。想象这样一个场景：当用户点击屏幕上的一座建筑模型，系统需要立即展示该建筑的详细属性信息——可能是楼层高度、竣工年份，或者是当前入驻企业的数据。这种交互体验直接影响着三维应用的实用性和专业度。

SuperMap iClient3D for WebGL提供了两种截然不同的技术路径来实现这一功能：基于数据服务的动态查询和基于模型缓存的本地化查询。选择哪种方案，往往取决于项目的数据特点、性能需求和实施阶段。本文将深入剖析这两种方法的实现原理、代码差异和适用边界，并通过完整可运行的代码示例，带你掌握三维属性查询的核心技术要点。

1. 技术选型：理解两种查询机制的本质差异

1.1 数据服务查询的工作原理

数据服务查询（FeatureService）是一种典型的"请求-响应"模式。当用户点击场景中的模型时，前端会向服务器发起一个空间查询请求，服务器实时计算后返回对应的属性数据。这种方式的典型工作流程是：

1. 用户点击三维场景中的模型
2. 前端获取点击位置的屏幕坐标
3. 将屏幕坐标转换为场景中的三维坐标
4. 构造空间查询参数并发起AJAX请求
5. 服务器执行空间查询并返回JSON格式的属性数据
6. 前端解析并展示查询结果

// 典型的数据服务查询URL结构 const queryUrl = "http://{server}:{port}/iserver/services/data-{datasource}/rest/data/featureResults.rjson";

这种方案最大的优势是实时性——属性数据永远与数据库保持同步，适合需要频繁更新属性的场景。但缺点也很明显：每次查询都需要网络请求，在弱网环境下体验较差。

1.2 模型缓存查询的内在机制

模型缓存查询则采用了完全不同的思路。在生成三维模型缓存时，属性数据会以二进制形式直接嵌入到模型文件中（通常是S3MB格式）。这种"预烘焙"的方式带来几个显著特点：

• 属性数据与模型几何数据一起加载到显存
• 查询完全在本地完成，无需网络请求
• 查询速度稳定，不受服务器负载影响
• 但属性更新需要重新生成模型缓存

重要提示：使用缓存属性查询前，必须确保生成缓存时勾选了"存储模型属性"选项。这个设置在SuperMap iDesktop的"生成场景缓存"对话框的高级选项中。

2. 数据服务查询的完整实现

2.1 基础环境配置

首先确保你的开发环境包含以下要素：

• SuperMap iServer基础服务（版本建议10.2.1以上）
• 已发布的三维数据服务
• 支持WebGL的现代浏览器
• 基本的JavaScript开发环境

关键依赖库：

<script src="libs/Cesium.js"></script> <script src="libs/supermap/SuperMap.Include.js"></script>

2.2 核心代码实现

完整的实现代码可以分为四个逻辑部分：

1. 场景初始化
2. 点击事件绑定
3. 空间查询构造
4. 结果展示处理

// 初始化Viewer const viewer = new Cesium.Viewer('cesiumContainer', { scene3DOnly: true, baseLayerPicker: false }); // 加载场景 const scene = viewer.scene; const promise = scene.open('http://{server}:{port}/iserver/services/3D-{scene}/rest/realspace'); // 点击事件处理 const handler = new Cesium.ScreenSpaceEventHandler(scene.canvas); handler.setInputAction(function(movement) { const pick = scene.pick(movement.position); if (!pick || !pick.id) return; // 构造查询参数 const queryParam = new SuperMap.GetFeaturesByGeometryParameters({ datasetNames: ["Building:Buildings"], geometry: pick.id.position, spatialQueryMode: SuperMap.SpatialQueryMode.CONTAIN }); // 执行查询 new SuperMap.FeatureService(queryUrl).getFeaturesByGeometry(queryParam, function(serviceResult) { if (serviceResult.result && serviceResult.result.features) { displayProperties(serviceResult.result.features[0]); } }); }, Cesium.ScreenSpaceEventType.LEFT_CLICK); // 结果显示函数 function displayProperties(feature) { const attributes = feature.properties; let html = '<table class="property-table">'; for (const key in attributes) { html += `<tr><td>${key}</td><td>${attributes[key]}</td></tr>`; } document.getElementById('propertyPanel').innerHTML = html; }

2.3 性能优化技巧

在实际项目中，我们总结了几条提升数据服务查询效率的经验：

• 空间查询模式选择：

  • CONTAIN：完全包含（精度高但性能差）
  • INTERSECT：相交查询（平衡精度与性能）
  • DISJOINT：不相交查询（特殊场景使用）

• 查询范围控制：

  • 为点击位置添加缓冲半径，避免点查询的精度问题
  • 设置合理的超时时间（建议3-5秒）

• 数据预处理：

  • 为常用查询字段建立空间索引
  • 对大表进行水平分片

3. 模型缓存查询的实战指南

3.1 缓存准备关键步骤

使用缓存属性查询前，必须确保模型缓存包含属性信息。在iDesktop中操作时：

1. 右键点击场景选择"生成场景缓存"
2. 在"缓存类型"中选择"S3MB"
3. 点击"高级设置"按钮
4. 勾选"存储模型属性"选项
5. 设置适当的LOD级别（影响属性存储量）

3.2 前端代码实现

缓存查询的实现相对简洁，因为所有逻辑都在本地完成：

// 场景加载与点击事件绑定 viewer = new Cesium.Viewer('cesiumContainer'); const scene = viewer.scene; scene.open('http://{server}:{port}/iserver/services/3D-{scene}/rest/realspace'); // 点击查询处理 viewer.screenSpaceEventHandler.setInputAction(function(movement) { const feature = viewer.scene.pick(movement.position); if (feature && feature.properties) { showProperties(feature.properties); } }, Cesium.ScreenSpaceEventType.LEFT_CLICK); // 属性展示函数 function showProperties(properties) { const panel = document.getElementById('propertyPanel'); panel.innerHTML = ''; // 使用异步迭代避免UI阻塞 properties.forEachProperty(function(key, value) { const row = document.createElement('div'); row.className = 'property-row'; row.innerHTML = `<span class="prop-key">${key}</span>: <span class="prop-value">${value}</span>`; panel.appendChild(row); }); }

3.3 缓存查询的性能特点

通过实际项目测试，我们得到以下性能数据（测试环境：Chrome浏览器，i7-10700K CPU，RTX 3070 GPU）：

注意：缓存属性查询的内存占用与模型复杂度直接相关。对于超大规模场景（如整个城市级别的建筑），建议按区域动态加载模型。

4. 技术方案选型决策树

在实际项目中选择哪种技术方案，需要综合考虑多个维度因素。我们设计了一个简单的决策流程图：

1. 属性更新频率：

   • 需要实时更新 → 选择数据服务查询
   • 属性基本不变 → 考虑缓存查询

2. 模型复杂度：

   • 简单模型（<1000个对象）→ 两种方案均可
   • 复杂模型 → 优先缓存查询

3. 网络环境：

   • 稳定高速网络 → 数据服务查询更灵活
   • 弱网环境 → 必须使用缓存查询

4. 开发阶段：

   • 原型开发阶段 → 数据服务查询更易调试
   • 生产环境部署 → 缓存查询性能更优

对于大多数智慧城市类项目，我们的经验是采用混合方案：基础属性使用缓存查询保证性能，动态业务属性通过数据服务实时获取。这种架构既保证了交互流畅性，又能满足业务数据实时性的要求。

5. 常见问题与解决方案

5.1 数据服务查询无返回

典型现象：点击模型后控制台显示查询成功，但结果集为空。

排查步骤：

1. 检查数据集名称是否匹配（区分大小写）
2. 验证空间参考系统是否一致
3. 确认查询几何是否有效（特别是高度值）
4. 在iServer管理界面直接测试服务

5.2 缓存属性显示为undefined

可能原因：

• 生成缓存时未勾选"存储模型属性"选项
• 模型LOD级别设置过高导致属性丢失
• 前端代码中未正确处理异步属性加载

解决方案：

// 正确的属性访问方式 feature.properties.then(function(props) { // 在这里处理属性 });

5.3 性能优化实战技巧

对于超大规模场景，我们推荐几个经过验证的优化手段：

• 按需加载属性：

  // 只在需要时加载完整属性 if (feature.isPropertyLoaded) { showProperties(feature.properties); } else { feature.loadProperties().then(function() { showProperties(feature.properties); }); }

• 属性缓存策略：

  • 对高频访问的模型属性实现本地缓存
  • 设置合理的缓存过期时间

• 查询结果复用：

  • 对同一模型的重复查询直接使用缓存结果
  • 实现最近查询结果的LRU缓存

在最近的一个智慧园区项目中，通过组合使用这些技巧，我们将属性查询的平均响应时间从最初的280ms降低到了45ms，用户体验得到显著提升。