1. 这个需求有点怪但细想其实很实用先说个背景。最近有个项目甲方提了个需求三维场景里相机飞到哪儿页面上就实时汇报那个位置的天气情况。当时第一反应是这算哪门子需求三维地球加个天气模块多半是又想要什么花哨功能。但实际聊下来发现人家真是有用途的——现场巡查的时候监控人员需要知道某个区域当前的天气状态判断能不能继续作业。这个需求本质上不是“看天气”而是“跟随视角自动获取当前关注点的环境信息”。所以这篇博文我不打算只讲SuperMap iClient3D for WebGL的相机接口怎么调而是把“相机位置实时获取 天气数据接入 场景状态联动 汇报面板展示”这一整套链路拆开讲。无论你用的是SuperMap iClient3D for WebGL 10i还是11i甚至换成Cesium原生开发思路都通用。适合谁来参考三维GIS开发、WebGL可视化方向的前端以及正准备接这类“眼随镜动、信息随行”需求的方案设计人员。看完你能直接落地的核心东西有如何拿到相机当前的经纬度、高度、朝向角如何高效捕获相机位置变化避免性能翻车如何把位置信息换算成天气查询条件并处理跨域限制如何让场景里的环境效果雾、亮度、粒子随天气数据自动切换如何做一个不突兀的相机状态汇报面板考虑到标题带了“实时”两个字这里要先定个调所谓实时不是每一帧都去请求天气接口那不叫实时那叫自爆。实时指的是——相机停止变化或者说位置稳定后自动触发一次天气状态刷新。这才是这个功能正确且可落地的打开方式。2. 相机位置与姿态信息怎么拿以及为什么它很容易坑2.1 基础APICamera对象到底能给你什么在SuperMap iClient3D for WebGL里相机对象通过viewer.camera访问。它继承自Cesium的Camera体系所以Cesium上能用的相机属性在这里基本都能用。这一点对很多从Cesium转过来的开发者是个好消息踩坑的经验大部分也能复用。关键的属性分成两类位置类姿态类。位置camera.position返回一个Cartesian3笛卡尔坐标它是地心直角坐标系下的坐标单位是米。直接拿这个数字给后端用十有八九会把后端搞懵因为常规业务里大家习惯用经纬度和高度。姿态camera.heading、camera.pitch、camera.roll单位是弧度分别表示偏航角、俯仰角和翻滚角。heading是相对于正北方向的顺时针角度pitch为负表示俯视roll在常规GIS场景里几乎总是0。这些角度信息是这个需求的关键因为有了相机朝向你才知道用户“正在看哪里”而不只是“人在哪里”。但注意position在场景刚加载完成或者执行了flyTo进行定位后内容是不同的。flyTo是一个异步动画过程相机位置会连续变化。如果直接执行flyTo后立刻读取position读到的往往还是飞行前的值或者是动画进行中的某个中间值。2.2 位置换算从笛卡尔坐标到经纬度拿到Cartesian3之后需要换算成WGS84经纬度。SuperMap的写法var cartographic Cesium.Cartographic.fromCartesian(viewer.camera.position); var longitude Cesium.Math.toDegrees(cartographic.longitude); var latitude Cesium.Math.toDegrees(cartographic.latitude); var height cartographic.height;这个换算很简单但有个容易出错的点Cesium.Cartographic.fromCartesian在相机高度过高时精度变化明显。当地球视角拉到全球尺度经纬度的小数点后几位用的意义不大但当地面缩放到了一个城市级别对经纬度精度的要求就到小数后4位甚至5位约10米级。实际操作时建议根据cam.height动态决定保留几位小数避免给天气接口传了太长的经纬度参数白白多传几个字节。还有一点值得提醒不要每次都new一个Cartographic对象。Camera的position在相机旋转、平移、缩放时会持续变化如果你写了个监听器在每帧都换算就会频繁创建临时对象增加GC压力。正确做法是复用变量var scratchCartographic new Cesium.Cartographic(); var cartographic Cesium.Cartographic.fromCartesian(viewer.camera.position, Cesium.Ellipsoid.WGS84, scratchCartographic);第三个参数是结果对象这样避免了内存频繁分配。项目跑到一两个小时这个细节会实实在在地体现到帧率稳定度上。2.3 实时感知位置变化camera.changed事件与节流策略SuperMap/Cesium的Camera有一个changed事件当相机发生变化时触发并且带一个percentage参数表示变化幅度。用法很简单viewer.camera.changed.addEventListener(function(percentage) { // 相机动了 });真正坑人的地方在于这个事件每一帧都可能触发频率远高于你的需求。相机稍微一抖、一下滚轮缩放、一次拖动旋转都会触发。如果你在回调里直接发天气请求那效果就是拉着接口疯狂揍。所以需要两层防护时间节流 静止判断。时间节流比较好理解定义最小间隔比如5秒内只允许触发一次天气查询。哪怕相机一直在动也是每5秒最多查一次。静止判断稍微复杂一点如果相机连续几秒没有发生大幅度变化才认为这次是“稳定驻留”此时触发一次请求。静止判断的好处是避免飞行过程中频繁发起无效请求只有当用户停下视角开始观察时才汇报。我实际采用的方案是双重判断var lastQueryTime 0; var lastPosition null; var MIN_INTERVAL 5000; // 最小查询间隔单位毫秒 var STILL_THRESHOLD 0.001; // 位置变化阈值用于判断是否静止 viewer.camera.changed.addEventListener(function(percentage) { var now Date.now(); if (now - lastQueryTime MIN_INTERVAL) return; var currentPosition viewer.camera.positionWC; if (lastPosition) { var distance Cesium.Cartesian3.distance(currentPosition, lastPosition); if (distance STILL_THRESHOLD) { lastPosition Cesium.Cartesian3.clone(currentPosition); return; } } lastPosition Cesium.Cartesian3.clone(currentPosition); lastQueryTime now; // 执行天气查询 queryWeatherByCamera(); });这段代码的核心思想是相机必须“在一个地方待够时间”才会触发汇报。这比单纯节流更符合“实时汇报”的业务语义——我要汇报的是“当前正在关注那个位置”的天气不是“刚才飞过那一圈”的天气。注意percentage参数是相对上一次事件的变化比例不是位置差别试图用它来判断静止。要用positionCartographic或者positionWC做几何计算。3. 天气数据从哪来数据源选型与跨域绕行方案3.1 数据源怎么选天气数据源是这类项目里最容易被低估的一环。开发阶段随便找个免费接口测试没问题一旦要上生产就得考虑请求量、稳定性、国内可访问性、是否需要商业授权。我用过的方案有这么几类数据源请求方式优点缺点和风天气QWeatherHTTPS API数据全返回快有开发版免费额度需要注册key生产环境建议付费OpenWeatherMapHTTPS API国际城市覆盖好国内访问偶有不稳定高德开放平台天气接口HTTPS API国内稳和GIS场景契合度高返回字段简单类型偏少后端自建代理转发任意密钥可控、可缓存、可加业务逻辑需要后端配合个人建议国内项目首选高德或和风国际项目考虑OpenWeatherMap而且所有请求务必走后端代理。理由很简单天气接口的key一旦暴露在前端代码里别人抓包就能看到用你的额度白嫖甚至恶意刷接口。这个钱不该省。3.2 前端拿不到天气接口怎么办代理与绕行如果你的后端没时间帮你做代理前端也不是完全没法绕。最常见的做法是使用支持跨域的公共服务接口再在请求上做一些技巧。拿高德举例它的天气接口是GET https://restapi.amap.com/v3/weather/weatherInfo常规情况下浏览器直接请求会跨域。解决办法分几种用JSONP。部分天气服务商包括一些老版本接口支持JSONP回调前端用script标签加载绕开CORS限制。用本地开发代理生产环境用Nginx反向代理。Nginx配置一行proxy_pass就能解决生产环境本来也应该有这么一层。用Cesium官方推荐的CORS-friendly公共服务。但这只适合测试不适合正式业务。我的经验是能走后端代理就走后端代理别为了省事在前端裸调接口。跨域之外还有个更现实的问题——接口限流。免费天气接口通常有每秒多少次请求的限制前端直接调很容易触发限流返回错误。后端代理可以加一层缓存相同的经纬度短时间内只查一次大大降低限流概率。3.3 经纬度转城市编码的取舍天气接口通常支持两种查询方式按经纬度查或者按城市编码adcode查。经纬度查询更精准但依赖服务商的地理围栏数据城市编码查询精准度差一点但对于“汇报天气”这个场景完全够用而且返回的天气信息往往是“XX市多云”语义更清晰。实际项目中我更推荐经纬度为主、城市编码兜底的组合方案。步骤如下将相机经纬度传给天气接口请求最近位置的天气。如果接口返回码表示位置无匹配比如在海上、在戈壁深处则用一个逆地理编码接口把经纬度换成城市名再查一次。如果逆地理编码也失败极端场景比如用户把相机拖到了太平洋中间就直接在面板上显示“当前位置无天气数据”不报错、不崩溃。这个兜底逻辑非常实用。你永远不会知道用户会把相机拖到什么鬼地方。飞行模式下相机过境几千公里路径上的城市天气可能多达几十个但真正需要汇报的永远是用户停下来的那个点。4. 天气数据下来之后场景状态联动才是这个功能的灵魂4.1 天气不只是文字它要驱动场景变天如果天气查询完之后只是在角落弹一个文字框“当前天气小雨18℃”那这个功能就太鸡肋了。真正让甲方眼前一亮的效果是相机飞到正在下雨的城市场景里就开始下雨飞到雾霾城市场景就起雾晴天场景就明亮通透。这里的核心技术点有两个一是场景天气效果怎么改二是怎么把不同天气类型映射到场景参数上。SuperMap iClient3D for WebGL场景中和天气相关的渲染参数主要这几块场景亮度/雾效viewer.scene.fog控制雾的密度与颜色viewer.scene.globe.baseColor可以改动底图色调。光源方向viewer.scene.globe.enableLighting控制是否开启光照光源方向随太阳位置变化。晴天时开启阴天时关闭并降低亮度效果差异非常明显。粒子系统SuperMap支持在场景中挂粒子系统来模拟雨雪。雨滴、雪花本质上是粒子贴图加发射器。背景色viewer.scene.backgroundColor在雾天、夜晚可以调成灰白色或深蓝色。这些参数在开发文档里都有但组合起来的效果需要自己调。我这里给出一个我这边调过的映射关系表供参考天气类型雾密度光照开启底图颜色粒子效果天空盒备注晴0.0开默认无默认天空多云0.01开默认偏暗无可换天空盒阴0.03关偏灰无天空盒换阴天版小雨0.05关偏暗雨粒子中速天空盒换雨云版大雨/暴雨0.08关明显变暗雨粒子高速大密度同上雪0.06关偏白亮雪粒子慢速飘落天空盒换雪云版雾0.2-0.4关偏灰白无低能见度天空盒这个表不是权威标准是我自己在项目里调出来的视觉经验。数值需要根据自己项目的模型风格、色调微调但方向是对的。4.2 粒子系统挂载与回收别创建了不销毁雨雪粒子是这里最容易出问题的一环。SuperMap iClient3D for WebGL封装了Cesium.ParticleSystem你可以用它构建粒子效果。我自己的做法是封装一个WeatherEffectManager负责根据当前天气动态创建或销毁粒子系统。代码骨架如下function WeatherEffectManager(viewer) { this.viewer viewer; this.currentEffect null; } WeatherEffectManager.prototype.applyWeather function(weatherType) { // 先清除旧效果 if (this.currentEffect) { this.viewer.scene.primitives.remove(this.currentEffect); this.currentEffect null; } // 根据天气创建新效果 switch (weatherType) { case rain: this.currentEffect this.createRainEffect(); break; case snow: this.currentEffect this.createSnowEffect(); break; default: break; } if (this.currentEffect) { this.viewer.scene.primitives.add(this.currentEffect); } };关键点在于粒子系统的位置必须跟随相机。因为粒子是在相机周围空间生成的一旦相机动了而粒子发射器还挂在地理坐标上效果就“穿帮”了——雨滴会突然消失或者瞬移到远处。所以每帧都要把粒子发射器的位置同步到相机位置附近。这个同步逻辑可以放到viewer.scene.preUpdate事件里。viewer.scene.preUpdate.addEventListener(function(scene, time) { if (weatherManager.currentEffect) { weatherManager.currentEffect.modelMatrix Cesium.Transforms.eastNorthUpToFixedFrame( viewer.camera.positionWC ); } });这样无论相机飞到哪雨雪都是围绕着相机下的看起来就是“用户所在位置正在下雨”。4.3 天气数据驱动UI做一个不抢眼的汇报面板和三雏场景里的效果联动配套页面上最好有一个小的信息面板。这个面板不是简单的文字堆砌而是一个可折叠的浮动卡片展示以下信息当前经纬度保留合适精度不要显示一长串小数海拔高度天气状况晴/雨/雪/多云等温度与湿度风力风向如果接口有数据更新时间面板的定位和样式建议做成半透明浮层挂在右下角或左下角不要居中遮挡场景。还要支持手动关闭因为有些用户就是不想看到任何浮层。代码上我用的是原生DOM因为这种小组件用框架反而重了。面板更新时要注意一个用户体验细节天气数据变化时如果只是粗暴地改变文字内容用户很难感知到变化。加一个淡入或者颜色闪烁的小动画提示“数据已刷新”体验会好很多。但是注意别用太花哨的动画避免抢焦点。5. 从“能跑”到“好用”性能调优与项目实战避坑5.1 高频相机事件与rendering性能的平衡相机位置汇报这个功能本身对场景性能影响不大真正影响性能的是为了这个功能你额外加的那些东西。最容易踩的坑有三个第一个坑在camera.changed里做了太重的同步操作。比如每帧读取相机位置后立刻做DOM更新这会导致强制回流reflow帧率直接掉。解决办法是DOM更新只在天气请求返回时做不要在相机移动的每一帧都做。第二个坑天气数据查询的并发控制没做好。用户在场景里快速拖动、缩放camera.changed高频触发如果5秒节流逻辑没写对可能会在极短时间内发出多个并发请求。后端接口返回顺序不一致最后面板上显示的数据可能是几秒前的旧位置数据。这个问题非常隐蔽往往要等用户操作很快时才会暴露。我的解法是加一个requestToken每次发起新请求之前把旧请求的标记作废var requestSeq 0; function queryWeatherByCamera() { var seq requestSeq; // 发送请求 fetchWeather(lon, lat).then(function(data) { if (seq requestSeq) { updateWeatherPanel(data); } }); }这样旧请求返回时因为seq不一致直接被丢弃不会污染UI。第三个坑相机飞到地下或非常规位置时天气查询会失败或返回诡异数据。比如相机高度为负地形地下、经纬度为NaN初始化阶段。必须对参数做合法性校验否则接口返回报错会反应到前端控制台对非技术用户很不友好。function isValidPosition(longitude, latitude, height) { return isFinite(longitude) isFinite(latitude) isFinite(height) longitude -180 longitude 180 latitude -90 latitude 90; }5.2 相机模式切换时的数据刷新陷阱SuperMap iClient3D for WebGL有两种视角模式三维地球和平面场景以及相机飞行过程中常见的2.5D视角过渡。测试时很容易忽略在飞行动画未结束时切换了场景模式怎么处理相机事件的绑定关系。实际项目中我遇到过这么一种情况用户点了一个飞行按钮让相机朝某城市飞去飞行过程中想立刻点另一个城市执行了新的flyTo。此时旧飞行动画会与新动画冲突camera.changed会剧烈触发。这本身是SuperMap/Cesium的正常行为但对天气汇报来说动画未结束之前不应该触发天气查询否则面板上会不停跳数据。解决办法是维护一个isFlying标记。flyTo开始时置为true飞行结束后置为false。天气查询只在非飞行状态下执行。viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(lon, lat, height), complete: function() { isFlying false; queryWeatherByCamera(); // 飞行结束立即执行一次查询 } }); isFlying true;由于相机位置在飞行中是连续变化的飞行结束这个时点拿到的位置就是用户最终落点此时触发一次天气查询是最佳时机。注意complete回调在flyTo被中断时不会触发所以还需要在camera.changed里判断飞行是否被取消来做兜底。5.3 生产环境部署与缓存策略天气数据虽然变化不算特别快但同一经纬度多次请求相同的天气数据纯属浪费。我的建议是在前端做两层缓存会话级缓存同一个经纬度保留到小数点后2位约1公里精度在10分钟内不重复请求天气接口。页面生命周期内缓存当前天气写入本地变量面板刷新时直接读缓存。这样一套做下来实际接口请求频率能降到用户主动操作时才发一次生产环境不用担心被限流。后端即使有代理它也照样有成本。我之前的项目上线后天气接口的平均日请求量不到500次而用户打开页面次数远超这个数。这就是缓存和静止判断共同作用的结果。给同行的建议是“实时”很多时候是个伪需求把这个词翻译成技术方案时要理解业务真实意图而不是字面的“时刻在请求”。6. 完整代码组装一套可以直接用的位置汇报模块前面拆了这么多最后给一套完整的可运行组合逻辑。注意这不是一个完整项目的所有代码而是核心骨架拷贝到SuperMap iClient3D for WebGL项目中就能跑起来。6.1 模块一的完整代码块// CameraWeatherReporter.js function CameraWeatherReporter(viewer, options) { this.viewer viewer; this.options Object.assign({ minInterval: 5000, // 天气查询最小间隔 stillThreshold: 0.01, // 相机静止判定阈值 enableSceneLinking: true, // 是否联动场景天气效果 enablePanel: true // 是否展示信息面板 }, options || {}); this.lastQueryTime 0; this.lastPosition null; this.requestSeq 0; this.isFlying false; this.currentWeatherType ; this.weatherCache new Map(); this.init(); } CameraWeatherReporter.prototype.init function() { var self this; // 1. 监听相机变化 this.viewer.camera.changed.addEventListener(function() { self.handleCameraChanged(); }); // 2. 如果开启场景联动挂粒子自动跟随 if (this.options.enableSceneLinking) { this.viewer.scene.preUpdate.addEventListener(function() { self.syncParticlePosition(); }); } // 3. 初始化面板 if (this.options.enablePanel) { this.createPanel(); } }; CameraWeatherReporter.prototype.handleCameraChanged function() { if (this.isFlying) return; var now Date.now(); if (now - this.lastQueryTime this.options.minInterval) return; var currentPosition this.viewer.camera.positionWC; if (this.lastPosition) { var distance Cesium.Cartesian3.distance(currentPosition, this.lastPosition); if (distance this.options.stillThreshold) { this.lastPosition Cesium.Cartesian3.clone(currentPosition); return; } } this.lastPosition Cesium.Cartesian3.clone(currentPosition); this.lastQueryTime now; this.queryWeather(); }; CameraWeatherReporter.prototype.queryWeather function() { var cartographic Cesium.Cartographic.fromCartesian( this.viewer.camera.position, Cesium.Ellipsoid.WGS84, new Cesium.Cartographic() ); var lon Cesium.Math.toDegrees(cartographic.longitude); var lat Cesium.Math.toDegrees(cartographic.latitude); var height cartographic.height; if (!isValidPosition(lon, lat, height)) return; var roundedLon lon.toFixed(2); var roundedLat lat.toFixed(2); var cacheKey roundedLon , roundedLat; // 检查缓存10分钟内不重复请求 var cached this.weatherCache.get(cacheKey); if (cached Date.now() - cached.timestamp 10 * 60 * 1000) { this.updatePanel(cached.data, parseInt(height)); return; } var seq this.requestSeq; var self this; // 这里替换成你自己的后端代理地址 fetch(/api/weather?lon roundedLon lat roundedLat) .then(function(response) { return response.json(); }) .then(function(data) { if (seq ! self.requestSeq) return; self.weatherCache.set(cacheKey, { timestamp: Date.now(), data: data }); self.updatePanel(data, parseInt(height)); if (self.options.enableSceneLinking) { self.applyWeatherEffect(data.weather); } }) .catch(function() { // 失败静默处理不打断用户操作 }); };6.2 与SuperMap场景绑定在主场景初始化完成、地形或影像加载成功之后实例化这个类var viewer new Cesium.Viewer(cesiumContainer, { // 你的初始化配置 }); var weatherReporter new CameraWeatherReporter(viewer, { minInterval: 5000, enableSceneLinking: true, enablePanel: true });这样用户可以在场景里自由飞行停下来之后页面右下角会出现一张小卡片显示当前位置的经纬度、高度、天气、温度。如果场景里挂了粒子系统天会随查询结果变化。6.3 这个模块的扩展空间这个CameraWeatherReporter只是满足“汇报相机位置天气情况”的最小可用版本扩展空间很大把天气接口返回的更多字段湿度、紫外线、空气质量加进面板把天气联动扩展到其他业务实体比如某个区域的设备状态、巡逻点位把“汇报”的对象从UI面板改成语音播报想象一下飞行到某个城市时自动播报“当前到达上海市小雨温度18度”这个体验会非常好把相机的移动轨迹记录下来和天气数据叠加成一条“时间-位置-天气”的回放曲线事后做路径复盘非常有用我在实际项目中就接过语音播报用的是浏览器的SpeechSynthesis接口效果出乎意料地好。甲方对这个功能印象很深认为“系统很聪明”。7. 实际项目里最容易翻车的三个细节这一节单独拎出来聊聊我在项目里踩过的细节问题。这几个问题不解决功能看起来是好的但用起来就很别扭。第一个细节中国区域影像加载完成后相机默认位置与经纬度换算精度会受地形数据源影响。有些地形服务的精度并不均匀在城市区域可以精确到几米在偏远地区可能偏差几百米。天气接口按经纬度查询时这个偏差通常不影响结果但如果你有按坐标解析地址的需求就需要注意服务商的数据质量。第二个细节多显示器或浏览器标签页切换时camera.changed的触发频率会异常。当页面在后台运行浏览器的requestAnimationFrame会暂停或降频但场景状态恢复后会有一波集中的位置更新。如果你的节流逻辑只做了“间隔”判断没做“任务队列去重”几个请求会同时发出去。解决办法是在handleCameraChanged里加一个isQuerying布尔标记保证同时只有一个天气查询在途。第三个细节面板上的天气文字不要直接透传接口字段。不同天气服务商返回的天气描述五花八门有的返回“多云转晴”有的返回“Clouds”有的返回“阴天有雨”。建议在代码层做一层映射统一成你自己的枚举sunny/cloudy/overcast/rain/snow/foggy再转成展示文案。这样后续更换天气服务商时UI和场景联动逻辑都不用动只改映射表。这第三个细节的工程意义很大。我最初直接接的高德接口后来换到和风天气前后端联调和UI适配花了两天。如果一开始就设计好枚举映射半天就能切换完。最后再分享一个我从这个项目里带走的经验三维场景的需求很多看着是“展示型功能”本质是“决策辅助工具”。甲方说“想看到相机的天气情况”不代表他要一个天气软件他要的是把环境信息嵌到他的作业流程里让系统替他去感知周围。理解了这一层你做的功能永远比需求文档上写的再多一步——这一步就是价值所在。