简介这是一份面向GIS开发者的Mapbox加载3DTiles倾斜摄影模型示例项目。项目整合Mapbox GL JS与deck.gl的CesiumIon3DTileLayer演示如何在地图上高效加载并展示大规模倾斜摄影数据适合需要实现城市三维场景、数字孪生或倾斜模型可视化的前端与GIS工程师尤其适合已具备基础WebGIS知识、想快速上手三维数据接入的开发者。压缩包共5个文件包含2个JavaScript、2个JSON和1个HTMLJS文件承载地图初始化、数据加载及点击交互逻辑JSON文件管理npm依赖与Webpack构建配置HTML作为页面入口整体结构清晰便于定位与修改。已有4890人学习浏览。借助该demo可掌握Mapbox与deck.gl协同接入3DTiles的完整流程理解CesiumIon3DTileLayer的数据组织与调用方式并基于示例代码扩展属性查询、图层切换、视角动画等功能为智慧城市、规划展示、环境监测等场景提供可复用的三维GIS开发脚手架。 今年接了一个无人机倾斜摄影模型的Web展示需求模型是实景三维的甲方要求叠加到地图上能转视角、能定位、能看周边环境。项目定了Mapbox做底图但真正动手才发现Mapbox原生压根不认3D Tiles直接拖进去什么都显示不出来卡在如何让Mapbox加载3dTiles倾斜摄影模型这一步上的人不在少数。这篇文章就把我从数据转换到最终demo跑通的完整链路写出来包括那套能直接复用的代码以及几个让我调试到凌晨两点的坑。内容适合正在做WebGIS可视化的前端开发者、测绘行业的软件工程师以及准备把倾斜摄影数据接到地图上做展示的产品同学。1. 为什么说Mapbox和3D Tiles天生不搭1.1 3D Tiles到底是什么东西要搞明白兼容性问题先得清楚3D Tiles的数据组织方式。它本质上是一套面向海量三维地理空间数据的流式调度规范核心是tileset.json这个入口文件再加上一堆瓦片数据。每个瓦片可以有多个类型倾斜摄影最常用的是b3dmBatched 3D Model它有LOD层级调度能力视点近了加载精细模型远了自动切粗模。想象一下一栋楼拍出来的倾斜摄影模型如果一次性全部加载到浏览器几千万个三角面直接卡死。3D Tiles的聪明之处在于它把模型按金字塔结构切成很多块视点在哪里就只加载附近能看到的块几何误差大的块在远处直接跳过等用户走近了再补细节。这套调度逻辑需要渲染层深度配合光能解析文件格式远远不够。1.2 Mapbox GL JS只认自己的那套渲染体系Mapbox GL JS是基于WebGL的矢量地图渲染引擎它的核心调度单位是样式图层瓦片。你可以在里面加矢量瓦片、栅格瓦片、GeoJSON数据、模型图层但它的数据模型完全围绕Mapbox方案设计。v3版本之后虽然支持了model图层加载glTF/glb模型但那是针对单个模型或者少量模型实例的面对b3dm这种批量压制的场景完全不够用更别说实现了3D Tiles的LOD调度算法和瓦片请求策略。很多人一开始都以为Mapbox会原生支持3D Tiles毕竟都是做地图的。但事实就是不行社区里等着官方支持等了好几年也没等到最后只能靠第三方方案来做桥接。1.3 路只有一条吗三套常见方案的取舍我调研了一圈目前把3D Tiles塞进Mapbox的主流方案有三套。第一套是deck.gl的Tile3DLayer配合deck.gl的MapboxLayer桥接类在Mapbox的地图上以自定义图层形式插入3D Tiles图层。这是目前最主流、维护最活跃的方案也是我最终选择的路线。第二套是mapbox-3dtiles这类老插件基于three.js的TilesRenderer封装早期项目用得多但仓库维护半停滞遇到新版Mapbox容易翻车配置项也比较绕。第三套是绕开Mapbox直接用Cesium加载3D Tiles把它的div浮在Mapbox上面。这个看起来简单实际上两个地图的相机同步、事件穿透、图层遮挡都是大坑不到万不得已不建议。方案技术栈维护状态复杂度适用场景deck.gl Tile3DLayerdeck.gl Mapbox GL JS活跃官方维护低有例程主流推荐mapbox-3dtiles插件three.js Mapbox GL JS基本停更中老项目维护Cesium叠加Cesium MapboxCesium活跃桥接无官方维护高有大量Cesium业务代码2. 倾斜摄影原始数据到3D Tiles的转换链路2.1 你的原始数据长什么样大多数倾斜摄影项目的原始成果分两种一种是采集完直接处理的另一种是别人给的原生格式数据。做倾斜摄影采集的软件比较多ContextCapture现在叫iTwin Capture、大疆智图、Metashape、OpenDroneMap都有可能。这些软件输出的原始成果通常是OSGB格式一个大的Data目录下面套着Tiles层级里面全是小瓦片数据结构很庞杂浏览器根本没法直接用。关键点在于转换工具对输入格式非常敏感。不同软件导出的目录结构、坐标系基准、坐标单位都不同参数配错了后面在Mapbox里加载就会遇到模型跑偏的问题。2.2 各种转换路径怎么选我整理了几条亲测有效的转换路径。最省事的方式是在处理软件里直接导出3D Tiles格式ContextCapture的导出选项里就带3D Tiles大疆智图新版也支持直接导出b3dm。如果你拿到的只有OSGB旧数据那就需要走中间转换常见的工具是CesiumLab、osgb23dtiles、或者是智图自带的格式转换功能。转换之后要检查b3dm文件能不能被Cesium或cesiumlab的本地预览服务打开预览能过再接入Mapbox。还有一种情况很常见用户只有shp建筑白模要求做到和倾斜摄影一样的加载效果。这种情况下shp转3dtiles通常先用GIS工具给shp做拉伸成体块再通过CesiumLab的shp转3D Tiles功能生成白模瓦片。这不算倾斜摄影但加载逻辑和数据链路是一样的。2.3 坐标系问题必须在转换阶段就解决这是整条链路里我最想强调的一点。3D Tiles的坐标系设计是右手坐标系z轴向上但当前国内倾斜摄影生产经常用CGCS2000的高斯投影平面坐标y轴还是朝北的x轴朝东和3D Tiles的ENU东北上坐标系不完全对应更不用提和Mapbox的Web Mercator坐标系差了十万八千里。坐标系问题不能在渲染层硬掰最好在转换阶段就处理到位。理想状态下转换前先确认原始数据的地理参考是WGS84经纬度坐标高程用的是WGS84椭球高而不是85高程。如果原始数据是地方坐标系建议先用专业GIS软件做坐标转换把数据输出成EPSG:4978或者EPSG:4326再生成3D Tiles。否则你在前端该怎么猜都猜不准偏移量因为不同城市的坐标偏移根本不是线性规律。注意别只看tileset.json里写着4326就以为没问题实际3D Tiles内部大量使用地心坐标系数据转换工具如果处理不当你拿到的b3dm内部坐标并不一定是标准的地心坐标最后渲染层还要再套一层变换才能对上。3. Mapbox token与地图初始化千万别在这些细节上翻车3.1 token申请与本地开发环境Mapbox的注册流程不复杂到官网注册账号进Dashboard创建一个Access Token。用默认的public token就行注意不要把secret token泄露到前端代码里。本地开发直接用localhost跑默认token的URL限制不会拦你但如果你要部署到测试环境记得在token设置里把允许访问的域名加好否则线上突然打不开底图排查半天发现是token白名单的问题。很多人为了绕开Mapbox的token限制想用本地瓦片服务或者天地图底图替代这种思路没问题但意味着相机同步、样式解析都需要自己搞一套工作量远大于注册一个token。非内网项目老老实实注册内网项目可以用Mapbox的开源样式自定义离线瓦片只是后续配起来麻烦一些。3.2 基础地图的相机参数要按三维场景来设置地图初始化看起来简单但几个参数直接影响3D Tiles的展示效果。最容易被忽略的是pitch俯仰角默认的0度是俯视视角模型会缩成一团看不出来立体感。做倾斜摄影展示一般把pitch设到45到70度之间接近人眼观察角度。另外antialias参数要打开否则模型边缘锯齿感明显。这个参数在WebGL上下文里控制是否开启抗锯齿默认是false开启后对画面提升很明显。我把初始化代码列一下这是可以直接抄的版本import mapboxgl from mapbox-gl; import mapbox-gl/dist/mapbox-gl.css; mapboxgl.accessToken pk.这里是你的token; const map new mapboxgl.Map({ container: map, style: mapbox://styles/mapbox/satellite-v9, center: [拾取的中心经度, 拾取的中心纬度], zoom: 15, pitch: 60, bearing: 0, antialias: true });style建议选satellite-v9或者dark-v11。带路网和poi的默认样式会干扰模型展示卫星图做底图叠加建筑的实景效果最自然。center和zoom先随便填一个模型的大致位置后面加载成功后再用相机flyTo精准定位。3.3 别忘了加resize处理这是个特别基础但是特别容易踩的坑。如果你把地图放在一个会变化的容器里比如弹窗、折叠面板、抽屉路由切换之后容器尺寸变了Mapbox不知道画布变大了画面会变成模糊的截断状态。需要在容器尺寸变化之后手动调一次setTimeout(() map.resize(), 200);200毫秒是为了等容器动画完成。如果你有容器尺寸变化的监听器直接在里面调这个。4. 核心代码实现用deck.gl把3D Tiles挂进Mapbox4.1 安装依赖这里用的是deck.gl的Tile3DLayer它底层是基于loaders.gl的3D Tiles解析器可以把b3dm文件转换成deck.gl能渲染的图层。依赖包有不少但都是标准包直接装npm install mapbox-gl deck.gl/core deck.gl/mapbox deck.gl/geo-layers deck.gl/layers4.2 在Mapbox上添加Tile3DLayer安装完之后核心代码非常简洁。先实例化Mapbox地图等load事件触发后通过MapboxLayer这个桥接类把deck.gl图层注册到Mapbox的图层树里。Tile3DLayer的data直接指向你的tileset.json地址支持相对路径和绝对URL也可以传一个返回promise的函数动态加载import { MapboxLayer } from deck.gl/mapbox; import { Tile3DLayer } from deck.gl/geo-layers; map.on(load, () { map.addLayer( new MapboxLayer({ id: photogrammetry-layer, type: Tile3DLayer, data: /data/3dtiles/tileset.json, loadOptions: { fetch: { headers: { // 如果服务端有鉴权或跨域要求在这里配置 } } } }) ); });这里最需要注意的就是跨域问题。做本地demo的时候直接用Vite或Webpack的devServer代理把3D Tiles目录代理到前端项目下避免出现CORS拦截。我把写死的文件路径放在本地静态资源目录里开发时省了很多麻烦。如果模型文件量很大几十GB部署时单独起一个静态文件服务然后用nginx统一代理也别忘了配跨域响应头。加载完成之后Mapbox的相机视角操作会和deck.gl层的渲染自动同步不需要手动挂载事件这是桥接类帮我们做掉的。你用Mapbox的rotate、pitch、zoom3D Tiles都会跟着一起转。4.3 模型位置不对怎么校正onTilesetLoad与modelMatrix多数情况下模型数据转换得当的话加载进Mapbox会落在正确的地理位置上。但如果原始数据坐标系处理时出现了偏差模型可能出现在海里、别的城市或者悬在半空中这时候就要在渲染层做矩阵修正。Tile3DLayer提供了一个onTilesetLoad回调它能拿到tileset实例它的modelMatrix是4x4矩阵直接控制整个模型的平移、旋转和缩放。我处理偏移问题时常用的做法是先获取模型的实际中心坐标和期望落点坐标计算两个位置在WGS84下的差值转成平移矩阵import { Matrix4 } from math.gl/core; onTilesetLoad: (tileset) { // 期望模型中心东经120.1北纬30.2高度200米 // 实际模型中心东经120.0北纬30.1高度50米 // 根据偏差构造平移量 const dx (120.1 - 120.0) * 111320; const dy (30.2 - 30.1) * 110540; const dz 200 - 50; tileset.modelMatrix new Matrix4().translate([dx, dy, dz]); }注意这个dx dy dz的单位是米经纬度转米的公式是近似值如果你的项目精度要求高还是建议用专业的GIS库比如proj4js或者turf做投影换算或者直接用CesiumLab这类工具在数据端把坐标系修正掉。我这里给的是应急处理方案属于渲染层兜底真正的根治办法仍然是把数据转换做对。5. 模型乱飞、发黑、被遮挡常见故障的定位思路5.1 模型整体偏移几百米甚至几公里这个是我遇到最多、也最坑的问题。表面上看tileset.json能加载b3dm也正常请求了但模型就是没落在expected的位置上。排查思路从简到繁分三步走。第一步先用浏览器开发者工具打开tileset.json看root节点的transform数组。3D Tiles的设计里根节点可以带一个transform表示整个瓦片的局部坐标系到上一层坐标系的变换很多转换工具会把地方坐标信息塞进去。如果你在Mapbox上看到的模型位置和真实位置差了很远先把这个transform记下来。第二步确认原始数据的高程基准。倾斜摄影常用的高程基准有两种WGS84椭球高和1985国家高程基准。两者在某些地区能差几十米如果数据源是85高程你在Mapbox上看到模型悬浮在空中或者陷入地下大概率就是这个原因。处理办法是数据端重新导出时改成WGS84椭球高或者在模型矩阵里加上一个固定的垂直偏移。第三步如果偏移量是非恒定值比如一部分地方偏了100米另一部分偏了200米那基本可以断定数据自身是地方坐标系没有做精确的七参数转换。这个没法在渲染层弥补必须回到转换工具里重新处理坐标参考。5.2 模型整体发黑或者贴图全丢看起来像材质丢了的问题通常和3D Tiles的纹理加载机制有关。b3dm内部通常会引用纹理图片加载的时候会根据相对路径去服务端拉图片。如果相对路径在转换工具里写得不对或者你在部署的时候把目录结构调整了图片就会404模型自然就变成白模或者灰模。打开开发者工具的Network面板筛选图片和b3dm请求看看有没有404。如果有把tileset.json所在的目录和纹理资源的相对位置调成一致或者把整个3D Tiles目录原样部署到服务器不做任何目录结构层面的改动。还有一种发黑情况是渲染环境没光照导致的deck.gl默认对3D Tiles使用PBR光照如果你的数据模型没有法线信息屏幕上看就是一片黑这种只能回原始软件重新生成法线。重要提示3D Tiles目录部署后尽量不要用压缩软件重新打包上传很多可视化工具在打包过程中会把目录结构、文件大小、json中的相对路径改掉。我见过太多因为为了传百度网盘方便压了个zip导致全盘404的案例建议直接用官方导出的目录结构。5.3 模型直接被地形或者底图盖住Mapbox官方地形DEM瓦片默认是不打开的所以很多人根本没意识到自己有地形遮挡的问题。但如果你为了效果开了地形比如添加了hillshade或用了map.setTerrain()那低矮区域的模型就会被地形埋进去看起来像是只显示了一半。解决思路有两个。一是直接把地形关掉倾斜摄影模型自带高程信息不需要底图再叠一层DEM。二是把模型抬高一个固定值让模型底部浮在地形上方但这样会让底部出现悬空缝隙不太好看。实际项目里我一般选择切掉地形毕竟倾斜摄影模型自身精度比Mapbox的全局DEM高得多。5.4 模型加载后闪跳、掉帧闪跳的本质是LOD切换太频繁。deck.gl的Tile3DLayer里有一个maximumScreenSpaceError参数控制屏幕空间误差阈值默认值是16这个值越小LOD越精细但请求数和渲染压力也越大。如果你的模型文件比较大频繁切换精细层和粗糙层就会出现跳变感。按我的经验处理策略是把该参数调到24到32之间让视点离得比较远的时候切粗模靠近再加载精模。如果你的模型是给领导汇报用的对细节要求不高可以继续调大到48性能提升非常明显。另外如果模型实在太大可以在转换阶段做纹理压缩或者限制最大瓦片加载深度。在deck.gl里用一个onTileLoad回调可以看到每个瓦片的信息也可以借此确认是否有一直重复请求的瓦片。6. 性能优化和多模型融合的实测经验6.1 多个tileset同时挂载一个倾斜摄影demo大概率不会只有一栋楼往往是一片区域里有好几个区块的模型。最直观的做法是循环调用map.addLayer为每个tileset创建一个独立的MapboxLayerid不能重复互不影响。但实测下来如果同时挂载超过五六个大tileset显存占用会明显上升页面也会变卡。更好的做法是让数据端把这些tileset合并成一个根节点或者在渲染端用视距裁剪只有相机靠近时才添加对应区域的图层。我自己写了一个按视野范围动态变化的加载逻辑监听Mapbox的moveend事件根据当前相机中心坐标和视野半径判断模型离得近离得远再决定要不要加载和销毁对应图层。这样虽然代码复杂了一点但体验比一次性全部加载好得多。6.2 shp转出来的白模和倾斜摄影融合有相当多的场景是倾斜摄影模型只覆盖了局部其他区域用shp拉伸出来的白模补充。两者叠加在Mapbox上时要注意图层顺序。MapboxLayer本质上是插入到Mapbox自定义图层槽位里的多个图层按添加顺序渲染后添加的会盖在先添加的上面。要让白模作为远景兜底、倾斜摄影作为近景精细层先加白模图层再加倾斜摄影图层。shp转3D Tiles白模还有一个常见问题shp里的每个建筑要素默认没有高度属性生成的白模是平的或固定高度。需要在转换工具里指定高度字段或者在生产shp的时候就给每个面加上层数属性。CesiumLab的shp转换参数里就有高度字段这一项要用起来。6.3 在无底图环境下的部署思路最后说一个做政企项目经常遇到的情况客户要求内网部署不能访问Mapbox公共服务器。这种情况下Mapbox的基础底图也要换成内部数据。Mapbox GL JS本身支持自定义style里的sources指向内部瓦片服务比如ArcGIS Server发布的瓦片或者GeoServer的WMTS渲染逻辑不变只是把底图源换掉。3D Tiles的加载完全不受影响因为Tile3DLayer走的是独立的数据源。线上部署的时候还有一点值得注意如果整个站点使用nginx代理3D Tiles的路径要做成相对稳定的路由不要用带版本号的绝对路径否则客户端缓存和nginx缓存策略容易错乱。这一点是二次上线时领导发现模型加载越来越慢才暴露出来的当时排查了很久。这里面的核心逻辑是Mapbox承载底图与交互deck.gl承载3D Tiles的流式解析与渲染两者各司其职。跑通demo不难难的是在项目里把坐标系理清、把性能调到可接受范围。我做这个项目的最终体会是花在数据转换和坐标系对齐上的时间远比写渲染代码的时间多。如果你正准备做类似的功能第一步前一定先问清楚数据的坐标系和转换工具的参数这个坑绕过去了后面基本一路顺畅。一个小技巧分享给你正式接入Mapbox前先用CesiumLab的本地预览把tileset.json打开看一眼数据能在Cesium里正常显示再往Mapbox里接能省掉一半的排查时间。本文还有配套的精品资源点击获取