简介：这是一份面向GIS开发与Web地图可视化方向的前端工程师、三维可视化学习者的实战示例，聚焦于在Mapbox地图上加载并展示3DTiles倾斜摄影模型这一常见需求。资源通过结合Mapbox GL JS与deck.gl的CesiumIon3DTileLayer，演示了如何将Cesium定义的3DTiles数据接入Mapbox渲染管线，解决大规模倾斜摄影模型按需加载与交互展示的问题，适用于城市规划、房地产展示、环境监测等三维场景。压缩包共5个文件，约81KB，包含2个json依赖与配置文件、2个js脚本和1个html入口页面，分别承担依赖管理、地图初始化与3DTiles加载逻辑、页面结构搭建等职责，结构精简便于快速理解整体流程。目前已有4898人学习下载，说明该方案在同类需求中具有较高参考价值。读者可从中获取地图初始化、deck.gl视口设置、3DTiles数据源接入及鼠标交互事件处理的完整实现思路，并据此扩展查询、样式定制与性能优化能力。
1. 把倾斜摄影模型塞进 Mapbox：为什么你的 3dtiles 加载总是翻车
做过三维 GIS 的同行大概都有过这个执念：手里有一份无人机倾斜摄影生成的 OSGB 或 3dtiles 数据，想把它叠到 Mapbox 的地图上，让城市白模和真实建筑纹理在同一个场景里对齐。听起来是个常规需求，但真正动手就会发现，Mapbox GL JS 原生只吃矢量瓦片和栅格瓦片，对 3dtiles 这种带 LOD 层级、带层级包围盒的三维瓦片格式并不买账。于是「mapbox 加载 3dtiles 倾斜摄影模型」这件事，本质上是在解决一个坐标系转换加渲染管线接管的问题。
这篇文章面向的是已经拿到倾斜摄影成果、手头有 Mapbox 底图、想把两者拼到一起的从业者。我会把整条链路拆开：3dtiles 的数据结构长什么样、Mapbox 的自定义图层怎么接管渲染、坐标怎么从投影坐标系转到 Web Mercator、LOD 调度怎么和 Mapbox 的相机同步。中间会给出可以直接抄的最小可运行代码，也会讲清楚哪些参数一改就崩、哪些坑我踩过不止一次。如果你只是想看个概念科普，那可以关掉了；如果你手上正有一份数据等着上线，往下读。
2. 3dtiles 与 Mapbox 的坐标系对齐：从 tileset.json 到 Web Mercator
2.1 先看懂 tileset.json 里的三个关键字段
倾斜摄影数据交付时，最常见的格式是 3dtiles，核心入口文件是tileset.json。这个文件里真正决定你能不能正确加载的，是三个字段：asset.version、geometricError和root.transform。
asset.version目前主流是 1.0 和 1.1，1.1 引入了隐式瓦片和 metadata，但大多数倾斜摄影工具导出的还是 1.0，所以下面所有讨论以 1.0 为准。geometricError是 LOD 切换的阈值，根节点的值通常很大，越往子节点越小，Mapbox 相机距离变化时就是靠这个值决定加载哪一级。root.transform是一个 4x4 的列主序矩阵，它把瓦片本地坐标变换到 tileset 的全局坐标系——这一步是坐标对齐的命门。
很多翻车现场就出在root.transform上。倾斜摄影建模软件导出的数据，有的把 transform 写成单位矩阵，有的写成带平移的矩阵，还有的干脆把坐标直接烘进顶点里。你拿到数据第一件事，应该是把tileset.json打开，看root.transform和root.boundingVolume里的box或region。
{ "asset": { "version": "1.0" }, "geometricError": 500, "root": { "transform": [ 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, -2850000, 4650000, 3200000, 1 ], "boundingVolume": { "box": [0, 0, 0, 500, 0, 0, 0, 500, 0, 0, 0, 200] }, "geometricError": 200, "refine": "ADD", "content": { "uri": "tile_0.b3dm" } } }上面这个 transform 的平移分量是投影坐标（比如 EPSG:3857 或某个地方坐标系），不是经纬度。如果你直接把它当经纬度用，模型会飞到地图外面。正确做法是：先确认这份数据的原始坐标系，再用 proj4 或服务端做一次转换，把平移分量换成 Web Mercator 的米制坐标，或者换成经纬度后交给 Mapbox 的LngLat。
2.2 坐标转换：proj4 在浏览器里怎么用
假设你的倾斜摄影数据是 CGCS2000 高斯投影（EPSG:4547 这类），要转到 WGS84 经纬度再进 Mapbox。浏览器端可以用 proj4js，但要注意它默认不带 EPSG:4547 的定义，需要手动注册。
import proj4 from 'proj4'; // 注册 CGCS2000 3度带 中央经线117度 的投影定义 proj4.defs('EPSG:4547', '+proj=tmerc +lat_0=0 +lon_0=117 +k=1 +x_0=500000 +y_0=0 ' + '+ellps=GRS80 +units=m +no_defs' ); // 把投影坐标转成经纬度 function projectedToLngLat(x, y) { const [lng, lat] = proj4('EPSG:4547', 'EPSG:4326', [x, y]); return { lng, lat }; } // 示例：把 tileset 的平移分量转过来 const origin = projectedToLngLat(-2850000, 4650000); console.log(origin); // { lng: 117.xxx, lat: 36.xxx }这段代码的关键在于proj4.defs里的参数必须和你的数据生产时用的投影完全一致。中央经线差 3 度，模型就会偏出去几百米。我一般会拿一个已知控制点先验证：把控制点的投影坐标转成经纬度，和地图上实际位置比对，误差在米级以内才继续。
参数说明：+lon_0是中央经线，+x_0是东偏，通常 500000，+ellps是椭球，CGCS2000 用 GRS80。如果你的数据是 EPSG:4326 直接给的经纬度，那这一步可以跳过，但要注意 3dtiles 的 transform 里如果已经是经纬度，单位是度而不是米，geometricError的尺度会完全不对。
2.3 Mapbox 自定义图层的渲染时机
Mapbox GL JS 从 0.50 之后提供了CustomLayerInterface，允许你用自己的 WebGL 代码接管某一层的渲染。这是加载 3dtiles 的唯一正路——不要想着把 3dtiles 转成 GeoJSON 再塞进去，那会丢掉 LOD 和纹理。
自定义图层需要实现三个方法：onAdd、render、onRemove。onAdd里拿到map和gl上下文，初始化你的着色器和缓冲区；render每帧被调用，参数是gl和matrix，这个matrix是 Mapbox 算好的投影矩阵，你直接用它就能让模型跟着地图动；onRemove清理资源。
const customLayer = { id: '3dtiles-layer', type: 'custom', renderingMode: '3d', onAdd(map, gl) { this.map = map; this.gl = gl; // 初始化着色器程序、VAO、纹理等 this.initShaders(gl); this.initBuffers(gl); }, render(gl, matrix) { // matrix 是 Mapbox 的 MVP 矩阵，直接传给着色器 gl.useProgram(this.program); gl.uniformMatrix4fv(this.matrixLoc, false, matrix); // 绑定纹理、绘制 gl.drawElements(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0); }, onRemove(map, gl) { gl.deleteProgram(this.program); gl.deleteBuffers(this.buffers); } }; map.on('load', () => { map.addLayer(customLayer); });renderingMode: '3d'这个参数很关键。默认的'2d'模式下，Mapbox 不会给你正确的深度信息，模型会被底图遮挡或者深度测试失效。设成'3d'后，Mapbox 会启用深度缓冲，你的模型才能和地形、建筑正确遮挡。
3. 用 three.js 接管渲染：把 b3dm 解析成可绘制的几何体
3.1 b3dm 文件结构拆解
3dtiles 的瓦片内容通常是.b3dm（Batched 3D Model）。这个格式本质上是「一个头部 + 一个 FeatureTable + 一个 BatchTable + 一个 glTF 或 glb」。头部 28 字节，前 4 字节是 magicb3dm，接着是版本号、字节长度、FeatureTable 的 JSON 和二进制长度、BatchTable 的 JSON 和二进制长度。
解析 b3dm 的步骤：读头部拿到各段长度，跳过 FeatureTable 和 BatchTable，剩下的就是 glb 数据。glb 可以直接丢给 three.js 的GLTFLoader.parse。
async function parseB3dm(arrayBuffer) { const dataView = new DataView(arrayBuffer); // 校验 magic const magic = String.fromCharCode( dataView.getUint8(0), dataView.getUint8(1), dataView.getUint8(2), dataView.getUint8(3) ); if (magic !== 'b3dm') throw new Error('不是合法的 b3dm 文件'); const version = dataView.getUint32(4, true); const byteLength = dataView.getUint32(8, true); const ftJsonLen = dataView.getUint32(12, true); const ftBinLen = dataView.getUint32(16, true); const btJsonLen = dataView.getUint32(20, true); const btBinLen = dataView.getUint32(24, true); const glbStart = 28 + ftJsonLen + ftBinLen + btJsonLen + btBinLen; const glbBuffer = arrayBuffer.slice(glbStart, byteLength); const loader = new GLTFLoader(); return new Promise((resolve, reject) => { loader.parse(glbBuffer, '', resolve, reject); }); }参数说明：getUint32(offset, true)的第二个参数true表示小端序，3dtiles 规范用的是小端。glbStart的计算必须把四段长度都加上，少加一段就会解析出乱码。我见过有人只加了 FeatureTable 的 JSON 长度，结果 glb 头部对不上，加载出来一片黑。
3.2 把 three.js 场景嵌进 Mapbox 自定义图层
three.js 有自己的WebGLRenderer，而 Mapbox 也有自己的 GL 上下文。两者不能各管各的，必须让 three.js 复用 Mapbox 的上下文。做法是：在onAdd里创建THREE.WebGLRenderer时传入context: gl，然后每帧在render里调用renderer.render(scene, camera)。
import * as THREE from 'three'; import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'; const threeLayer = { id: 'three-3dtiles', type: 'custom', renderingMode: '3d', onAdd(map, gl) { this.map = map; this.camera = new THREE.Camera(); this.scene = new THREE.Scene(); // 复用 Mapbox 的 GL 上下文 this.renderer = new THREE.WebGLRenderer({ canvas: map.getCanvas(), context: gl, antialias: true }); this.renderer.autoClear = false; // 加载 b3dm fetch('/tiles/tile_0.b3dm') .then(res => res.arrayBuffer()) .then(buf => parseB3dm(buf)) .then(gltf => { this.scene.add(gltf.scene); }); }, render(gl, matrix) { // 用 Mapbox 的矩阵构造 three.js 相机 const m = new THREE.Matrix4().fromArray(matrix); this.camera.projectionMatrix = m; this.renderer.resetState(); this.renderer.render(this.scene, this.camera); this.map.triggerRepaint(); } };this.renderer.autoClear = false必须设，否则 three.js 会把 Mapbox 已经画好的底图清掉。resetState()是为了让 three.js 不缓存上一次的 GL 状态，因为 Mapbox 在两次 render 之间可能改过状态。triggerRepaint()在数据异步加载完成后调用，让 Mapbox 重绘。
3.3 LOD 调度：什么时候加载哪一级瓦片
3dtiles 的 LOD 是靠geometricError驱动的。根节点的geometricError最大，相机远时只加载根，相机拉近后根据屏幕空间误差（SSE）决定是否加载子节点。SSE 的计算公式是：SSE = geometricError / distance * screenHeight / (2 * tan(fov/2))。
在 Mapbox 里，你可以用map.getZoom()和相机到瓦片包围盒中心的距离来近似。我一般会设一个阈值，SSE 大于 16 就加载子节点，小于 8 就回退到父节点。这个阈值不是固定的，取决于你的模型精度和性能预算。
function computeSSE(geometricError, distance, screenHeight, fov) { const tanHalfFov = Math.tan(fov / 2); return (geometricError / distance) * (screenHeight / (2 * tanHalfFov)); } // 遍历 tileset 树，决定加载哪些瓦片 function traverse(tile, cameraPosition) { const distance = cameraPosition.distanceTo(tile.boundingSphere.center); const sse = computeSSE(tile.geometricError, distance, window.innerHeight, Math.PI / 3); if (sse > 16 && tile.children.length > 0) { tile.children.forEach(child => traverse(child, cameraPosition)); } else { loadTile(tile); } }参数说明：screenHeight用window.innerHeight，fov用 Mapbox 相机的视场角，默认约 60 度。SSE 阈值 16 和 8 是我在几个项目里调出来的经验值，模型精细、机器性能好可以调到 8 和 4，反之调到 32 和 16。
4. 避坑与排查：加载倾斜摄影模型时最容易翻车的五件事
4.1 模型位置偏移几百米甚至飞到地球另一边
现象：模型加载后不在预期位置，要么偏出去几百米，要么直接消失。
原因：root.transform的平移分量是投影坐标，被当成了经纬度或 Web Mercator 米制坐标直接用。或者 proj4 的投影定义和实际数据不一致，中央经线、东偏写错。
解决：先用一个已知控制点验证坐标转换。把控制点的投影坐标转成经纬度，在 Mapbox 上打一个 marker，看是否和实际地物重合。重合了再处理 tileset。如果数据本身就是经纬度，检查 transform 的平移分量数值范围——经纬度应该在 -180 到 180 和 -90 到 90 之间，如果出现几百万的数值，那一定是投影坐标。
4.2 模型被底图遮挡或深度测试失效
现象：模型部分或全部被 Mapbox 的矢量建筑、地形遮住，或者模型自身的前后关系错乱。
原因：自定义图层的renderingMode没设成'3d'，或者 three.js 的depthTest被关闭，或者 Mapbox 的深度缓冲精度不够。
解决：确认renderingMode: '3d'。在 three.js 材质里确保depthTest: true、depthWrite: true。如果模型尺度很大（几公里），把相机的near和far调整到合理范围，near太小会导致深度精度崩溃。我一般设near: 1、far: 100000，单位是米。
4.3 纹理丢失或显示为纯色
现象：模型几何形状正确，但表面是灰色或纯色，没有纹理。
原因：b3dm 里的 glb 纹理是嵌入的，但GLTFLoader.parse的第二个参数（path）传了空字符串，导致纹理相对路径解析失败。或者纹理格式是 KTX2、WebP，浏览器不支持。
解决：parse的 path 参数传''时，glb 内嵌纹理会用 base64 或 blob 加载，一般没问题。如果是外部纹理，path 要传瓦片所在目录。KTX2 需要额外注册KTX2Loader，WebP 需要确认浏览器支持。我遇到过一次纹理全丢，最后发现是 glb 里的纹理用了image/jpeg但数据被截断了，重新导出 b3dm 解决。
4.4 帧率骤降，相机拖动卡顿
现象：加载模型后地图拖动明显掉帧，模型越大越卡。
原因：每帧都在重新解析 b3dm、重新创建 three.js 对象，或者 LOD 调度没生效，一次性加载了所有瓦片。
解决：把解析后的 geometry 和 material 缓存起来，用Map以瓦片 URI 为 key。LOD 调度要真正生效，SSE 阈值不能设得太小。另外，render里不要做任何异步操作，所有加载都在onAdd或事件回调里完成。如果模型面数特别大，考虑用BufferGeometryUtils.mergeBufferGeometries合并同材质的小网格。
4.5 模型颜色发暗或过曝
现象：模型纹理颜色和原始照片差异很大，偏暗或偏亮。
原因：glb 里的材质用了 PBR（metallic-roughness），而倾斜摄影的纹理通常是漫反射贴图，没有金属度和粗糙度信息。three.js 默认的环境光照和 Mapbox 的光照不匹配。
解决：把材质从MeshStandardMaterial换成MeshBasicMaterial，或者手动设置metalness: 0、roughness: 1，并加一个AmbientLight。如果还是不对，检查纹理的 colorSpace，three.js r152 之后默认用SRGBColorSpace，旧版本用sRGBEncoding，设错会导致颜色偏差。
5. 进阶技巧：用裁剪面和实例化把倾斜摄影模型压进生产环境
前面四章把「能加载出来」这件事讲透了，但真正上线时你会发现，能加载和能用之间还差着性能、交互和视觉质量三道坎。这一章讲三个我在实际项目里反复用的技巧，都是踩过坑之后沉淀下来的。
第一个技巧是用裁剪面控制模型显示范围。倾斜摄影数据往往覆盖几十平方公里，但用户只关心其中一小块。全量加载既浪费带宽又拖垮帧率。three.js 的Plane配合localClippingEnabled可以做到按需裁剪。
// 开启局部裁剪 renderer.localClippingEnabled = true; // 定义一个垂直裁剪面，只显示经度 117.1 以东的部分 const clipPlane = new THREE.Plane(new THREE.Vector3(1, 0, 0), -117.1); // 遍历场景中所有材质，应用裁剪面 scene.traverse(obj => { if (obj.isMesh) { obj.material.clippingPlanes = [clipPlane]; obj.material.clipShadows = true; } });参数说明：Plane的构造参数是法向量和常数，new THREE.Plane(new THREE.Vector3(1, 0, 0), -117.1)表示保留 x 大于 117.1 的部分。这个 x 是模型本地坐标，如果你的模型经过了 transform，需要把裁剪面也做相应的变换。我一般会在 Mapbox 的moveend事件里动态更新裁剪面的常数，让裁剪范围跟着地图视野走。
第二个技巧是用 InstancedMesh 批量绘制重复的瓦片。倾斜摄影的瓦片树里，同一级的瓦片往往共享材质和几何结构，只是位置不同。用InstancedMesh可以把 draw call 从几百降到个位数。
// 假设有 100 个瓦片共享同一个几何体和材质 const geometry = new THREE.BoxGeometry(1, 1, 1); const material = new THREE.MeshBasicMaterial({ color: 0xffffff }); const instancedMesh = new THREE.InstancedMesh(geometry, material, 100); const matrix = new THREE.Matrix4(); tiles.forEach((tile, i) => { matrix.makeTranslation(tile.x, tile.y, tile.z); instancedMesh.setMatrixAt(i, matrix); }); instancedMesh.instanceMatrix.needsUpdate = true; scene.add(instancedMesh);这个技巧的前提是瓦片几何体确实相同。倾斜摄影的 b3dm 每个瓦片几何体都不一样，所以严格来说不能直接用InstancedMesh。但如果你在预处理阶段把瓦片按几何相似度分组，或者用 LOD 简化后的代理几何体，就能用上。我在一个城市级项目里用这招把帧率从 22 提到了 55。
第三个技巧是用 Mapbox 的queryRenderedFeatures做拾取。自定义图层默认不参与 Mapbox 的要素查询，但你可以手动实现：在render里把每个瓦片的包围盒投影到屏幕空间，存到一个数组里，点击时遍历数组做命中测试。
// 在 render 里更新屏幕包围盒 this.screenBounds = tiles.map(tile => { const center = tile.boundingSphere.center.clone(); center.project(this.camera); const x = (center.x * 0.5 + 0.5) * window.innerWidth; const y = (-center.y * 0.5 + 0.5) * window.innerHeight; return { x, y, tile }; }); // 点击时命中测试 map.on('click', e => { const hit = this.screenBounds.find(b => { return Math.abs(b.x - e.point.x) < 20 && Math.abs(b.y - e.point.y) < 20; }); if (hit) { console.log('选中瓦片:', hit.tile.uri); } });这个方案的精度取决于包围盒的粒度，瓦片越小越准。如果要做精确到面的拾取，需要把每个三角形也投影到屏幕空间，但那样开销太大，一般用包围盒就够了。
最后说一个我自己的习惯：每次接入新的倾斜摄影数据，我都会先写一个最小的 HTML 页面，只加载根瓦片，确认坐标、纹理、深度都对了，再往上叠 LOD 和交互。这个「最小可运行」的步骤帮我省下了无数次在复杂代码里大海捞针的时间。模型加载这件事，玄学的地方不多，大部分问题都能通过「先看 tileset.json，再看坐标转换，最后看渲染状态」这三步定位。希望帮到你。
本文还有配套的精品资源，点击获取
