简介面向地理信息可视化与 WebGL 地图开发者的 Mapbox 加载 3DTiles 倾斜摄影模型示例聚焦在 Mapbox 底图上展示大规模倾斜摄影数据这一常见需求适合需要快速验证技术路线或搭建演示原型的初中级开发者参考。压缩包共 5 个文件以 2 个 JSON 配置、2 个 JavaScript 逻辑和 1 个 HTML 入口组成整体约 81KB结构轻量便于直接查阅依赖配置、页面挂载与地图渲染之间的组织关系。已有 4901 人学习说明该方向具备较高关注度。内容围绕 Mapbox GL JS 与 deck.gl、CesiumIon3DTileLayer 的协同展开可帮助读者理解 3DTiles 分块加载、地图交互与倾斜摄影模型呈现的基本链路并为进一步优化性能、扩展查询交互或集成更多 GIS 能力提供可复用的参考。1. Mapbox 加载 3D Tiles原生不认 tileset.json得自己搭一层拿到一份倾斜摄影的 OSGB 成果兴冲冲想塞进 Mapbox 里看第一步就撞墙——Mapbox GL JS 的图层体系里压根没有 3D Tiles 这个类型addSource传tileset.json的地址不报错但也永远不会出图。这个 demo 要补的就是这段空白把 Cesium 生态里的 mapbox 3dtiles 倾斜摄影模型挂到 Mapbox 底图上让它跟着地图一起平移、旋转、俯仰而不是另开一个独立的三维窗口。适合谁手上已经有转换好的tileset.json底图是 Mapbox又不愿意为了一个模型把整个前端切到 Cesium 的项目。读完你应该能把模型落到指定经纬度、把 LOD 参数调顺并且在「模型不显示」和「模型飘到天上」这两类最常见的翻车里半小时内定位到原因。2. 三条技术路线custom layer、deck.gl Tile3DLayer 与格式转换的取舍在动手写代码之前先把路线定死。选错了后面全是白工尤其是数据量上到几十上百 GB 的倾斜摄影性能和交互体验的差距会非常明显。2.1 Mapbox GL JS 原生能力的边界在哪先说清楚 Mapbox 自己能干什么。它在三维方向上的原生能力大概是三块fill-extrusion做建筑体块、v3 版本里的model图层加载单个 glTF、以及custom图层对外暴露 WebGL 上下文。前两个跟倾斜摄影基本无关——fill-extrusion是挤出多边形出不来纹理model图层虽然能吃 glTF但它是一个模型一次性加载没有分块调度、没有 LOD 层级、没有视锥剔除。3D Tiles 的规范核心恰恰就在调度上tileset.json描述一棵空间索引树每个节点带geometricError渲染器根据相机距离和屏幕误差决定加载哪一层、卸载哪一层。整片倾斜摄影动辄几千个b3dm不靠这套调度直接全量加载显存会先垮。所以结论很直接Mapbox 缺的不是「渲染三维」的能力是「解析 3D Tiles 并做 LOD 调度」的能力。这一层必须自己补补法有三种。2.2 three.js custom layer控制力最强的一条路custom图层是 Mapbox 留的正经后门接口只有三个回调{ id: 3d-tiles, type: custom, renderingMode: 3d, // 关键让 Mapbox 用 3D 管线做深度处理 onAdd(map, gl) {}, render(gl, matrix) {}, onRemove(map, gl) {} }render(gl, matrix)的第二个参数是个 4x4 的Float32Array含义是「把 Mercator 坐标x、y、z 都在 01 区间变换到裁剪空间」的矩阵。它同时包含了投影和视图信息直接把它塞给 three.js 相机的projectionMatrix相机自身矩阵置单位阵两套坐标系就对齐了。3D Tiles 的解析交给 three.js 生态里的3d-tiles-renderer它负责请求tileset.json、解析b3dm、管理 LOD 队列和内存释放对外只暴露一个group让你挂到场景里。这条路的代价是你要自己写坐标变换——ECEF 到 Mercator 的那套矩阵得自己推好处是所有参数都在手里模型在哪个经纬度、朝哪个方向、缩放多少全都能控。2.3 deck.gl Tile3DLayer 与「转成 glTF」的适用场景deck.gl的Tile3DLayer配合Tiles3DLoader也能读 3D Tiles代码量小很多几行就能出图。它的问题在交互层deck.gl 自己维护一套相机和 Mapbox 的transform是两套东西俯仰角度大或者 zoom 很高的时候容易出现模型和底图对不齐、拖拽时轻微延迟的情况。做数据看板、做大屏展示够用做需要精确贴地的测绘类应用就得反复调。第三条路是把模型转成 glTF 或者 3D 瓦片以外的东西再用model图层加。这条路只在模型很小的时候成立——单栋楼、单个桥墩、单个设备构件几十 MB 以内转了也就转了。整片倾斜摄影转成单个 glTF 会变成一个几 GB 的文件浏览器解析阶段就崩了。路线实现成本LOD 调度贴地精度适用体量three.js custom layer高要写坐标变换完整支持可控能做到米级几 GB 到几十 GBdeck.gl Tile3DLayer低完整支持大俯仰角下需调试中等体量转 glTF model 图层低无取决于转换精度几十 MB 以内我一般会先问一句这模型要跟底图严格对齐吗要就走 custom layer只是展示deck.gl 更省事。3. 倾斜摄影数据准备OSGB 到 3D Tiles 的目录结构与 tileset.json 体检拿到手的往往是一堆Tile_000_000.osgb和几个metadata.xml。这套东西浏览器不会解析得先变成tileset.json加一堆b3dm。转换本身是一次性的活但转换出来的东西合不合格决定了后面调试要花多久。3.1 OSGB 空三成果到 b3dm 的产物形态空三软件导出的倾斜摄影成果典型结构是分块的每一块放在Data/Tile_xxx_xxx/下里面有若干.osgb和.jpg纹理根目录一个metadata.xml记录坐标系和范围。坐标一般是工程坐标系或者带带号的投影坐标转换工具通常需要你指定一个「中心点」把它换算成经纬度作为 ECEF 到局部坐标的锚点。转换完成后应该得到这样的结构tiles/ ├── tileset.json ├── 0/ │ ├── 0.b3dm │ ├── 1.b3dm │ └── ... └── 1/ └── ...几个必须确认的点b3dm的纹理是内嵌的还是外挂的不同转换工具做法不一样外挂的在部署时容易漏拷tileset.json的根节点有没有transform字段geometricError的量级是不是米制常见值是几十到几百如果看到0.0001这种就该警觉说明单位换算错了。3.2 tileset.json 里必须逐项确认的四个字段打开tileset.json前两百行足够判断数据能不能用。字段期望值不对会怎样asset.version1.0或1.1版本过高时解析器可能拒绝加载geometricError根米制通常 50500过小会一次性拉满所有瓦片过大则永远只加载最粗层root.transform16 个数的数组列主序ECEF 单位缺失说明数据在局部坐标需要自己补锚点root.boundingVolumeregion或box只有sphere时部分渲染器剔除不准会出现「转个角度模型消失」transform字段最容易出问题。3D Tiles 规范里它是列主序存储的 4x4 矩阵[0..3]是第一列而不是第一行。做矩阵乘法的时候如果按行主序拼接后面的坐标变换就会整段失效。提示想看根节点有没有transform用一行命令就够别手动翻文件。node -e const jrequire(./tiles/tileset.json);console.log(geometricError:, j.geometricError);console.log(transform:, j.root.transform ? yes : no);console.log(boundingVolume:, Object.keys(j.root.boundingVolume).join(,))输出里geometricError是根节点级别的它决定了整个模型的初始精度root.geometricError是叶子层级的最小误差两个值不能颠倒。如果transform: no说明所有b3dm顶点都是相对某个局部原点的那你必须在代码里自己补一个 ECEF 变换否则模型会跑到地心去。3.3 用脚本做一次瓦片完整性体检转换为失败得很隐蔽——tileset.json生成成功但某些分块的b3dm没输出全前端表现就是飞到一个角度突然缺一块。上百个节点手动点不现实写个脚本走一遍。// check-tileset.mjs import fs from node:fs; import path from node:path; const root process.argv[2] || ./tiles; const json JSON.parse(fs.readFileSync(path.join(root, tileset.json), utf8)); let nodes 0; let missing 0; let maxDepth 0; function walk(node, depth) { nodes; maxDepth Math.max(maxDepth, depth); // content.uri 可能带 URL 编码先解码再判断 const uri node.content?.uri; if (uri) { const file path.join(root, decodeURIComponent(uri)); if (!fs.existsSync(file)) { missing; if (missing 10) console.log(缺失:, uri); } } (node.children || []).forEach((c) walk(c, depth 1)); } walk(json.root, 0); console.log(节点总数 ${nodes}最大层级 ${maxDepth}缺失内容 ${missing});脚本做三件事递归遍历整棵索引树、统计节点数和最大深度、逐个校验content.uri指向的文件是否真实存在。参数root传 tileset 所在目录默认./tiles。输出里的「最大层级」很有参考价值——超过 20 层的树LOD 调度器在移动端基本跑不动得考虑砍层级缺失数不为 0 的话别急着写前端先回去补转。跑完确认没问题再用 HTTP 服务起起来。注意这里不能用file://直接打开 HTMLfetch会被同源策略拦住。# Python 起一个带 CORS 的静态服务方便本地调试 python3 -m http.server 8080 --directory ./tiles--directory指定根目录这样tileset.json里的相对路径0/0.b3dm就能被正确解析。如果模型放在别的域名下服务端必须带Access-Control-Allow-Origin否则浏览器控制台会刷一片 CORS 错误而页面本身什么都不显示——这是新手最容易卡住的地方。4. Custom Layer 落地从 ECEF 到 Mercator 的矩阵与 LOD 相机这一章是核心。坐标系这套东西一旦错了表现往往不是报错而是模型不见、模型变形、模型疯狂闪烁全靠猜。所以我把矩阵推导和双相机结构拆开写。4.1 初始化复用 Mapbox 的 WebGL 上下文Mapbox 已经把 WebGL 上下文建好了three.js 必须复用它不能再new一个 canvas。import * as THREE from three; import { TilesRenderer } from 3d-tiles-renderer; const MODEL_ORIGIN [118.123456, 32.654321]; // 模型中心经纬度按实际数据填 const MODEL_HEIGHT 0; // 模型底部相对椭球面的高度单位米 class TilesCustomLayer { constructor(map, tilesetUrl) { this.map map; this.url tilesetUrl; this.camera new THREE.PerspectiveCamera(); this.lodCamera new THREE.PerspectiveCamera(); this.scene new THREE.Scene(); this.renderer null; this.tiles null; } onAdd(map, gl) { this.renderer new THREE.WebGLRenderer({ canvas: map.getCanvas(), context: gl, antialias: true, }); // 共享上下文时不能让 three.js 自己清屏会擦掉 Mapbox 的底图 this.renderer.autoClear false; this.renderer.setPixelRatio(1); // 渲染相机不参与矩阵计算只负责投影 this.camera.matrixAutoUpdate false; // 场景加一点点环境光b3dm 的材质一般是 PBR没有光会漆黑 this.scene.add(new THREE.AmbientLight(0xffffff, 1.6)); const dir new THREE.DirectionalLight(0xffffff, 1.2); dir.position.set(1, 1, 1); this.scene.add(dir); this.tiles new TilesRenderer(this.url); this.tiles.errorTarget 12; // 屏幕空间误差阈值越小越精细 this.tiles.maxDepth 18; // 防止深层瓦片把内存吃光 this.tiles.setCamera(this.lodCamera); this.scene.add(this.tiles.group); // 加载完成后统一算一次矩阵避免每帧重算 this.tiles.onLoadTileset () this.buildTransform(); } buildTransform() { // 见 4.2 } render(gl, matrix) { // 见 4.3 / 4.4 } }几个参数值得说清楚。errorTarget是屏幕空间误差的像素阈值调小模型更精细但加载更慢调大则相反倾斜摄影场景一般 816 之间手感比较平衡。maxDepth是硬性层级上限用来兜底——有些转换工具生成的树会一直往下钻不限制的话显存增长很快。renderer.autoClear false这行不能省。three.js 默认每帧自己清一次颜色和深度缓冲共享上下文时这一清就把 Mapbox 已经画好的底图抹掉了表现是「只有模型底图全黑」。4.2 坐标链ECEF → ENU → Mercator 的矩阵拼装3D Tiles 的顶点数据经过根节点transform之后落在 ECEF地心地固坐标系里原点在地球质心单位是米。而 Mapbox 的render(gl, matrix)期待的是 Mercator 坐标原点在西南角x、y、z 都在 01 之间单位是无量纲的。中间要过一道 ENU东-北-天局部坐标系以模型中心为原点x 指向东、y 指向北、z 指向天顶。这一步既把平移归零也把「米」换算成 Mercator 单位。而 Mercator 的 z 轴也是本文还有配套的精品资源点击获取