Cesium POI点聚合实战：EntityCluster配置、避坑与海量性能优化

简介面向Cesium三维GIS开发者的POI点聚合代码示例重点解决Cesium原生primitive不支持点聚合的局限。该方案借助DistanceDisplayCondition属性根据POI的typename字段层级关系动态返回视距范围如“汽车服务加油站加油站”对应最远视距“汽车服务加油站”对应中视距“汽车服务”对应最近视距从而在_clustering方法中计算显示距离并在_add方法中应用条件最终实现远、中、近视距下的POI分级显示。压缩包内含1个HTML演示页面与1个inscode项目文件整体大小仅4KB目前已有78人学习下载。通过这份代码开发者可以快速掌握基于视距条件实现聚合的思路无需修改Cesium内部源码即可集成进现有项目相较修改EntityCluster.js的传统方案更轻量、易维护。代码结构清晰适合需要高效渲染海量POI数据的WebGIS场景可灵活调整视距参数以适配不同业务层级有效缓解高密度POI渲染时的视觉拥挤提升地图交互流畅度。1. Cesium POI 点聚合是干什么的从满屏图标到一眼看懂密度把 1 万个 POI 一次性丢进 Cesium俯视状态下你看到的不是地图而是一团黑色马赛克——图标互相压叠帧率掉到个位数用户根本看不出哪里密哪里稀。Cesium POI 点聚合解决的就是这个问题按照屏幕像素距离把靠近的 POI 合并成一个聚合节点节点上显示数量视角拉近后节点自动拆回单个 POI。这套机制对门店分布、安防点位、设备台账这类以密度展示为主的应用几乎是标配。下面从 Cesium 内置的 EntityCluster 讲起给一段能直接跑通的最小代码再把我踩过的 5 个坑和十万级 POI 的调优路径一次讲透。2. 聚合原理与方案选型EntityCluster 和自研格网怎么选2.1 EntityCluster 的工作机制Cesium 的聚合能力不是单独一个插件而是挂在 DataSource 上的一个属性任何 DataSource 子类都有 clustering 对象CustomDataSource、GeoJsonDataSource、CzmlDataSource 一视同仁。你往数据源里 add 实体Cesium 会在相机变化后把这些实体的世界坐标投影到屏幕再以像素距离为尺子做合并两个图标在屏幕上的距离小于 pixelRange就会被归到同一个聚合组。聚合组不是一个抽象概念它在场景里是一个真正的 Entity位置是成员实体位置的加权中心。所以你能像操作普通实体一样给它设置 billboard、label、point甚至 ellipse。相机移动时聚合组会实时分裂和重组这个变化通过 clustering.clusterEvent 事件对外通知事件的回调参数是 (clusteredEntities, cluster)前者是聚合组里的实体数组后者是聚合节点实体本身。理解两个关键点对调参很重要。第一聚合发生在屏幕空间而不是地理空间同样一批 POI500 米高空视角是散的20 公里高空视角就合并了因为投影后的像素距离变了。第二聚合节点是复用对象不是在每个事件里新建你的 clusterEvent 回调只是改变它的外观搞反了这个方向就会写出性能很差的代码后面避坑章专门讲。2.2 选型依据内置聚合和自研聚合的边界在哪自己写聚合方案最常见的是格网聚合把经纬度按固定单元格切分一个单元格内的 POI 合并成一个聚合点。这个方案和 EntityCluster 不是替代关系而是互补关系。我遇到的大多数项目第一阶段用内置 EntityCluster 就够第二阶段才被数据量逼着做格网。对比项内置 EntityCluster自研格网聚合实现成本配置属性即可零合并逻辑需要自己分桶、合并、更新样式动态性随相机实时拆散/合并固定单元格缩放到一定程度要重建实体数量上限5000 以内流畅5 万开始吃力配合预聚合可以撑到几十万交互区分需要自己标记聚合节点和普通 POI聚合点自带 cellKey容易回溯成员地图语义聚合范围跟屏幕密度走符合直觉聚合范围跟地理格子走边界偏生硬我的取舍标准是这样POI 数量小于 5000无脑用内置 EntityCluster5000 到 5 万内置加性能优化重点是减少实体数量和层级切换超过 5 万用格网预聚合把实体数量砍到几千再交给 EntityCluster。注意这是递进关系不是二选一第 5 章的调优还会回到这个组合。2.3 数据准备POI 数据入库前的清洗与字段约定聚合对脏数据的容忍度比普通标注高但脏数据会让聚合数量失真。我一般在进入 Cesium 前做三道清洗。第一道查坐标合法性lng 在 -180 到 180lat 在 -90 到 90纯数字、非 NaN能滤掉接口返回 0 和空字符串的坏数据。第二道去重同一经纬度加上同一 name 的记录只保留一条重复 POI 会让聚合数虚高用户放大后看到两个一模一样的图标也会觉得是 bug。第三道约定字段id、lng、lat、name、type 必须有type 是业务分类后面按字段分组聚合和图标配色都要用它。function cleanPoi(rawList) { const seen new Set(); return rawList.filter(p { if (!Number.isFinite(p.lng) || !Number.isFinite(p.lat)) return false; if (p.lng -180 || p.lng 180 || p.lat -90 || p.lat 90) return false; const key ${p.lng.toFixed(6)},${p.lat.toFixed(6)},${p.name}; if (seen.has(key)) return false; seen.add(key); return true; }); }这段代码在数据源创建之前执行把 rawList 清洗成合法数组。Number.isFinite 比 typeof 判断更严格能过滤掉 NaN 和 Infinity。toFixed(6) 是去重的关键经纬度保留 6 位小数约等于 0.1 米精度同一个点位重复上报基本能命中。清洗之后数据量如果还是超过 5 万先别急着连 Cesium跳到第 5 章看格网预聚合。3. 用 EntityCluster 跑通 POI 聚合最小代码与参数说明3.1 最小可运行代码创建数据源、开聚合、加 POI下面这段是把聚合跑起来的最小骨架把坐标数组换成你的真实数据就能用。const viewer new Cesium.Viewer(cesiumContainer); const poiSource new Cesium.CustomDataSource(poi-layer); viewer.dataSources.add(poiSource); // 开启数据源的聚合能力 poiSource.clustering.enabled true; poiSource.clustering.pixelRange 50; // 屏幕像素半径 poiSource.clustering.minimumClusterSize 2; // 至少 2 个 POI 才聚合 poiSource.clustering.clusterBillboards true; // billboard 图元参与聚合 poiSource.clustering.clusterPoints true; // point 图元参与聚合 // 模拟 200 个 POI坐标随机偏移 const mockPoi []; for (let i 0; i 200; i) { mockPoi.push({ lng: 116.39 (Math.random() - 0.5) * 0.2, lat: 39.9 (Math.random() - 0.5) * 0.2, name: POI_${i}, type: i % 3 0 ? hospital : i % 3 1 ? school : shop }); } mockPoi.forEach(p { poiSource.entities.add({ position: Cesium.Cartesian3.fromDegrees(p.lng, p.lat), billboard: { image: /assets/img/poi_marker.png, width: 28, height: 28, verticalOrigin: Cesium.VerticalOrigin.BOTTOM }, properties: { poiName: p.name, poiType: p.type } }); });注意clustering 是数据源级别的配置换数据源要重新设置不会跟着实体迁移。这段代码的核心是把聚合配置和数据添加彻底分离clustering 只管开关实体只管加Cesium 自动完成合并判定。pixelRange 是屏幕像素半径两个 POI 投影后距离小于 50 像素就会进同一个聚合组值越大聚合越激进城市全景下 50 到 80 是常用区间。minimumClusterSize 设成 2 表示两个 POI 也得聚设成 5 可以让孤立 POI 保持散点避免出现一个聚合节点只包两三个点的尴尬。clusterBillboards 和 clusterPoints 分别控制 billboard 和 point 两类图元是否参与聚合混用图元时哪个开关没打开那一类图元就不会被聚合。3.2 在 clusterEvent 中定制聚合节点样式聚合开启后的默认节点是个蓝色圆点不显示数量看不出密度。定制样式要在 clusterEvent 里做这是聚合方案里最核心的回调。poiSource.clustering.clusterEvent.addEventListener((clusteredEntities, cluster) { const count clusteredEntities.length; cluster.billboard { image: /assets/img/cluster_marker.png, width: 46, height: 46, verticalOrigin: Cesium.VerticalOrigin.CENTER, disableDepthTestDistance: 2000 }; cluster.label { text: count 99 ? 99 : String(count), font: bold 14px Arial, fillColor: Cesium.Color.WHITE, pixelOffset: new Cesium.Cartesian2(0, -18), showBackground: true, backgroundColor: new Cesium.Color(0, 0, 0, 0.45) }; });回调参数是固定的clusteredEntities 是聚合组内的实体数组cluster 是聚合节点实体。回调做的事其实就是给 cluster 设置外观Cesium 负责把它的位置放到成员中心。count 超过 99 显示 99避免三位数字把图标撑爆。disableDepthTestDistance 设成 2000表示 2000 米观察距离内聚合图标不被地形和建筑遮挡这个是经验值第 4 章展开讲。一个性能提醒这个回调在相机移动时会被高频触发回调里尽量只做属性赋值不要 new Image、不要发请求、不要做复杂遍历。如果聚合成员的数组需要保存slice 一份存到 Map 里别直接持引用原因后面讲。3.3 点击聚合节点与普通 POI 的区分聚合节点也是 Entity点击拾取能拿到它但拿到的对象和普通 POI 没有天然区别需要自己标记。我的做法是维护一个 Map把 cluster 实体映射到它的成员列表。const clusterMap new Map(); poiSource.clustering.clusterEvent.addEventListener((clusteredEntities, cluster) { clusterMap.set(cluster, clusteredEntities.slice()); // 样式设置代码同上一节省略 }); const handler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); handler.setInputAction(movement { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || !Cesium.defined(picked.id)) return; const members clusterMap.get(picked.id); if (members) { // 点到聚合节点飞行到该区域并放大 const carto Cesium.Cartographic.fromCartesian( picked.id.position.getValue(Cesium.JulianDate.now()) ); viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees( Cesium.Math.toDegrees(carto.longitude), Cesium.Math.toDegrees(carto.latitude), viewer.camera.positionCartographic.height * 0.4 ) }); } else { // 点到普通 POI这里做弹窗或高亮 const name picked.id.properties.poiName.getValue(undefined); console.log(POI clicked:, name); } }, Cesium.ScreenSpaceEventType.LEFT_CLICK);scene.pick 返回的对象带 id 属性对实体图元来说 id 就是 Entity。clusterMap.get(picked.id) 命中就说明点击的是聚合节点否则是普通 POI。飞行高度用当前相机高度的 40%一次点击大约放大 2.5 倍两三次点击能把聚合完全拆开。注意 properties 里的值要 getValue(undefined) 取出这是 Cesium Property 体系的标准用法直接用 picked.id.properties.poiName 拿到的是属性对象而不是原始值。4. 聚合避坑手册5 个高频翻车点与排查路径4.1 聚合图标点不中点击事件总落空现象聚合节点显示正常但鼠标点上去没反应用 drillPick 却发现点到了别的实体。原因最常见的是 label 的像素尺寸大于 billboardpick 射线最先命中 label 或它的背景板命中区域落在 label 边缘时某些 Cesium 版本里 picked 会是 undefined。其次是聚合节点没有显式设置 width 和 height命中区域只有图标本身那么小。解决给 cluster.label 设置向左或向右的 pixelOffset让文字离开图标主体把 billboard 的 width 和 height 放大到 48 像素以上扩大命中区域。拾取需求复杂的项目直接用 viewer.scene.drillPick 替代 pick它返回按深度排序的命中数组遍历找第一个带 id 的对象能绕开大部分层级遮挡问题。4.2 缩放过程中聚合图标闪烁像灯坏了一样现象连续缩放时聚合节点一闪一闪或者相机没怎么动聚合节点在聚合和拆分两个状态之间反复横跳。原因两个层面。第一clusterEvent 在相机停止移动前会高频触发回调里如果每次创建新样式对象或操作 DOM浏览器 GC 一介入就是肉眼可见的卡顿和闪烁。第二聚合判定本身有像素阈值相机缓慢移动时部分 POI 恰好处于 pixelRange 边界一会儿并一会儿拆这是临界抖动无法完全消除只能缓解。解决clusterEvent 回调里只做赋值图标图片在页面初始化时就加载成 Image 对象再传入不要在回调里 new。对临界抖动把 minimumClusterSize 提到 3 以上让边界上的单点 POI 不参与聚合抖动会明显减少。老版本 Cesium 上还可以给 clusterEvent 做 200 毫秒节流用 requestAnimationFrame 包一层虽然不算优雅但确实有效。4.3 POI 一多帧率就崩5 万条直接变幻灯片现象实体数量超过 5 万相机一移动帧率掉到个位数CPU 占用拉满。原因EntityCluster 的聚合判定需要把每个实体投影到屏幕再算距离这是 O(n) 遍历5 万实体的遍历不至于要命真正要命的是 5 万个 billboard 实体的渲染开销——每个实体一次独立 draw call加上聚合过程要频繁重算成员关系双重压力下帧率必然崩。实体数量是主要瓶颈不是聚合算法本身。解决两条路同时走。第一用第 5 章的格网预聚合把 5 万砍到 5000。第二让非聚合层走 Primitive 体系把 billboard 实体换成 PointPrimitiveCollectiondraw call 从 5 万降到个位数。这里补一句血泪经验别指望只调 pixelRange 扛性能聚合计算量反而会变大正确顺序永远是先减实体、再调渲染。4.4 聚合节点被地形和高楼压住看不见现象项目加了 3D 地形后山体背面的聚合节点完全看不见城市里的聚合节点被高层模型挡住。原因聚合节点的位置是成员地理坐标的加权平均这个平均点可能落在起伏地形之下也可能落在楼模背后。默认情况下 billboard 的深度测试是开启的聚合节点被遮挡是正确渲染行为但在地图业务里通常不是你要的效果。解决在 clusterEvent 里给聚合节点 billboard 设置 disableDepthTestDistance用有限值比无限大合理。我的习惯是 2000意思是 2000 米观察距离内聚合图标永远在最上层拉远后回归深度测试保留山体遮挡的立体感。也可以把 heightReference 设为 CLAMP_TO_GROUND 让节点贴地但地形起伏大的区域贴地后节点可能和成员 POI 有肉眼可见的错位。这个问题属于地图玄学里典型的取舍没有标准答案。4.5 清除数据后聚合图标残留Map 引用泄漏现象调用 poiSource.entities.removeAll() 清掉数据地图上聚合节点还在或者重构图层后旧聚合样式跑到新图层上。原因正常情况下 removeAll 会触发聚合重算把聚合节点一并移除。残留通常出现在两个地方——一是 clusterMap 还持有 cluster 实体引用Map 不清、引用不释放打开内存面板能看到实体对象只增不减二是切换图层时 new 了新数据源但 clusterEvent 回调还挂在旧数据源上旧聚合节点的样式被新数据源的聚合事件重复触发看起来像幽灵图标。解决清除数据按固定顺序操作先 poiSource.clustering.enabled false 暂停聚合再 entities.removeAll()最后 clusterMap.clear()。切换图层时直接 viewer.dataSources.remove(poiSource)不要复用同一个数据源实例装不同业务数据。排查这类问题最快的路径是打开浏览器内存面板做一次 heap snapshot对比清数据前后的对象数量能精确看出引用没释放的位置。5. 海量 POI 性能调优从实体聚合升级到格网聚合5.1 分层显示远景聚合、近景明细的切换时机数据量大的项目第一步不是优化渲染而是想清楚什么时候给用户看什么。我的做法是分层相机高度大于 3 公里显示聚合层小于 3 公里显示明细层。聚合层用格网预聚合后的点位数量控制在几千明细层用原始 POI只渲染当前视野范围。// aggregateLayer 和 detailLayer 是事先创建好的两个 CustomDataSource const LAYER_SWITCH_HEIGHT 3000; // 米 viewer.camera.changed.addEventListener(() { const height viewer.camera.positionCartographic.height; aggregateLayer.show height LAYER_SWITCH_HEIGHT; detailLayer.show height LAYER_SWITCH_HEIGHT; });camera.changed 在相机参数变化时触发这里只看高度简单可靠。这个事件触发很频繁回调里只做 show/hide不要做其他计算。为了消除切换瞬间的空白帧我习惯让切换高度有重叠区间——聚合层到 2500 米才隐藏明细层在 3000 米就显示中间两层共存视觉上无缝。本质是 LOD 思想只是把模型 LOD 搬到了 POI 数据上。5.2 格网预聚合按经纬度分桶生成聚合点格网预聚合的核心是把地理空间切成单元格一个单元格的 POI 合成一个点。单元格大小跟相机高度挂钩高度越高格子越大。function buildGridAggregates(pois, cellDeg) { const buckets new Map(); for (const p of pois) { const cellX Math.floor(p.lng / cellDeg); const cellY Math.floor(p.lat / cellDeg); const key ${cellX},${cellY}; if (!buckets.has(key)) buckets.set(key, []); buckets.get(key).push(p); } const result []; buckets.forEach(list { let sumLng 0, sumLat 0; list.forEach(p { sumLng p.lng; sumLat p.lat; }); result.push({ lng: sumLng / list.length, lat: sumLat / list.length, count: list.length, items: list }); }); return result; }提示cellDeg 要随相机高度动态调整别写死否则缩放到大范围时聚合点过密、放大时又过稀。输入是清洗后的 POI 数组和单元格大小输出是聚合点数组。cellDeg 单位是度纬度上 1 度约等于 111 公里要做到几百米聚合粒度cellDeg 在 0.01 到 0.005 量级。我用过一个经验公式cellDeg cameraHeight / 400000相机高度 10 公里时算出 0.025 度大概对应 2.7 公里一格可以当起始值再微调。分桶用 Map 而不是对象是因为拼接 key 在 Map 里哈希查找更快几万条数据差异不大但这是习惯。聚合点生成后装进单独的 CustomDataSource每个点带 count 属性用 clusterEvent 显示数量。注意这时候的聚合点是地理格子级别的固定节点不会随相机自行拆分所以要么把该数据源的 clustering.enabled 设为 false要么把 pixelRange 设得极大让它永不合并。5.3 图标合并与渲染开销控制实体数量降下来后draw call 优化也不可忽视。一个 billboard 一个 draw call几千个聚合点就是几千次调用图集是标准解法。把 POI 分类图标合成到一张 PNG用 imageSubRegion 切出子图标。// 假设 atlas 是 4x4 的图标网格每个 32x32 const ATLAS_GRID 4; const ICON_SIZE 32; function iconRegion(index) { const col index % ATLAS_GRID; const row Math.floor(index / ATLAS_GRID); return new Cesium.BoundingRectangle(col * ICON_SIZE, row * ICON_SIZE, ICON_SIZE, ICON_SIZE); } // 添加聚合点时 dataSource.entities.add({ position: Cesium.Cartesian3.fromDegrees(agg.lng, agg.lat), billboard: { image: /assets/img/poi_atlas.png, imageSubRegion: iconRegion(agg.typeIndex), width: 32, height: 32 } });imageSubRegion 让 Cesium 只取图集里对应的小块多次 draw call 变成一次纹理绑定。合成图集时每个子图标四周留 2 像素透明边距避免线性过滤采样串色这是图集方案最容易翻车的细节。渲染开销控制到这一步配合 5000 聚合点上限二十万级 POI 的全景浏览基本能稳定在 40 帧以上。6. 聚合进阶按字段分组、飞行钻取与正确性验证6.1 按业务字段分组聚合让颜色会说话聚合不只是合并数量还能带业务语义。在 clusterEvent 里统计成员实体的 type 占比取最高的类型给聚合节点染色。poiSource.clustering.clusterEvent.addEventListener((clusteredEntities, cluster) { const typeCount {}; clusteredEntities.forEach(e { const t e.properties.poiType.getValue(undefined); typeCount[t] (typeCount[t] || 0) 1; }); const mainType Object.entries(typeCount).sort((a, b) b[1] - a[1])[0][0]; cluster.billboard { image: /assets/img/cluster_marker.png, width: 46, height: 46, color: colorMap[mainType] || Cesium.Color.GRAY }; cluster.label { text: String(clusteredEntities.length), font: bold 14px Arial }; });一个前提给 billboard 染色要求贴图是白色或浅色底color 是乘法运算深色贴图染出来会发黑。素材统一用灰度底图颜色全部交给代码控制这是我被配色坑过之后固定下来的习惯。6.2 点击聚合后飞行展开高度节奏拆开聚合的条件是成员间屏幕距离超过 pixelRange。相机高度减半地面距离在屏幕上约放大一倍所以点击聚合节点后飞到当前高度的 40%一次点击就能让聚合组裂成两三个小组两三次点击完全拆开。这个渐进节奏比一步到位更符合空间认知用户能看到聚合逐步裂开、密度区域逐步显现的过程。6.3 验证聚合正确性的三个检查点上线前固定检查三件事。数量守恒全图缩小后所有聚合 count 加散点总数等于 POI 总数。等价拆解任意聚合节点放大后拆出的 POI和原始数据在该范围内的记录一致。状态一致同一视角反复进出聚合结果稳定不稳定多半是 clusterEvent 里混入了异步操作。聚合的事做完别急着上线先跑一遍这三项检查。这些年我的习惯是先用内置聚合到线上跑量顶不住再换格网一上来就自研聚合的返工成本远高于想象。希望帮到你。本文还有配套的精品资源点击获取