简介面向GIS开发者的SuperMap iClient for 3D二三维一体化浏览示例包聚焦二维与三维场景无缝切换这一核心需求解决传统GIS中二三维分离、需切换系统的问题适用于城市规划、环境分析、交通管理等领域的空间信息直观展示。包内共18个文件、约18.9MB含JavaScript库、bru/lsl三维缓存配置、中国省级地理数据udb/udd、可直接运行的HTML示例及docx说明文档结构清晰便于查阅。通过该资源可学习SuperMap iClient for 3D的API调用掌握数据加载、三维建模、交互操作与LOD性能优化等关键技能为跨浏览器/跨设备的GIS应用开发打下基础。已有445人学习下载既适合入门也可供中高级开发者快速检索二三维一体化实现细节提升实际项目开发效率。 做WebGIS开发的朋友多半被同一个问题折磨过业务数据都在二维地图上领导却想在三维场景里看效果。二维系统做得好好的有POI、有专题图、有空间分析接口一上三维所有数据好像都得重做一遍。我在实际项目里用SuperMap iClient for 3D官方产品名是SuperMap iClient 3D for WebGL做过一套“平面场景二三维一体化浏览”的方案简单说就是把二维地图服务和三维模型放到同一个三维场景里浏览、查询、联动不用再开两个窗口来回切。这篇文章会把方案思路、数据准备、核心代码、踩坑记录全部摊开讲适合正在做WebGIS可视化、被“二三维联动”需求缠住的开发者参考。1. 先想清楚平面场景二三维一体化到底要解决什么问题1.1 二三维分离是WebGIS最常见的老大难绝大多数业务系统都是从二维起家的。设备点位、管网数据、房屋面、业务专题图全沉淀在二维GIS服务里。等要上三维可视化的时候常规做法是同一个页面放两个窗口左边二维地图、右边三维场景靠鼠标事件做联动。这种双窗口方案开发起来不算难但用起来很别扭用户得不停在二维找数据、到三维看效果本质上还是两套系统拼在一起。真正的二三维一体化不是“两个窗口”而是让三维场景本身具备二维地图的表达能力二维地图服务能贴进去矢量数据能叠上去专题图能显示出来属性还能点选查询。这样用户在一个场景里就能完成从“找数据”到“看模型”再到“查属性”的完整操作链路不用来回跳。我这次用SuperMap iClient for 3D的目的就是验证这种“单场景融合”的可行性。把二维Map服务、GeoJSON业务点、S3M三维模型放进同一个平面场景前端代码量控制在可接受范围整个浏览体验基本是无缝的。1.2 平面场景和球面场景到底怎么选很多人习惯直接用球面场景。全球影像、大范围数据浏览很合适但做局部精细化项目时平面场景的优势非常明显。我判断的依据大概是这几条数据范围小且集中一个园区、一座工厂、一栋楼的地下空间用平面场景更自然原始数据是CAD图纸、平面布置图、施工图坐标系是投影坐标甚至工程坐标用平面场景能保留1:1的比例关系后续要高频测量距离、计算面积平面场景下默认是平面直角坐标计算符合业务直觉如果数据范围覆盖一个城市甚至更大或者需要叠加全球底图那老老实实退回球面场景标题里写“平面场景”意味着数据和服务本身的坐标系不是经纬度而是CGCS2000高斯投影、城市独立坐标系这类平面坐标。后续所有前端叠加、相机定位、联动逻辑都要围绕这个坐标系来想这和球面场景的写法有不小差异。2. 选型思考为什么用SuperMap iClient 3D来落地2.1 iClient 3D和Cesium的关系一句话说清SuperMap iClient 3D for WebGL本质上是SuperMap在Cesium基础上深度定制的一套WebGL三维开发库。API风格和Cesium高度一致但扩展了一大堆SuperMap数据能力S3M格式流式加载、iServer REST服务访问、超图场景配置、属性查询等。对已经用SuperMap iServer做后端的人来说这套库几乎是唯一性价比最高的前端选择。因为数据发布之后前端接服务就是几行代码的事不用自己写格式解析不用折腾瓦片转换。S3M是超图的流式三维数据格式桌面端生成缓存后前端直接加载加载速度和处理效率都有保障。如果硬要类比iClient 3D就像一个翻译官后端iServer把场景、模型、地形、影像全部发布成服务前端用iClient把这些服务翻译成场景里的一个个图层。你不需要深入了解底层格式细节只需要关心业务层怎么组织图层、怎么交互。2.2 二三维一体化浏览的三条技术路线在平面场景里做二三维一体化实际落地方式大致有三种路线做法适用场景效果影像叠加法把二维Map服务作为影像底图贴到场景地表宏观底图、业务总览三维地形/模型上盖二维地图矢量转Entity法把GeoJSON、KML等矢量数据转成三维实体显示业务点位、管网、区域标注支持点击、悬停、属性查询S3M模型叠加法把精细三维模型以S3M瓦片叠加进场景建筑、设备、地下管线真实感最强适合精细化展示我实际项目里不会只用一种通常是三条路线混合S3M做主体三维展示二维Map服务做底图和业务专题GeoJSON做动态业务标注和查询。这样既保住了二维数据灵活更新的优势又有三维模型的表现力。2.3 为什么不直接用Three.js或者原生Cesium这个问题几乎每次做方案评审都会有人问。Three.js灵活、轻量适合创意可视化但GIS能力太弱地图投影、坐标系变换、地形分析、量算都要自己造轮子做业务GIS系统会累死。原生Cesium能力强但和iServer服务之间并不原生打通要自己写S3M加载逻辑或者把数据转成3D Tiles工作量不小而且转格式又会带来数据一致性的风险。如果你后端已经是SuperMap iServer前端用SuperMap iClient 3D是省事最多的一条路。它保留了Cesium底层的扩展能力又能无缝接iServer相当于两头都占。唯一要注意的是iClient版本和iServer版本最好对应避免接口兼容问题。3. 实现路径平面场景二三维一体化浏览的完整搭建流程3.1 数据准备先在iDesktop里把平面场景做好别急着写代码这一步很多人会跳过直接拿一个S3M服务地址扔给前端结果各种对不齐。正确的姿势是在SuperMap iDesktop里先把数据治理好、场景存好再发布给前端用。我当时的处理流程大概是准备数据。CAD导出的DWG/DXF、SHP、GeoJSON都可以但所有数据的坐标系必须统一。比如统一到CGCS2000 / 3 Degree GK CM 120E不要一个图层用经纬度、一个图层用投影坐标。导入iDesktop。新建数据源把数据导进去全幅显示看一眼数据范围是否正确。出现数据飞天的基本都是坐标系没定义或定义错了。新建场景。这里注意选择新建“平面场景”不是球面场景。场景属性里把坐标系设置成和数据一致这是后续一切正常的基础。生成S3M缓存。对建筑、设备这类模型数据生成S3M三维切片缓存lod级别用默认值就行。把二维地图缓存拖进场景。如果你的二维Map服务已经有专题图或缓存可以在桌面端直接拖进场景当底图同时就验证了数据叠加位置是否齐整。保存场景发布到iServer。服务类型选REST三维服务realspace发布成功后复制服务地址前端要用。一个关键注意事项平面场景的所有图层坐标系必须是同一个。把不同坐标系的图层硬塞进一个平面场景叠加出来的位置一定是错乱的而且这个问题在前端很难排查因为跑起来不报错就是位置不对。3.2 页面骨架初始化Viewer并打开平面场景页面结构不复杂一个div容器引入iClient 3D的CSS和JS然后创建Viewer。关键代码大概是这样的!DOCTYPE html html head meta charsetutf-8 / titleSuperMap iClient 3D 平面场景二三维一体化/title link hrefhttps://example.com/iclient3d.css relstylesheet / /head body div idmapContainer stylewidth:100%;height:100vh;/div script srchttps://example.com/iclient3d.min.js/script script var viewer new Cesium.Viewer(mapContainer, { baseLayerPicker: false, animation: false, timeline: false, infoBox: false }); var sceneUrl http://localhost:8090/iserver/services/3D-plane/rest/realspace; viewer.scene.open(sceneUrl).then(function () { // 场景打开成功 console.log(scene opened); }); /script /body /html这里有几个细节容易踩坑。首先viewer.scene.open()是异步的后续对图层的操作最好放在回调里否则会拿到空的场景对象。其次如果你们的场景是经纬度坐标系可以再用viewer.scene.camera.setView定位到数据范围但如果是平面无投影坐标系Cesium.Cartesian3.fromDegrees()这套就不适用我建议直接在iDesktop里把场景初始视角保存好前端打开场景就直接落在那个视角上省去前端定位的麻烦。3.3 关键一步二维数据和三维模型怎么叠加到同一个场景场景打开之后就开始往里面堆图层了。二维Map服务、GeoJSON业务数据、S3M模型三种数据叠加方式不一样我拆开说。先看二维Map服务作为底图叠加。用iClient 3D的addLayer方法通过layerType指定为IMAGE加载iServer发布的二维地图服务viewer.scene.addLayer({ name: plantBaseMap, url: http://localhost:8090/iserver/services/map-plant/rest/maps/PlantMap, layerType: IMAGE, visible: true, opacity: 0.85 });二维地图服务在三维场景里本质上就是贴在地表或地层上的一张影像图所以它的坐标系必须和场景坐标系匹配否则会贴到不知哪里去。opacity参数按需调如果S3M模型是主角底图通常调低一点透明度让模型更突出。再看GeoJSON业务数据加载。业务点、监测点、区域范围这类经常变的二维数据适合用Entity方式在浏览器端动态渲染Cesium.GeoJsonDataSource.load(./monitor-points.geojson, { clampToGround: true, stroke: Cesium.Color.WHITE, fill: Cesium.Color.fromCssColorString(#1E90FF).withAlpha(0.6), markerSize: 24 }).then(function (dataSource) { viewer.dataSources.add(dataSource); });注意clampToGround: true这个参数它决定矢量数据是否贴合地面。平面场景里如果数据点加了高度信息也可以不贴合改成悬浮在三维模型周围做标注非常合适。GeoJSON里的坐标一样要和场景坐标系一致这个没有商量余地。最后看S3M模型图层。如果场景服务里已经带了模型那打开场景就有了如果要动态追加另一个模型缓存服务可以这样var modelLayer viewer.scene.addS3MTilesLayerByUrl( http://localhost:8090/iserver/services/3D-building/rest/realspace/datas/buildings, { name: buildings, visible: true } );S3M图层是超图性能最稳的一类数据适合放大体量模型。模型和二维底图配在一起的时候注意检查贴地高度否则会出现模型悬空或者被地面穿模的情况。3.4 可选增强二维地图与三维场景联动如果业务上确实还需要一个二维地图做全局概览那就在页面右侧挂一个OpenLayers或Leaflet二维地图和三维场景做双向联动。三维到二维的联动监听相机移动结束事件viewer.camera.moveEnd.addEventListener(function () { var carto viewer.camera.positionCartographic; var lon Cesium.Math.toDegrees(carto.longitude); var lat Cesium.Math.toDegrees(carto.latitude); // 把二维地图中心移动到 (lon, lat) olMap.getView().setCenter([lon, lat]); });二维到三维的联动监听二维地图的点击事件让三维相机飞过去olMap.on(click, function (evt) { var coord evt.coordinate; viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(coord[0], coord[1], 500) }); });平面场景如果坐标不是经纬度直接从相机取经纬度可能不准确。我的建议是如果项目必须做二维联动优先统一到经纬度坐标系否则联动逻辑会非常难受。4. 实测坑位坐标系、图层和性能问题排查记录4.1 数据对不齐坐标系是头号嫌疑我遇到过最典型的问题S3M模型在二维Map底图也在但两者差了大概几百米像是被平移过。反复查代码没发现问题最后回到iDesktop检查才发现模型数据是CGCS2000投影坐标二维底图缓存却用的WGS84经纬度。一个场景里两个坐标系不偏才怪。排查坐标系问题我习惯按这个顺序来在iDesktop里分别查看每个图层的坐标系属性确认是否一致查看场景属性里的坐标系设置确认是否和图层一致对GeoJSON这类外部数据用代码或在线工具检查坐标范围判断是经纬度还是投影坐标确认没问题后再用iServer发布服务发布后通过iServer预览页面验证一遍前端代码里加坐标系转换逻辑不是不行但成本高、隐患多。最好的策略就是在数据准备阶段把所有数据统一到一个坐标系前端不做任何转换。4.2 图层不显示按这个顺序排查图层加了一堆场景里什么都看不到这是新手最容易慌的场景。我一般按这套流程排查确认图层的visible属性是true不要以为默认就是显示确认opacity大于0我曾经把透明度设成0.3加上底图颜色重叠直接看不见还以为加载失败打开浏览器Network面板看服务请求是否返回200如果404或500服务地址或配置有问题检查相机视野范围有时候数据不在当前视野内缩小或飞到数据范围就能看到检查图层叠加顺序二维底图在最底层S3M模型在中间业务矢量在最上层把服务URL直接复制到浏览器打开如果连iServer自身都打不开那是服务端的问题跟前端没关系这个排查顺序很重要不要一上来就怀疑代码逻辑先确认服务、图层属性、视野这些基础因素再回头查代码。4.3 场景一卡一卡性能优化三板斧平面场景叠加多个图层后性能问题会很明显。S3M本身做了LOD地形和模型加载策略相对成熟但二维Map底图叠加进去后GPU压力会成倍增加。我常用的优化手段是这几招增大maximumScreenSpaceError降低模型细节密度。这个参数越大模型渲染越粗糙但帧率明显提升。做展示项目时调到4-8之间基本够用二维底图必须用预生成缓存瓦片不要实时渲染。iServer发布时检查是否开启了缓存实时渲染会直接把GPU打爆图层按需显示。根据相机当前范围判断哪些图层在视野内视野外的图层设置visiblefalse拉回来时再显示大量业务点用聚合。几千个GeoJSON点同时渲染即使Entity性能不差也会卡用EntityCluster聚合即可还有一个容易被忽略的图层用完要及时移除尤其是临时加载的标注、测量结果。viewer.scene.layers.remove(layer, true)可以直接释放资源避免内存持续上涨。4.4 常见问题速查表问题现象可能原因解决办法二维底图和三维模型错位几百米坐标系不一致在iDesktop把所有数据统一坐标系重新发布场景打开后是黑屏服务启动失败或scene.open回调内未处理异常确认iServer服务可用查看浏览器控制台报错某个图层不显示visible不为true、opacity为0、图层范围不在视野内按4.2的排查顺序逐个检查GeoJSON加载后点全挤在一起数据坐标未定义或投影转换错误检查GeoJSON坐标范围确认坐标系S3M模型悬空或穿地贴地高度设置错误在桌面端调整模型高度或前端设置height属性帧率低、拖动卡顿底图实时渲染、S3M LOD层级过高启用底图缓存增大maximumScreenSpaceError最后再聊两句实际经验做完这套平面场景二三维一体化之后我最深的感受是二三维一体化不是把两个系统硬塞到一个页面而是从数据源头就要设计好。坐标系统一了数据规范了前端拿到的就是一个可以直接叠加的“空间底座”剩下的代码量反而很少。如果你也正在被这个需求卡住建议先从平面场景的数据准备开始验证不要一上来就堆代码那样只会事倍功半。最后分享一个小技巧在iDesktop里保存场景的时候把初始视角设置好、存好。前端打开场景时服务本身会把视角一起带到浏览器这样能省掉一大截相机定位的调试时间。别问我怎么知道的我在这里起码耗过半天。本文还有配套的精品资源点击获取