简介Cesium POI点聚合方法代码包面向三维GIS开发者用于解决primitive方式加载海量兴趣点时无法直接聚合显示的难题。压缩包总共包含2个文件一个HTML页面作为可运行示例一个inscode文件作为项目配置整体大小仅4KB代码量少结构清晰便于快速阅读与迁移。目前已有78位开发者学习下载。实现思路是依托POI点自带的分级类型字段按照“汽车服务加油站加油站”“汽车服务加油站”“汽车服务”等层级分别设定远、中、近三种显示距离通过聚类方法计算每个POI点的视距再以距离显示条件属性控制其在对应视距下显隐最终形成三级聚合效果。这种方法免去了修改Cesium内部聚合源码的麻烦兼容性与可维护性更佳适合处理大规模POI点数据的WebGIS项目参考复用尤其适合城市级三维场景。1. Cesium 里做 POI 聚合卡的不是数据量是绘制方式我之前做的一个城市 POI 展示 Demo初版直接把十万个点用viewer.entities.add全丢进去地图一转帧率掉到个位数CPU 占用飙满。后来把渲染换成 Primitive 批量绘制再配合网格聚合把十万个点先聚合成几百个聚合点同样数据量帧率稳定在 50 以上。Cesium POI 点聚合方法本质就是回答三件事怎么把海量 POI 合并成少量聚合点、怎么把聚合点高效画出来、以及缩放地图时怎么让聚合结果跟着视角变化。这篇文章会直接给出一套可复制的代码方案照着抄就能跑。适合正在做海量标注落图、城市 POI 展示、轨迹点或业务图层的人尤其适合那种数据量过万、用 Entity 已经明显掉帧的场景。2. 为什么 POI 聚合不能直接套用普通点聚合选型先说清楚2.1 从数据量反推渲染方案Entity 不是不能用是一万以上就吃紧Cesium 里点渲染有两条技术路线。第一条是 Entity API内部走 DataSourceDisplay 的更新机制每个点都是一个独立的 draw command 封装增删改还有事件派发CPU 开销随实体数量线性增长。第二条是 Primitive直接用底层 GeometryInstance 批量创建几何体一次提交GPU 绘制时一条调用画完所有实例。两者的差异在数据量敏感时特别明显。按我实际测过的数量级低于 5000 个点Entity 的开发效率和流畅度都很好代码几行就够样式也好控制。到了 1 万到 5 万拖拽视角时实体更新、可见性计算、拾取检测都压在 CPU 上帧率开始波动偶尔掉到 20 多。5 万以上基本不可交互切个图层都要等半秒。而 Primitive 的方式十万个点也能扛得住但代价是位置、颜色变化都要主动重建或更新 GPU 缓冲代码复杂度上来了。POI 聚合恰好卡在中间原始数据量大聚合后的结果量又很小。所以常见做法是聚合计算放前端做渲染用 Primitive两边优势都拿到。我一般会定一个原则数据量过万就放弃逐点 Entity 渲染这不是玄学是数据结构和绘制方式的差异决定的。做 POI 聚合之前先把这条选型路线定下来后面所有代码都围绕它展开。2.2 网格聚合还是 K-means两种思路的边界条件POI 聚合的算法选型常见有三类固定网格聚合、K-means 聚类、屏幕距离聚合。很多人一上来就想用 K-means理由是聚类形状更自然但实际落地时往往翻车。网格聚合是把经纬度平面按固定尺寸切成格子格子内的点合成一个聚合点。优点是速度快、结果可预测、实现就是一个字典循环单次遍历十万条数据在浏览器里也就几十毫秒。缺点是聚合边界是方格状视觉上会看出格网痕迹而且固定尺寸在不同缩放层级下需要主动调整。K-means 会让相近的 POI 自动形成任意形状的簇视觉确实更好但迭代计算耗时十万个点跑一遍通常几百毫秒到几秒而且结果受初始中心点影响每次执行可能不完全一样不适合地图交互过程中的反复计算。屏幕距离聚合是把“屏幕上距离小于 N 像素”的点合并效果最接近视觉预期但需要把每个 POI 转成屏幕坐标再求距离数据量大时要么 O(n²) 要么上空间索引项目里很少有人自己从零实现。对 POI 落图这个场景我通常直接选网格聚合原因有三点POI 坐标是经纬度切网格用浮点取整就能完成性能开销最小网格尺寸可以直接和相机高度挂钩聚合数量可预估方便调配渲染资源实现代码简单后面接 WebWorker、接点选展开都很容易。K-means 更适合做专题聚类分析比如找商圈、找热点区域不适合做渲染前的聚合预处理。2.3 后端聚合不推荐作为唯一方案为什么前端聚合更常用还有一种常见做法是后端提前把 POI 聚合成聚合点下发前端只负责画。优点是前端计算压力小缺点也很明显聚合粒度固定地图一缩放聚合结果跟不上视角变化必须重新请求接口一次请求几百毫秒轮子还没转完用户已经缩放到下一级了。如果数据是静态的、更新频率很低后端聚合还能接受如果是实时数据或者需要和地图缩放联动的场景前端聚合几乎是唯一选择。3. 用经纬度网格完成 POI 聚合核心代码与逻辑说明3.1 数据清洗与坐标预计算聚合前的三个必要步骤从接口或文件拿到的 POI 数据通常不干净直接喂进聚合算法会出现重复点、越界坐标、字段丢失一类问题。聚合前我习惯先做三步清洗。第一步校验字段保证 lng、lat 是可用的 Number 类型name 是字符串。第二步去重按经纬度和名称拼 key用 Set 过滤。注意浮点精度问题116.0 和 116.0000001 在业务上可能是同一点但字符串不同所以先统一保留 6 位小数再拼 key。第三步算一遍包围盒后面调试聚合效果和检查网格尺寸时都用得上。function cleanPOIs(rawList) { const seen new Set(); const out []; for (const item of rawList) { const lng Number(item.lng); const lat Number(item.lat); if (!isFinite(lng) || !isFinite(lat)) continue; if (lng -180 || lng 180 || lat -90 || lat 90) continue; const key ${lng.toFixed(6)},${lat.toFixed(6)},${item.name || }; if (seen.has(key)) continue; seen.add(key); out.push({ lng: lng, lat: lat, name: item.name || }); } return out; }逻辑说明先用Number()和isFinite过滤非数值再按 6 位小数拼 key 去重最后返回干净的数组。参数上toFixed(6)是经验值约等于 0.1 米的精度。如果数据源本身只保留 5 位小数这里可以降到 5避免把两个坐标不同的点误判为同一个点。3.2 聚合核心网格字典累加输出聚合点与数量聚合算法需要一个网格尺寸参数单位用米。POI 的坐标是经纬度直接用固定度数切格高纬度地区会严重变形所以常见做法是把“米”换算成“度”纬度方向近似 1 度约等于 111320 米经度方向要乘cos(lat)修正。聚合主循环就是一个字典累加对每个 POI 计算所在格的坐标格子 key 用${gridX},${gridY}拼接Map 里累加经纬度和数量。我这里特意避开了 Cesium 的坐标 API只用原生 Math后面接 WebWorker 时不会踩坑。function gridAggregate(pois, gridSizeMeters) { const METERS_PER_DEG_LAT 111320; const DEG_TO_RAD Math.PI / 180; const gridMap new Map(); for (const poi of pois) { // 当前纬度下1 度经度对应的实际米数 const metersPerDegLng METERS_PER_DEG_LAT * Math.cos(DEG_TO_RAD * poi.lat); const gx Math.floor(poi.lng / (gridSizeMeters / metersPerDegLng)); const gy Math.floor(poi.lat / (gridSizeMeters / METERS_PER_DEG_LAT)); const key ${gx},${gy}; let g gridMap.get(key); if (!g) { g { count: 0, sumLng: 0, sumLat: 0, items: [] }; gridMap.set(key, g); } g.count; g.sumLng poi.lng; g.sumLat poi.lat; g.items.push(poi); } return Array.from(gridMap.entries()).map(([key, g]) ({ key: key, count: g.count, lng: g.sumLng / g.count, lat: g.sumLat / g.count, items: g.items })); }逻辑说明每个 POI 先算出自己在哪个网格然后经纬度分别累加到对应格子的sumLng和sumLat最后除以 count 得到平均位置。items保留原始 POI用于第 6 章的点选展开功能不需要这个功能时可以去掉以节省内存。核心参数gridSizeMeters是聚合粒度越小聚合点越多、越接近原始位置越大聚合点越少、位置偏移越明显。经度方向的换算按每个 POI 自己的纬度独立计算同一个几百米的方格内部纬度差异很小不会造成可见的错位。提示如果聚合结果最终要传到 WebWorker 里跑依赖 Cesium 的接口越少越好这个函数已经是纯计算版本直接可以丢给 Worker。3.3 用 Primitive 渲染聚合结果为什么比 Entity 快一个量级聚合后数据从几万条变成几百条渲染压力已经下降但最后一步也不建议用 Entity。因为聚合要随相机高度动态重算每次重算都要重建点集Primitive 的显式控制比 Entity 更适合这种频繁更新。常见做法是把每个聚合点变成一个 PointGeometry 实例用 PerInstanceColorAppearance 让不同数量的聚合点显示不同颜色。PointGeometry 的像素大小在几何体构造时确定所以大小按 count 分级预生成几种不同尺寸的几何体按数量区间选用避免所有点一个尺寸看不出热度。function buildPrimitive(aggPoints) { const sizeSteps [ { max: 10, size: 8 }, { max: 50, size: 14 }, { max: 200, size: 20 }, { max: Infinity, size: 26 } ]; // 预生成 4 种不同像素尺寸的几何体按 count 分级复用 const geometryBySize sizeSteps.map(s ({ max: s.max, geometry: new Cesium.PointGeometry({ pixelSize: s.size, vertexFormat: Cesium.PerInstanceColorAppearance.FLAT_VERTEX_FORMAT }) })); const instances []; for (const p of aggPoints) { const geom geometryBySize.find(g p.count g.max); const color countToColor(p.count); const position Cesium.Cartesian3.fromDegrees(p.lng, p.lat, 2); instances.push(new Cesium.GeometryInstance({ geometry: geom.geometry, modelMatrix: Cesium.Matrix4.fromTranslation(position), attributes: { color: Cesium.ColorGeometryAttribute.fromColor(color) }, id: { gridKey: p.key, count: p.count, items: p.items } })); } return new Cesium.Primitive({ geometryInstances: instances, appearance: new Cesium.PerInstanceColorAppearance({ flat: true, translucent: false }), asynchronous: false }); }逻辑说明这段代码做两件事。第一按 count 分级选不同 pixelSize 的 PointGeometry避免点太大互相遮挡、太小看不见。第二把每个聚合点的位置通过modelMatrix从原点平移到目标经纬度同时把gridKey、count、items挂到id上供后续点选使用。asynchronous: false是为了在聚合结果变化时同步替换场景里的旧 Primitive避免异步构建导致的显示滞后。PointGeometry 的几何体默认在原点Matrix4.fromTranslation只需要平移到目标 Cartesian3 即可不需要再做额外偏移。height 设为 2 而不是 0是为了避免点贴地后被地形或建筑遮挡数值需要按你的数据场景调整。countToColor是颜色映射函数第 5.2 节会单独展开这里先只管调用。4. Cesium 中聚合的显示细节可视范围、缩放层级与更新策略4.1 根据相机高度动态调整网格尺寸聚合率不随缩放跳变固定gridSizeMeters会带来一个现象地图缩到全国范围时聚合点稀疏放大到街道级别时聚合点又过度密集格子比屏幕上的 POI 还多。解决方式是让网格尺寸和相机高度联动常见做法是先估算相机视野在当前位置覆盖多少米除以画布像素得到每像素对应的米数再用最小像素间距反推网格尺寸。function calcGridSizeFromCamera(viewer, minPixelDist) { const canvas viewer.canvas; const camera viewer.camera; const height camera.positionCartographic.height; const fovy camera.frustum.fovy; // 单位是弧度Cesium 里不需要再转 const visibleHeightMeters 2 * height * Math.tan(fovy / 2); const meterPerPixel visibleHeightMeters / canvas.clientHeight; return Math.max(50, meterPerPixel * minPixelDist); }逻辑说明先估算垂直视野在地面上覆盖的真实米数除以画布像素高度得到每像素米数再乘minPixelDist得到网格尺寸。minPixelDist代表聚合点之间期望的最小屏幕像素距离一般取 20 到 40。值是 28 时聚合点在屏幕上大约间隔 28 像素观感最均衡。Math.max(50, ...)是下限防止缩放到最大级别时网格小于街区尺度导致聚合点密集到失去意义。配合上一章的gridAggregate在相机高度变化时重算网格并重新聚合。这里有个参数细节鼠标滚轮连续缩放时camera.changed 事件会以极高频率触发每次都全量重算的话再快的算法也会卡。所以网格尺寸变化要设置阈值变化量超过一定比例才重算这就是下一小节要处理的问题。4.2 整体替换更新与监听节流地图缩放不卡的关键拿到新聚合结果后更新画面有两种写法。第一种是直接 remove 旧 Primitive、add 新 Primitive实现简单对聚合结果这种几百个点的小场景没有明显开销我推荐这种。第二种是保留 Primitive 只更新 geometryInstances需要处理旧实例销毁和 GPU 缓冲重建代码麻烦容易漏掉释放导致内存上涨收益却不大。整体替换的关键点在于节流。下面这段是完整的监听逻辑放在初始化代码里地图一缩放就会自动更新聚合let currentPrimitive null; let lastGridKey ; viewer.camera.changed.addEventListener(() { const grid calcGridSizeFromCamera(viewer, 28); // 把网格尺寸散列成离散档位只有当档位变化时才重算 const key grid 50 ? 50 : grid 100 ? 100 : String(Math.round(grid / 50) * 50); if (key ! lastGridKey) { lastGridKey key; requestAnimationFrame(() updateAggregation(viewer, sourcePOIs, grid)); } }); viewer.camera.moveEnd.addEventListener(() { // 移动结束时做一次最终兜底确保聚合点和视角完全同步 const grid calcGridSizeFromCamera(viewer, 28); updateAggregation(viewer, sourcePOIs, grid); }); function updateAggregation(viewer, pois, gridSize) { const agg gridAggregate(pois, gridSize); const newPrimitive buildPrimitive(agg); if (currentPrimitive) { viewer.scene.primitives.remove(currentPrimitive); } viewer.scene.primitives.add(newPrimitive); currentPrimitive newPrimitive; }逻辑说明camera.changed在连续缩放中高频触发代码先用档位 key 做判断网格尺寸没跨档就不重算。moveEnd做最终兜底因为 changed 的节流可能让最后一次缩放停在旧档位moveEnd 再算一次保证画面准确。updateAggregation里先构建新 Primitive 再移除旧的避免出现点集先消失、几百毫秒后才回来的现象。注意moveEnd兜底虽然准确但如果数据量大用户快速缩放时会在移动结束瞬间卡一下。可以把updateAggregation里的聚合部分放到 requestAnimationFrame 里卡顿会明显缓解。4.3 聚合点数量与可视层级绑定什么时候该显示原始点当相机高度很低、网格尺寸被Math.max(50, ...)限制在 50 米时聚合点基本等于原始 POI 的位置此时聚合意义不大而且格子里的点数量也会变得很少。反过来相机高度非常高时聚合点数量会骤减到只有几个地图上没有内容感。两种极端情况都需要兜底逻辑。第一种情况判断当前网格尺寸小于 30 米时直接切换到原始点模式不再聚合用独立的 Primitive 绘制原始 POI样式和聚合点区分开。第二种情况聚合结果少于 10 个点时把minPixelDist从 28 降到 15 重新算一版保证地图上始终有足够多的聚合点。原始点模式不要和聚合点混在同一个 Primitive 里否则点太多会淹没聚合点最好用单独的 Primitive 管理方便清理。5. POI 聚合落地避坑5 条血泪经验5.1 聚合点闪烁、跳动位置高度没有统一现象是地图静止时聚合点不断闪烁或者稍微拖动视角同一个 POI 就被吸到附近另一个位置。排查时先看两点第一Cartesian3.fromDegrees的第三个参数是否所有点都一致如果有 0、有 2、有 10点会被地形高低差抬得参差不齐拾取判定也不稳定第二更新时有没有先移除旧 Primitive 再添加新的新旧两个 Primitive 同时存在视觉上就是点在跳。解决方式高度统一用固定值不要混用地形高度。更新时严格先构建新的再 remove 旧的然后 add 新的用currentPrimitive保证同时只有一个聚合 Primitive 在场景里。5.2 颜色分档看不出层次用线性映射聚合点数量现象是聚合结果里 80% 的格子点数量在 10 以内只有几个热点超过 1000用线性映射颜色后小数量点颜色完全一样热点也只是一个稍微深一点的蓝。原因是 POI 数量分布是长尾的线性映射把绝大多数点的颜色差异压缩到肉眼无法分辨。解决方式是对 count 取对数再映射色相把长尾压缩到 0 到 1 的区间里function countToColor(count) { // 对数压缩避免 5 个点和 500 个点的颜色拉不开差距 const t Math.min(1, Math.log(count 1) / Math.log(1000 1)); return Cesium.Color.fromHsl(0.58 - t * 0.58, 0.7, 0.5, 0.9); }逻辑说明count 为 0 时 t 约等于 0颜色接近蓝色count 到 1000 时 t 为 1颜色偏暖色。Math.min(1, ...)是防止超过 1000 的点把色相推成负值。如果你希望热点更突出把1000改成你数据的 90 分位值映射会更贴合你的分布。另外注意PerInstanceColorAppearance的translucent参数没有特殊需求保持 false走不透明管线性能更好也不会和地形透明叠加产生伪影。5.3 点被地形和建筑遮挡把点抬高一点现象是地形起伏大的区域聚合点在地图旋转视角时被山体完全盖住用户看不全。原因是Cartesian3.fromDegrees的高度传 0 时点在椭球体表面地形起伏后自然被遮挡。解决方式是统一抬高。最省事的是给fromDegrees传 2 到 5 米。如果场景里高层建筑密集这个高度还要再加。不要试图对每个点动态获取地形高度十万个点的异步地形查询会拖垮性能。聚合完成之后只剩几百个点这个量级可以逐个查询做法是聚合结果出来后对每个聚合点调用一次地形高度接口再加一个常量 offset。整体效果比固定高度好很多性能也可接受。5.4 使用 WebWorker 聚合时踩的坑Worker 里不能用 Cesium 的坐标类现象是主线程不卡了但 Worker 里一调Cesium.Cartesian3或Cesium.Math直接报错。原因是大部分打包配置下Worker 里注入的 Cesium 是独立的模块实例甚至没有完整初始化调用任何跟渲染相关的 API 都可能抛异常。解决方式是让 Worker 保持纯计算聚合函数从一开始就只依赖原生 Math。第 3.2 节的gridAggregate已经是这个风格Math.PI / 180替代了Cesium.Math.toRadians坐标转换全部放到主线程做。Worker 里只接收{ lng, lat, name }数组回传{ key, count, lng, lat, items }这样聚合逻辑在浏览器主线程和 Worker 里都能跑同一份代码切换成本最低。5.5 点选聚合点拿不到原始 POIid 里没有存数据现象是点击聚合点只能拿到一个 count拿不到格子里具体的 POI 列表信息弹窗和下钻展示都做不了。原因是构造 GeometryInstance 时没有传 id或者 id 里只放了 count。解决方式是把原始 POI 的索引列表放到 id 里。数据量不大时可以直接放 items 数组像第 3.3 节那样。数据量大时不要直接持有原始对象而是存它们在源数组里的下标点选时按下标到源数组里取避免 Primitive 额外持有一份大对象数组导致内存翻倍。拾取代码在第 6.1 节给出这里先记住原则id 里带数据弹窗和展开才有得用。6. 进阶点选命中、展开聚合点与最后一级的下钻体验6.1 拾取聚合点的正确姿势Primitive 拾取聚合点用scene.pick。因为 GeometryInstance 构造时已经设了 idpick 的返回对象上会带这个 id。注册 LEFT_CLICK 事件判断 id 存在后读取gridKey和总量信息viewer.screenSpaceEventHandler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); viewer.screenSpaceEventHandler.setInputAction((movement) { const picked viewer.scene.pick(movement.position); if (!Cesium.defined(picked) || !Cesium.defined(picked.id)) return; const meta picked.id; if (meta.gridKey) expandGridPOIs(meta); }, Cesium.ScreenSpaceEventType.LEFT_CLICK);逻辑说明picked.id就是构造 GeometryInstance 时传入的 id 对象。用gridKey字段判断是否是聚合点避免拾取到地形或其他 Primitive 时误触发展开逻辑。如果同时存在多个 Primitivescene.pick在默认情况下只会返回最顶层的对象聚合 Primitive 要先确认没有被其他数据源挡住。6.2 点击聚合点展开原始 POI 列表聚合点的数量信息有了用户点击后想看格子里具体是哪些 POI。常见做法是在聚合 Primitive 之上临时追加一个展开层的 Primitive把原始 POI 用小尺寸点画出来同时弹一个信息浮层列出名称列表。如果展开点太多还要做二次聚合避免在超热格子里一次性画几百个点。let expandedPrimitive null; function expandGridPOIs(meta) { // 每次展开前先清理上一次的展开层 if (expandedPrimitive) { viewer.scene.primitives.remove(expandedPrimitive); expandedPrimitive null; } expandedPrimitive buildExpandedPrimitive(meta.items); viewer.scene.primitives.add(expandedPrimitive); }逻辑说明这段逻辑的关键是把聚合点与展开点分开管理聚合的 Primitive 仍在场景里展开点独立叠加通过expandedPrimitive持有引用。用户点击其他聚合点时先移除上一次展开结果再添加新的。buildExpandedPrimitive的内部结构与buildPrimitive类似但每个点用原始坐标、pixelSize 更小、颜色统一为浅色半透明透明度降低可以让用户透过展开点看到整体聚合态势。当meta.items.length超过 50 时建议在函数内部按 30 米小网格再做一次二级聚合避免展开点本身成为新的渲染压力。6.3 聚合点与原始点之间的平滑过渡最后说一个我踩过的坑。聚合下钻时不要一开始就做位置动画聚合点从聚合中心平滑飞到各自原始坐标视觉上确实好看但有几件事会让你翻车。一是动画期间的拾取不可用用户在这个过程中点击区域经常会命不中二是格子内点数量多时动画本身掉帧30 个点还好80 个点就开始肉眼可见的顿挫三是用户注意力集中在最终结果而不是飞行过程动画带来的价值远小于它消耗的性能和调试成本。我的开发习惯是静态 POI 用前端网格聚合加 Primitive 渲染动态更新数据用后端聚合加前端渲染结合。每个项目开工前先定一张聚合参数表把网格最小尺寸、最小像素距离、颜色分档、抬升高度、展开阈值写进去不同数据源直接替换参数不用重写逻辑。照着上面的代码搭一版城市级十万 POI 稳定跑到 60 帧是完全可以做到的希望这些方案能帮到你。本文还有配套的精品资源点击获取