简介：面向GIS开发者的SuperMap iClient for 3D平面场景二三维一体化浏览资源包，用于实现二维三维地图在同一平台的无缝切换，帮助解决传统GIS中二三维视角分离、空间信息表达不直观的问题，可应用在城市规划、环境分析、交通管理等专业场景。资源共18个文件，压缩包约18.9MB，主要包含js脚本、html演示页面、udd/udb空间数据文件以及docx说明文档，分别覆盖前端调用、示例工程、地理数据和开发说明。已有445人学习，适合有一定SuperMap基础、正在学习三维GIS开发的初中级工程师。通过学习该包，可掌握数据处理与融合、三维建模、交互操作、性能优化（如LOD）、用户体验及跨平台兼容性等关键技术，借助示例代码能快速搭建二三维一体化浏览原型。资源以SuperMap iClient经典示例为基础，兼顾概念讲解和工程实践，可直接复用其中代码片段，有助提升GIS开发效率。
1. 项目概述与需求定位
最近在做一个WebGIS项目，用户既想要传统二维地图的简洁交互，又想要三维场景的直观体验。折腾了一圈，最后落地用的是SuperMap iClient for 3D来做“平面场景二三维一体化浏览”，也就是同一个业务界面里面，左边二维地图、右边三维场景，两边联动浏览、同步定位。这里把整个项目的设计思路、落地细节和踩坑过程完整梳理一遍。
这类需求在GIS行业里太常见了。比如做智慧园区的时候，运维侧需要二维平面图快速定位到具体楼栋，再跳转到三维场景看楼宇外观、管线走向。如果做成两个独立的系统，用户就得在两套界面之间来回切换，操作成本很高。二三维一体化浏览的核心价值，就是把二维地图的“轻”和三维场景的“重”融入同一个交互闭环：二维负责宏观定位，三维负责微观呈现，两者通过坐标和视角联动无缝衔接。
1.1 这个项目解决什么问题
这里要明确，所谓“二三维一体化”，并不是简单地把一张二维地图和一个三维地球摆在一个页面里，而是要做到以下几点：
- 视点同步：二维地图移动中心点，三维场景相机跟着飞到对应位置；反过来旋转三维视角，二维地图同步缩放到相同区域。
- 图层关联：二维矢量图层和三维模型图层共享同一套数据源，选中某个地物时两边同时高亮。
- 操作互补：支持在二维图上框选范围，三维场景直接保留该范围的三维要素，再做空间量算、剖切等分析。
1.2 技术选型：为什么选SuperMap iClient for 3D
市面上的三维WebGIS方案不少，Cesium、Leaflet+Three.js、MapboxGL+deck.gl等都能做类似效果。选SuperMap iClient for 3D，最主要的考虑是项目底层数据源是SuperMap iServer发布的服务，iClient for 3D对自家的REST服务、S3M三维缓存格式支持是最完善的，起码省掉了大量格式适配的工作量。
另一方面，iClient for 3D本身封装了Cesium，在具备Cesium生态优势的同时，提供了大量GIS能力：比如多源数据叠加（地形、影像、矢量、模型、点云）、三维空间分析（通视、剖面、淹没），以及非常方便的Layer和Scene模型管理。这些能力如果用原生Cesium从头写，工作量会大很多。如果你项目里的数据主要是ArcGIS或自研服务，那完全可以选Cesium或MapboxGL；但如果你已经跑在SuperMap体系里，iClient for 3D基本是成本最低、见效最快的路线。
2. 整体设计思路：双向联动的核心机制
二三维一体化的技术难点不在“画两个地图”，而在于“两个视图如何基于同一套地理语义保持同步”。我把这个项目里的联动拆解成三个层面：数据层、坐标层、视图层。
2.1 数据组织方式
二维地图加载的是iServer发布的Map服务，通常是一组已经配好样式、切好缓存的地图瓦片；三维场景加载的是iServer发布的三维服务，数据源是S3M格式的缓存，包括倾斜摄影模型、人工精模、BIM、点云等。
两层数据在服务端共享同一个数据源，但前端不能直接把二维瓦片叠加到三维地球上看，除非你只做2.5D效果，否则瓦片在三维视角下会拉伸变形、贴近地表。所以主体方案仍然是双容器渲染：一个div承载二维SuperMap.Map，另一个div承载三维Viewer。
2.2 联动机制的工作流程
核心思想是事件驱动加状态防抖。两个视图各自维护自己的交互事件，当用户操作其中一个视图时，触发事件回调，在回调里计算出目标坐标和视角参数，再调用另一个视图的API去执行飞行或平移。
为了避免两个视图互相触发导致的死循环，我给每次同步动作加了一个isSyncing标志位。同步过程中，两个视图的change事件都会被暂时屏蔽，等参数设置完成后再恢复监听。这一点不做的话，大概率会看到相机来回抖动，最后卡死。
二维地图触发moveend ↓ 计算二维中心点经纬度 ↓ 根据zoom推算三维相机高度 ↓ 调用viewer.camera.flyTo ↓ 三维相机焦段变化触发camera.changed ↓ 反算二维中心点和zoom ↓ 调用map.setCenter同步二维地图流程不算复杂，实际代码需要同时处理好事件防抖和坐标转换，后面单独用一章来拆解。
3. 核心细节解析：坐标系同步与视点联动
联动效果做得好不好，核心在坐标转换和高度换算。这一步出错，哪怕差一两个像素，三维视角飞过去后中心点都会偏离目标地物。
3.1 坐标转换的底层逻辑
SuperMap二维地图默认的坐标系一般是“Web墨卡托”（EPSG:3857）或自定义高斯投影，而三维场景里相机位置、经纬度计算都基于地理坐标系（EPSG:4326）。因此，二维地图的center拿到的是投影坐标，不能直接拿去驱动三维相机，必须先转成经纬度。
SuperMap的类库本身提供了LonLat对象，但二维地图内部会使用Projection机制做投影管理。在设置二维中心点的时候，可以传入经纬度，SuperMap会基于地图当前投影自动转成投影坐标。反过来，从二维地图拿到center后，通过projection转换接口也可以取到经纬度。如果遇到自定义坐标系，建议直接引入proj4js，传入自定义投影参数做转换，避免依赖iServer端的动态投影。
3.2 视点同步算法
二维地图的操作能力是“中心点+缩放级别”，三维相机的控制能力是“经纬度+高度+方向角”。要让两边能够互相映射，我用了一个换算策略，不追求严格的像素级等比，而是保证“中心点一致、视觉比例和谐”。
二维转三维时，从map.getCenter()取出中心经纬度，再根据zoom级别推算一个合适的相机高度。这个推算不要求绝对精确，满足视觉比例即可，我用的经验公式是：
height = 20000 * 2^(12 - zoom)也就是zoom越大，相机拉得越低、看得越细。实测下来，zoom为10时高度约8000米，zoom为16时高度约250米，符合二维缩放尺度下的视觉习惯。
三维转二维时，从viewer.camera.positionCartographic取出相机经纬度，直接把该经纬度setCenter到二维地图。缩放级别则按照相机高度反推：
zoom = Math.round(12 - Math.log2(height / 20000))为什么不用真实分辨率去做严格换算？因为二维地图和三维场景的屏幕可视范围、视野角度不同，即使按像素级等比换算，用户视觉上仍然会觉得有偏差。这里追求的是“中心点一致、大致比例一致”，实践证明这种近似方案在交互上体验更好，用户感受到的是流畅联动而不是机械对位。
3.3 图层可见性控制
一体化浏览还需要解决一个问题：三维场景中加载了多层模型，比如倾斜摄影、地下管线、BIM体块，如果全部显示，页面会卡到没法交互。我做了两个控制方案。
第一是LOD控制。在Viewer的scene配置里开启LOD，设置最大屏幕空间误差（maxScreenSpaceError），让远处模型自动抽稀，近处模型精细显示。推荐值设在1.5到2之间，太小会导致加载大量细节模型，太大则远处模型会糊掉。
第二是联动显隐。在二维地图的图层树上勾选某个专题图层，三维场景对应模型图层也会同步显隐。这个实现的关键是找到二维图层与三维实体之间的唯一标识映射。我采用的是“服务地址+图层名称”作为唯一键，因为二维图层树和三维场景的图层列表，都来自iServer元数据，命名是一致的。监听二维图层树的勾选事件后，按这个唯一键找到对应的Primitive或Entity集合，统一设置show属性，从而做到一套勾选逻辑同时控制两端的显示状态。
4. 实操过程：从零搭建二三维一体化页面
下面把整个落地过程完整写一遍，适用SuperMap iClient for 3D 10i及以上版本，需要先部署好iServer并发布对应的二维地图服务和三维场景服务。
4.1 环境准备与资源引入
前端项目结构比较简单，核心文件就三个：一个HTML页面、一个业务JS、一个样式表。接入步骤如下：
- 到SuperMap官网下载iClient for 3D的发行包，得到若干js/css文件。
- 在页面里引入三个核心依赖：Cesium.js、SuperMap.Web.B3D的库、业务主程序库。
- 准备一个用来包裹三维场景的div，需要显式设置宽高；二维地图同样需要一个div。
<script src="path/to/Cesium.js"></script> <script src="path/to/supermap-web-b3d.js"></script> <link rel="stylesheet" href="path/to/supermap-web-b3d.css">注意：iClient for 3D的库包体积比较大，建议开启网站静态资源gzip压缩，首屏加载能快不少。如果项目本身用Webpack/Vite打包，也可以把库依赖放在externals里，避免参与打包体积优化。我的实测经验是，开启gzip后三维库的首屏加载时间能缩短一半以上。
4.2 初始化二维地图与三维场景
先看二维地图初始化，这段逻辑和SuperMap iClient for JavaScript 2D的写法几乎一致：
// 二维地图容器 const map = new SuperMap.Map('map2D', { controls: [new SuperMap.Control.ScaleLine()], projection: 'EPSG:3857' }); // 加载iServer发布的态势地图服务 const layer2D = new SuperMap.Layer.TiledDynamicRESTLayer( 'BaseMap', 'http://127.0.0.1:8090/iserver/services/map-china/rest/maps/China', { transparent: true, cacheEnabled: true } ); layer2D.events.on({ layerInitialized: () => map.addLayer(layer2D) });三维场景的初始化采用的是Scene方式：
// 三维场景容器 const viewer = new SuperMap.Web.B3D.Viewer('map3D', { scene3D: { url: 'http://127.0.0.1:8090/iserver/services/3D-scene/rest/realspace', enableLighting: false }, controlOptions: { enableRotate: true, enableTranslate: true, enableZoom: true } });这里有个关键细节：Viewer的初始化参数里，scene3D.url指的是iServer三维服务地址，不是SPB文件路径。如果你拿不到场景服务地址，也可以直接用SceneManager从本地加载S3M缓存目录，但那样就没有iServer的权限控制和动态调度能力了。生产环境建议用iServer地址，开发调试时可以先用本地缓存快速验证。
4.3 联动逻辑实现
联动是项目最核心的代码，我封装了一个双向同步类，把坐标转换和事件防抖都收敛在里面。简化版代码如下：
class SyncManager { constructor(map, viewer) { this.map = map; this.viewer = viewer; this.isSyncing = false; this.initEvents(); } initEvents() { // 二维移动结束后，通知三维飞过去 this.map.events.register('moveend', this, this.onMapMoveEnd); // 三维相机变化时，通知二维同步中心 this.viewer.camera.changed.addEventListener(this.onCameraChanged, this); } onMapMoveEnd() { if (this.isSyncing) return; this.isSyncing = true; const center = this.map.getCenter(); const lonLat = this.toLonLat(center); const height = this.calcHeightByZoom(this.map.getZoom()); this.viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees( lonLat.lon, lonLat.lat, height ), duration: 0.5 }); this.isSyncing = false; } onCameraChanged() { if (this.isSyncing) return; this.isSyncing = true; const carto = this.viewer.camera.positionCartographic; const lon = Cesium.Math.toDegrees(carto.longitude); const lat = Cesium.Math.toDegrees(carto.latitude); const zoom = this.calcZoomByHeight(carto.height); this.map.setCenter(new SuperMap.LonLat(lon, lat), zoom); this.isSyncing = false; } toLonLat(center) { // 投影坐标转经纬度；如果已经是经纬度，直接返回 if (center.lon < -180 || center.lon > 180 || center.lat < -90 || center.lat > 90) { return this.map.projection.inverse(center); } return center; } calcHeightByZoom(zoom) { return 20000 * Math.pow(2, 12 - zoom); } calcZoomByHeight(height) { return Math.max(3, Math.round(12 - Math.log2(height / 20000))); } } const syncManager = new SyncManager(map, viewer);写完后我实际测试下来，flyTo的duration设0.5秒最合适，太短会显得突兀，太长用户会感觉迟钝。另外，camera.changed是相机任何变化都会触发的高频事件，如果项目里还需要做鼠标交互，建议在同步前判断一下当前是否在飞行状态，可以用viewer.scene.screenSpaceCameraController.enableInputs来判断，或者直接用一个飞行标志位过滤中间态，避免拖动过程中二维地图频繁刷新中心点。
4.4 图层高亮联动的处理
除了视点联动，选中联动也很重要。我的做法是：二维地图点击某个要素，拿到要素属性里的唯一ID，然后去三维场景里遍历Entity，找到同ID的模型并设置高亮颜色。反向操作同理，三维场景拾取模型后，把ID回传给二维做闪烁。
代码核心是两个事件绑定：
// 二维要素点击 map.events.register('featureSelected', this, (feature) => { const id = feature.attributes.ID; highlight3DEntity(viewer, id); }); // 三维场景点击拾取 viewer.screenSpaceEventHandler.setInputAction((movement) => { const picked = viewer.scene.pick(movement.position); if (Cesium.defined(picked)) { const id = picked.id.properties.ID; highlight2DFeature(map, id); } }, Cesium.ScreenSpaceEventType.LEFT_CLICK);这里有几个坑：一是三维拾取到的可能是S3M模型内部的子部件，id未必是顶层要素的id，需要先根据模型层级关系向上找到业务ID；二是高亮材质如果直接修改Entity的color，会破坏原始纹理，更稳妥的做法是使用Cesium的colorBlendMode配合半透明白色叠加，或者给模型单独添加一个高亮外壳体，这样既能突出显示又不丢失原有贴图细节。
5. 常见问题与排查技巧实录
这个项目做完之后，我在调试阶段踩了不少坑，列几个最典型的，方便后面接手的人少走弯路。
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 三维场景一直白屏 | iServer服务地址错误或未开启跨域 | 在浏览器控制台查看网络请求，确认三维服务返回200；iServer站点开启CORS配置 |
| 二维地图空白，只有底图背景色 | 图层未初始化完成就addLayer | 监听layerInitialized事件再做addLayer，或检查瓦片路径是否有token |
| 联动时三维中心点偏移明显 | 二维地图用了自定义投影，toLonLat未做投影转换 | 引入proj4js，使用自定义投影参数反算经纬度 |
| camera.changed频繁触发导致页面卡顿 | 事件回调里做了过多的DOM操作 | 使用requestAnimationFrame做节流，只在每帧最后一次变化时同步 |
| 三维模型高亮后纹理丢失 | 直接改了entity.color | 改用colorBlendMode加半透明白色叠加，保留原始纹理 |
5.1 三维场景加载白屏排查
这个问题八成出在服务端跨域或场景服务没配置好。我遇到过一次，iServer部署在Linux服务器上，端口默认8090，前端页面用localhost访问，WebSocket和HTTP请求都被浏览器拦截了。最终的解决办法是让前端使用和iServer同源的域名，或者干脆把iServer的跨域开关打开，并在代理层把3D服务的WebSocket也代理一遍。顺带一提，如果页面是通过HTTPS访问的，一定要确认iServer也是HTTPS，否则混合内容会被浏览器直接阻止，这一点在排查时很容易忽略。
5.2 联动漂移问题的处理
联动漂移的根因绝大多数是坐标系不统一。二维服务发布的是什么投影，三维服务底层是什么坐标系，两边的空间参考必须严格匹配。我在实施时踩过一次：二维数据用的是CGCS2000高斯投影，三维服务的地形是WGS84，结果不管怎么调参数，飞过去总是偏几百米。后来把二维地图的投影明确指定为EPSG:4490，并在地图初始化的projection参数里做了配置，问题立刻消失。这类问题在排查时，不要只看页面代码，先到iServer的服务元数据里确认两个服务的坐标系是否一致。
5.3 高频事件与卡顿优化
联动卡顿主要来自camera.changed。相机的每次微小移动都会触发该事件，在浏览器里高频callback很容易让主线程满负荷。我的优化方案有两个层次：第一层用requestAnimationFrame节流，保证即使触发100次，同步动作也只在浏览器渲染帧内执行一次；第二层在用户拖拽三维场景时，先不实时同步二维，而是等用户松开鼠标后再同步一次。至于二维拖拽，反过来用的是moveend事件，本身只在拖拽结束时触发，所以不需要额外节流。
6. 从项目里总结的几条经验
这个项目做完，我印象最深的一点是：二三维一体化浏览看着是个“呈现层”的活，但实际上80%的工作都花在坐标系、事件机制和数据对应关系上。如果前期不从数据源头把空间参考统一好，后面所有联动都是空中楼阁。
给后续要做的朋友三点建议：第一，在项目启动阶段就确认二维和三维服务的坐标系是否一致，不一致立刻做动态投影或数据转换，别拖到联调阶段再处理；第二，联动逻辑一定要抽成独立模块，不要散落在页面里，否则后续加图层、加标绘、加卷帘功能时很容易互相干扰；第三，性能优化要前置，像S3M缓存、LOD参数、实体数量控制这些，在场景搭建时就要预估好数据规模，不要等卡了再返工。
再分享一个小技巧：如果你需要在二维侧做空间查询，比如框选一批楼栋，然后把结果同步到三维显示，可以在查询完成后，把二维查询到的要素ID集合传给三维侧，由三维侧按ID过滤生成临时实体，而不是把二维的Geometry直接塞给三维渲染。这样做的好处是性能好、逻辑清晰，也不容易出现坐标转换的精度损失。这个思路我在项目里反复验证过，稳定可靠，值得纳入你自己的项目工具箱。
本文还有配套的精品资源，点击获取
