Cesium加载MVT矢量瓦片的三种方案与实操指南
1. MVT到底是什么,为什么三维GIS绕不开它
做GIS开发的同行,这两年应该没少在项目里碰到MVT这个词。MVT全称Mapbox Vector Tiles,是Mapbox提出的一种矢量瓦片编码规范,本质是把地理数据按金字塔层级切分成一个个二进制瓦片,每个瓦片里存的是几何要素、属性字段和图层信息,用Protocol Buffers压缩编码。相比传统栅格瓦片,MVT不再把地图渲染成固定图片,而是把数据本身交给前端,由渲染引擎实时决定怎么画。这个思路直接改变了Web GIS的架构方式。
我最早接触MVT是在做Web端大屏项目时,栅格瓦片在高分屏上放大后显示模糊,切图服务磁盘占用也大。后来换成MVT,数据量小一个数量级,而且样式更新不需要重新切图,改个JSON样式文件就能全局换皮。最直观的理解可以把MVT比作网页里的矢量字体——存的是字形轮廓而不是光栅图,放大多少倍都清晰锐利,体积还小得多。
不过MVT在二维WebGIS里用得再顺手,到了三维场景就成了另一码事。Cesium作为目前最流行的开源三维地球引擎,原生支持3D Tiles、GeoJSON、KML这些格式,却偏偏不直接支持MVT。很多刚从二维切到三维的团队,拿着浏览器访问MVT服务的地址往Cesium里扔,Cesium根本读不了。这个状况导致一个很尴尬的现实:数据源头越来越多地用MVT输出,到了三维展示却要先折腾一步转换或者二次开发。
解决这个问题的思路大体有三条:一是用Cesium后端服务把MVT转成3D Tiles;二是借助Cesium的ImageryProvider接口,把MVT解码成图片喂给Cesium当底图用;三是写一个自定义数据源,解析MVT并在Cesium里直接绘制成矢量要素。三条路各有适用场景,本文会逐一讲透,并给出我从实际项目中踩坑攒下来的实操细节。
2. 思路拆解:从二维矢量瓦片到三维场景的三条路线
2.1 为什么不能直接加载:数据模型差的不是一点半点
要理解加载方案的取舍,先得知道Cesium和MVT在数据模型上的根本差异。MVT的核心结构是“瓦片金字塔”,每个瓦片用行列号标识,瓦片内部是uint32编码的长度前缀字段,包含图层名、要素几何、属性表,几何坐标采用512或4096单位的整数网格,需要配合tile的extent做归一化换算。Cesium的三维场景则建立在全球椭球体上,所有数据最终都要归一到ECEF(地心地固坐标系)或局部ENU坐标系中。
这意味着MVT里的每个坐标都是“瓦片内相对坐标”,和真实经纬度之间隔着一个瓦片范围换算的过程。Cesium不认识MVT的二进制容器,也没有内置解码器,所以直接把MVT地址塞给Cesium的viewer.imageryProvider,只会得到一个“Unsupported format”或者干脆白屏。初期项目里,我见到有同事试图用Cesium的GeoJSONDataSource去请求MVT,折腾一天结果自然是失败。所以第一件事要认清:这需要一个桥接层,谁来当这个桥接层,取决于你的渲染目标。
如果目标是给三维地形或影像做矢量标注、叠加路网、显示行政边界,那么用ImageryProvider方案最合适;如果目标是让矢量要素能够被点击拾取、实时高亮、与业务数据联动,那必须走自定义解码绘制的路线;如果数据量特别大,需要流畅的LOD调度,那转3D Tiles是长远最优解。
2.2 方案A:后端转换MVT为3D Tiles
这个方案本质上不在Cesium端做任何处理。用现成的工具(比如TileServer GL、cesium-terrain-server配合转换脚本,或者基于MapLibre的MVT转B3DM工具)定时把MVT服务拉取并重建成3D Tiles数据,Cesium直接加载生成的tileset.json。优点是一劳永逸,Cesium原生支持3D Tiles,性能最好;缺点是数据有延迟,如果原始MVT更新频繁,重建成本很高,而且需要额外的服务器资源做转换。
适合的场景是数据更新不频繁的基础底图,比如全国行政区划、路网骨架、水系分布。我实际在一个省级路网项目里用这种方式,把MVT按zoom 0到14转换生成3D Tiles,Cesium加载很流畅,几十万个线要素没什么压力。转换工具我推荐使用MapTiler的tileserver-gl加上另写脚本导出,或者直接用northvector/mvt2tiles这类开源方案。操作步骤大概可以总结为:先起一个本地MVT服务,再用转换工具逐级读取,最后将输出布置到静态文件服务器,Cesium的Cesium3DTileset直接指向tileset.json即可。
2.3 方案B:用ImageryProvider把MVT渲染成影像层
这是大多数团队快速上手的首选。思路是把MVT丢给一个能识别它的渲染引擎(通常是MapLibre GL JS),渲染出瓦片图片,然后通过Cesium的UrlTemplateImageryProvider或者自定义Provider把渲染结果叠加到地球表面。这样做的好处是开发成本极低,前端只需要在Cesium容器里隐藏一个MapLibre实例,或者部署一个瓦片渲染服务,让Cesium通过图片URL去请求。
可以类比把MVT当做了“半透明底图”,Cesium只关心渲染后的影像瓦片,不关心矢量数据的细节。这个方案里,点击拾取矢量属性比较困难,因为Cesium拿到的只是图片,属性信息在图片像素里不存在。不过如果要的只是视觉叠加,这个短板完全可以接受。
具体实现上,我推荐用MapLibre GL JS作为渲染引擎,因为它兼容MVT规范,样式配置灵活。MapLibre渲染完成之后,可以通过canvas的toDataURL导出图片,或者更高效的方式是直接在MapLibre内部设置一个隐藏canvas,用Cesium每帧请求指定瓦片坐标的图片。另一种更工程化的做法是用现成的瓦片渲染服务,比如tileserver-gl,它能把MVT渲染为PNG瓦片,Cesium用标准XYZ模板地址就能加载。这个方案对团队前端技术栈要求低,后端一个Docker容器就能搞定。
2.4 方案C:自定义数据源解码绘制(真正把MVT融进三维实体)
如果你想在三维场景中让MVT里的要素具备“实体感”,可以被拾取、高亮、绑定属性弹窗,那必须走自定义数据源这条线。这个方案工作量最大,也最灵活。核心步骤可以拆成四步:请求MVT数据、解码PB二进制、坐标转换、逐要素绘制。
解码这一步建议直接用mapbox/vector-tile-js这个JavaScript库,它能把ArrayBuffer解析成GeoJSON格式的要素集合。坐标转换是重头戏,需要把瓦片内相对坐标转成经纬度,公式其实不复杂,我在项目里写过一个完整实现,会在第五节详细展开。绘制阶段可以用Cesium的CustomDataSource添加Polyline、Polygon、Point实体,也可以细粒度地使用CallbackProperty实现动态更新。
这套方案的难点在于MVT中几何类型复杂,有Point、LineString、Polygon,每种类型都要写对应的实体生成逻辑;另外MVT的坐标是Z字曲线排序的,需要还原成真实坐标顺序,处理不恰当会出现线乱连、多边形自交的诡异效果。但一旦调通,你会拿到一个完全可控的三维矢量层,交互体验比图片方案高一个档位。
3. 实操之前:环境与依赖准备
3.1 工具选型与版本说明
我需要先声明一点,MVT规范是Mapbox提出的,但现在已经开源,Cesium加载MVT的方案选择很多,我下面使用的技术组合都是目前社区最稳定的:
- Cesium:推荐使用 1.100 以上版本,对ES模块和3D Tiles支持更好,我这里用1.111示例。
- MapLibre GL JS:v3之后的版本对MVT支持更完善,样式标准兼容Mapbox Style Spec。
- vector-tile-js:基于mapbox的官方解码库,npm包版本3.x,依赖pbf解析器。
- pbf:Protocol Buffers解码库,decode MVT时用的,vector-tile-js内部已经依赖它,但在自定义方案里你可以直接用pbf写更底层的解析。
- tileserver-gl:可选,Docker部署,用于方案B的瓦片渲染服务。
在动手之前,先检查你的MVT数据源地址是否能正常访问。常见格式是http://host:port/data/{z}/{x}/{y}.pbf,你要确认返回的Content-Type是application/x-protobuf,同时注意CORS跨域问题,开发阶段至少给静态服务器加上Access-Control-Allow-Origin头。
3.2 MVT数据源准备
如果手上没有现成MVT数据,可以用国内公开的样例服务测试,比如OSM的矢量瓦片服务,或者用Tippecanoe自己切一份测试数据。我建议初学者先用一份小范围、图层结构简单的MVT,比如只包含道路和边界两个图层,这样调试效率高很多。
我常用Tippecanoe做测试数据,安装后一条命令即可:
这个命令会把input.geojson切到zoom 0到14的MVT瓦片,存入output.mbtiles。注意当你用tileserver-gl发布这个mbtiles时,它提供的服务路径就是标准XYZ格式,可以直接用。
4. 核心细节解析:MVT的解码、坐标与绘制原理
4.1 MVT二进制格式的精髓
MVT数据本质上是一个Protocol Buffers消息块。顶层Message包含若干图层(layer),每个图层有name、extent、version和features数组。每个feature由id、tags、type和geometry组成。tags是属性键值对的索引,指到layer的keys和values数组;geometry则是按照规范编码的几何命令序列。
理解geometry编码是关键。MVT的几何编码采用“命令-参数”模式,每条命令包含Moveto、Lineto、Closepath三种类型之一,数字通过zigzag编码压缩。这样的设计使得一次move、大量line、一次close的组合能紧凑地表示一条折线或一个多边形。解码时,你需要逐条解析这些命令,把相对坐标累加成绝对坐标,再除以extent并乘以瓦片地理范围,最终得到经纬度。
我用一组简单的数据来描述这个过程:
假设一个瓦片范围为[xmin, ymin, xmax, ymax],瓦片坐标系的extent为4096,则某要素的点(px,py)对应的经纬度:
注意lat是用ymax减,因为屏幕坐标系y轴向下,而地理纬度向上。很多初学者在这里搞反,画出来的要素跑到海里了。
4.2 坐标转换的完整公式
如果你用的是vector-tile-js,它已经替你完成了从命令到几何坐标的解码,输出成GeoJSON时,坐标是瓦片像素坐标(以extent为基准),你仍需要把这个坐标换算成经纬度。我封装了一个函数:
这是Web Mercator投影下的瓦片坐标换算公式。利用这个函数可以算出某瓦片对应的经纬度范围。求解瓦片范围的完整代码我放在后面第5.3节。
4.3 属性与样式的取舍
MVT的图层设计自由度很高,一个瓦片内可以混合多个图层,每个图层有独立的extent。加载进Cesium时,你要决定哪些图层显示、哪些图层隐藏。我一般给自定义数据源增加一个filter参数,类似于:
这个filter对象还可以扩展成按属性过滤,比如只看等级为高速的公路。这部分是业务耦合的,通用库不会帮你做,但在实际项目里往往是最核心的需求。
4.4 为什么高频刷新场景优先考虑解码绘制
再补充一点我的个人经验:如果项目里的MVT服务更新非常频繁,比如实时路况、车辆轨迹,方案A每次重建3D Tiles的成本太高,方案B的图片瓦片有缓存延迟,此时方案C几乎成了唯一解。方案C能做到每次请求新瓦片、解码、重绘,秒级生效。代价是对前端解码性能要求高,好在MVT本身轻量,现在浏览器处理PB解码速度很快,万级要素规模不会成为瓶颈。
5. 实操过程:用代码把MVT加载到Cesium里
5.1 第一步:搭建Cesium基础场景
先把基础场景搭起来,这里用的是Cesium的Viewer,关闭不必要的控件加快加载速度,设置光照让矢量数据有立体感:
注意depthTestAgainstTerrain要设置成false,否则矢量会被地形遮挡导致看不见。
5.2 第二步:请求与解码MVT
我采用方案C作为主示例,因为它最通用,也是你从零迁移到三维最好的学习路径。首先写一个加载瓦片的函数,本质上就是一个XYZ请求,加一个ArrayBuffer解封装:
这里用到了pbf和vector-tile-js,安装方式:
5.3 第三步:瓦片范围计算
在绘制前,需要把xyz转成经纬度范围。这个函数我用了多次,直接复制可用:
注意这里的y坐标是Web Mercator中的瓦片行号,通常MVT服务也是按该规则组织,如果你的服务用TMS的y翻转,记得用 (Math.pow(2,z)-1-y) 替换。
5.4 第四步:坐标转换与实体绘制
解码得到每个图层的features后,遍历geometry。vector-tile-js返回的geometry是GeoJSON类型坐标,但仍是瓦片坐标体系。我们将每个feature的坐标数组换算成经纬度:
注意extent取当前图层extent字段,不是固定值。然后把转换后的坐标构建成Cesium实体。点要素用Cesium.PointPrimitiveCollection聚合效率更高,线面则用Polyline/Polygon。
feature.type在vector-tile-js中对应是1/2/3,分别代表点、线、面,这个常量在常量类中有定义。
5.5 第五步:按视口动态加载瓦片
Cesium场景是动态视野,你必须根据当前视角的经纬度范围动态加载对应zoom的瓦片。一个有效的办法是监听相机变化,计算当前屏幕对应的经纬度范围,然后按某个zoom请求覆盖这些瓦片。为了避免频繁请求,需要加入瓦片缓存和去重逻辑。
我实现过一个简单的瓦片管理器,核心伪代码如下:
getCoveringTiles需要把经纬度范围映射为瓦片行列号,核心公式:
注意这是异步流程,瓦片返回的顺序可能和请求顺序不一致,需要在drawTile前判断当前范围是否已经移动,避免把过期的瓦片画到新视图上。
5.6 方案B的快速实现参考
如果你只想要一个能跑能看的demo,方案B肯定更快。使用tileserver-gl很简单,Docker一条命令:
然后Cesium里加载:
如果你没有tileserver-gl,也可以用MapLibre GL JS的canvas渲染图片,把MapLibre的canvas作为Cesium的材质源,但这个做法复杂一些,不建议新手一开始就尝试。
6. 常见问题与排查技巧实录
6.1 瓦片加载404或者白屏
最常见的问题就是瓦片路径不对,尤其是y轴翻转。MVT服务通常使用XYZ坐标(y轴从北往南),但有的服务采用TMS(y轴从南往北)。排查办法很简单:打开浏览器网络面板,看请求的URL和实际服务端返回的内容,如果404说明行列号超出范围,如果返回空说明数据源没有该层级。TMS和XYZ的y转换公式是 y_tms = (2^z - 1) - y_xyz。
在代码里,如果你发现某个层级的瓦片总有一半区域空白,赶快检查是不是y轴翻转。
6.2 矢量要素错位或漂移
坐标错位的原因有几种:一是忘掉设置extent,或者用了错误的extent;二是经纬度换算公式中y方向反了;三是MVT服务的数据不是Web Mercator而是WGS84直接切图。我遇到过用WGS84经纬度切成MVT,导致换算无法对齐,这种情况要先把源数据做投影转换。
排查方法可以自己写一个小工具,在指定的瓦片范围内随机生成一组点,再手动打印某个要素的经纬度坐标和真实地图对比,如果偏得离谱,八成是公式问题。如果只是轻微偏移,可能是大地水准面问题,但这种在MVT里很少见。
6.3 层级切换时要素闪烁
闪烁一般是瓦片重复加载或清除逻辑有问题。我在动态加载瓦片时,曾遇到相机小范围移动触发大量瓦片重新请求,画面上来回闪烁。解法是给瓦片绘制加一个缓冲区,只有当旧瓦片完全离开视口后才清除,或者对请求做防抖,在相机停止后200毫秒再发起请求。
6.4 大量要素导致卡顿
如果要素动辄几十万,用viewer.entities.add一个一个加必然卡死。你必须改用Primitive API或者PointPrimitiveCollection、PolylineCollection。我在路网项目里,用PolylineCollection批量添加线要素,性能比Entity提高至少5倍。结构如下:
终极方案是使用CustomShader或GeometryBatch,但中小项目用Collection足够。
6.5 属性拾取怎么实现
如果你的方案B是图片瓦片,那属性拾取几乎不可能。方案C里拾取就简单多了,Cesium的ScreenSpaceEventHandler可以获取点击位置的经纬度,然后遍历当前视口内的要素做点包含判断。简化版本用Cesium的pickEntity自动拾取,前提是你在添加Entity时设置id为feature的属性对象:
然后通过pickEntity的id拿到属性,制作Popup。这一步完全是业务逻辑,可以根据需要自行实现。
6.6 服务端CORS问题
浏览器直接fetch MVT需要服务端允许跨域。如果你使用的是开发环境,可以本地起临时代理解决;生产环境务必让运维配置好CORS头:
或者指定你的前端域名。这个坑很常见,不配置的话浏览器报CORS错误,很多人误以为解码有问题,排查半天实际只是网络请求被拦截了。
7. 进一步扩展:MVT与3D Tiles的效率对比
最后聊聊我实际项目中的一个体感。同样一份全国道路网数据,切成MVT后全部矢量要素在二维瓦片里占磁盘大约3GB,三维场景用3D Tiles转换后大约500MB,加载速度后者明显更快。这是因为3D Tiles在调度时对数据做了更精细的空间剔除,离相机远的要素直接不加载,而MVT的瓦片是一整块下载,无法按需细分。
如果你同时存在二维和三维项目,我建议统一数据源为MVT,再按需转换为3D Tiles。底图数据变化不频繁的用转换方案,底图数据变化频繁的用方案C。我在某个智慧园区项目里,园区内部路网MVT每天更新,用了方案C实时刷新路面状态;园区周边建筑底图一个月才更新一次,直接转过3D Tiles。这样组合下来,既保证了数据时效,又维持了交互流畅度。
MVT在三维场景中的加载方案现在还处于群雄并起的阶段,新工具层出不穷,但底层原理不变。把坐标换算、属性解析、渲染调度这三个基本功打牢,不管前端框架怎么演进,你都能快速迁移。我这几套代码已经在多个项目里跑过,你直接按住不改也能跑通大部分场景,真遇到特殊需求再往上层加策略就是。
最后再分享一个小技巧:调试MVT时,不要急着接三维,先在二维MapLibre里把数据源URL加进去验证样式和数据正确性,二维没问题再进三维排解码和坐标的错。这样能把问题隔离干净,省掉很多联调时间。