Cesium动态天空盒实战：旋转矩阵与序列帧方案全解析

上个月在做一个智慧园区数字孪生项目场景里需要模拟一天中从黎明到夜晚的光照变化云层和星空也要跟着动。默认的 Cesium 天空盒是一张静态的六面立方体贴图客户第一次看到就问了句“这个背景是不是贴图贴死了” 从那以后我开始花时间研究如何在 Cesium 里做出会旋转的动态天空盒。折腾了大概两周试过改源码、试过序列帧、也踩过不少 Cesium 版本升级后带来的坑最后总算整理出一套能落地的方案。这篇内容适合正在做数字孪生、智慧城市、三维可视化项目的 Cesium 开发者。如果你只是想在默认地球上换个天空盒贴图那不用看这篇但如果你需要让太阳、云层、星空场景真正“动起来”并且让模型阴影和天空光照方向保持一致这篇会很有用。核心思路有两个一是直接改造 Cesium 引擎内部的 SkyBox给它增加旋转矩阵支持二是不动引擎用预渲染的序列帧动态切换天空盒贴图。两条路各有取舍下面我会把原理、代码、坑和优化全部分享出来。1. 为什么默认天空盒不够用旋转方案又好在哪1.1 默认天空盒的静态局限Cesium 的Viewer在创建时会自动带一个默认天空盒通常是一个星空背景由六张贴图组成对应立方体的六个面。它在三维空间里表现为一个无限远的包围盒相机动、它不动本质上就是根据相机视线方向去 CubeMap 里采样颜色。默认天空盒的问题不在于贴图质量而在于它是完全静态的。没有时间概念没有云层流动没有太阳从东到西的位置变化。对于传统 GIS 场景这个静态星空可能无所谓但一旦到数字孪生、影视预演、科研仿真这类对时空一致性要求高的场景静止天空就会显得“假”。有人可能想那我直接把默认天空盒的三十张贴图在 PhotoShop 里处理一遍加个太阳和云彩不就行了吗可以但这只是换了张静态图。客户要求的是上午九点太阳在东边、下午四点太阳在西边这个需求靠单张贴图根本满足不了。1.2 旋转天空盒到底解决什么问题旋转天空盒的核心逻辑很简单让立方体贴图的采样方向随时间发生变化。你 0 点时正东方向是星空到早上 6 点时正东方向变成了日出贴图区域。视觉上看起来整个天穹在缓慢转动太阳和星星的位置都跟着移动。这个方案最大的优点是轻量。它不需要额外加载成百上千张贴图不需要后台服务不需要复杂的流体模拟。你只需要准备一组标准六面天空盒贴图再在渲染阶段对采样向量做一个数学变换就能模拟出天空随时间变化的效果。配合场景内光源方向一起旋转还能让太阳位置和实体阴影保持同步这是不少“伪动态天空”方案最容易忽略的地方。至于为什么不直接用 WebGL 的纹理旋转参数、为什么不直接旋转整个场景我在第二章会讲清楚。先记住一点Cesium 的天空盒渲染走的是 Shader 采样修改采样向量是最干净、最可控的做法。1.3 两条技术路线怎么选根据项目约束我整理了两条可落地的路线先把对比结果放出来方案改动量动态程度资源消耗适合场景方案A修改 Cesium 内置 SkyBox增加旋转 uniform中需要重新构建引擎高支持连续旋转和实时光照同步低只多一个矩阵计算长期项目、核心展示需要高真实感方案B序列帧动态切换天空盒贴图低不改引擎中取决于帧序列长度和切换频率高预渲染图片占空间和显存快速 Demo、非核心展示、一次性的活动页面我个人的判断标准是如果你能接受在项目里使用自编译的 Cesium并且以后还会做光照、雾效、昼夜节律这类高性能需求定制那一定要选方案A。改一次源码之后很多效果都能在引擎层顺手做掉如果你只是做一个三五天的原型验收或者团队里禁止改引擎包那方案B更稳毕竟不动核心代码风险小得多。方案A看起来复杂但操作路径很清晰关键是找到 SkyBox 的 Shader 文件和 JS 文件插入旋转矩阵后重新构建。下面两章先解决原理问题再进入实战。2. SkyBox 渲染原理和旋转的数学基础2.1 天空盒本质上是一个方向采样器天空盒说穿了就是一个“方向到颜色”的查表过程。场景中的相机在一个非常大的立方体中心这个立方体不会因为相机移动而移动相机永远位于中心。渲染时对每个像素根据相机的视线方向去CubeMap纹理中取色就得到了看似无限远的背景。Cesium 内置的 SkyBox 也是这个思路。它用了一个单位立方体几何体顶点位置直接作为纹理坐标传入片段着色器后用textureCube采样。由于立方体足够远透视投影后所有方向都会覆盖屏幕所以看起来就像整个天穹都贴上了纹理。Cesium 原始的 SkyBox 着色器核心逻辑是这样的不同版本写法略有差异// SkyBoxVS.glsl attribute vec3 position; varying vec3 v_texCoord; void main() { v_texCoord position; gl_Position czm_viewProjection * czm_model * vec4(position, 1.0); }// SkyBoxFS.glsl varying vec3 v_texCoord; uniform samplerCube u_cubeMap; void main() { vec4 color textureCube(u_cubeMap, v_texCoord); gl_FragColor color; }注意片段着色器里采样的关键变量是v_texCoord。它代表的不是某个平面纹理坐标而是空间中的方向向量。如果我们能让这个方向向量整体绕某个轴旋转一个角度那么从相机里看到的结果就是“整个天穹在转”。2.2 旋转矩阵怎么作用到采样向量上要让天空盒绕 Y 轴旋转最直接的办法是构造一个绕 Y 轴旋转的 3x3 矩阵把采样方向向量乘上去。数学表达式很基础绕 Y 轴旋转 θ 角度后的方向向量是x x * cosθ z * sinθ y y z -x * sinθ z * cosθ在 Cesium 里这对应Cesium.Matrix3.fromRotationY(angle, result)这个 API。它会生成一个符合 Cesium 右手坐标系的矩阵。需要特别说明的是Cesium 里绕 Y 轴到底往哪个方向偏和你在 WebGL 里默认的旋转手势可能不完全一致。因为 Cesium 的地理坐标系、相机坐标系和普通三维建模软件的轴定义有差异实际项目中如果你发现太阳是往反方向转把角度取个负号或者用Matrix3.transpose转置一下矩阵就好。这个不是智商问题是坐标习惯问题。片段着色器里加上旋转矩阵后代码变成uniform mat3 u_rotation; void main() { vec3 dir normalize(u_rotation * v_texCoord); vec4 color textureCube(u_cubeMap, dir); gl_FragColor color; }由于textureCube对非归一化向量是会做内部处理的但为了后续可能增加的边缘采样逻辑还是建议先normalize一次。数学上旋转矩阵不会改变向量长度所以这一步不影响结果但能让你在调试其他效果时少一些隐患。2.3 为什么不能直接旋转 CubeMap 纹理本身有新手朋友会问能不能在 JavaScript 里给贴图对象设置一个旋转角度很遗憾WebGL 的 CubeMap 纹理就是六张 2D 纹理组合纹理采样器只有 wrap、filter、mipmap 等参数没有“旋转纹理”这个概念。你可以调整 Tiling 或 offset但那主要面向 2D 纹理不能对立方体贴图做整体旋转。也有人想那我不改 Shader每帧生成一张新的六面贴图再传进去行不行理论上行但代价是每帧要重新上传六张图片到 GPU显存带宽和 CPU 编码压力都很大。做一两次演示没问题做成长期产品性能上吃不消。所以最优雅的方案仍然是改采样向量。理解了这一步方案A的所有技术门槛基本就消除了剩下的就是找对文件、改对地方。3. 实战方案A改造 Cesium 引擎给 SkyBox 增加旋转支持3.1 改造前的环境与源码准备如果你使用的是 Cesium 1.9x 及以上版本源码目录结构是packages/engine/Source/...如果用的是老版本则直接把packages/engine去掉路径变成Source/...。需要改的核心文件有三个SkyBox.js天空盒的 JS 逻辑负责创建 DrawCommand、管理纹理对象。SkyBoxVS.glsl顶点着色器一般不用动。SkyBoxFS.glsl片段着色器旋转逻辑加在这里。先准备一个能构建的 Cesium 工程。最简单的方式是克隆官方仓库然后执行npm install。注意构建工具链需要 Node.js 环境推荐使用 Node 16 或 18太新或太旧都可能遇到和 Cesium 构建脚本不兼容的问题这是个常识性坑。在动手之前建议先把源码对应文件打开看一遍搜索u_cubeMap这个 uniform你就能看到 SkyBox 的着色器是如何被引用的。不同 Cesium 版本里这段代码的位置可能有迁移但命名通常不会变搜索是很可靠的定位方式。3.2 修改片段着色器加旋转矩阵找到SkyBoxFS.glsl把它改成下面这样varying vec3 v_texCoord; uniform samplerCube u_cubeMap; uniform mat3 u_rotation; void main() { vec3 dir normalize(u_rotation * v_texCoord); vec4 color textureCube(u_cubeMap, dir); gl_FragColor color; }这里新增的u_rotation是个 3x3 矩阵。之所以用 3x3 而不是 4x4是因为采样向量是方向向量不是带位置的点向量不需要平移用 3x3 就够了。这一行改动不会显著增加 GPU 负载矩阵乘法在片段着色器里几乎可以忽略不计。如果你想在三维空间里同时绕 X、Y、Z 轴旋转也可以在 CPU 端把三个轴的旋转矩阵相乘得到一个复合矩阵后传进来。这个自己按需求扩展即可。3.3 在 SkyBox.js 里创建并更新旋转矩阵打开SkyBox.js在构造函数末尾增加两个成员变量this._rotation options.rotation || 0.0; this._rotationMatrix Matrix3.clone(Matrix3.IDENTITY);options.rotation是你希望天空盒初始绕 Y 轴旋转的角度值单位是弧度。默认给 0表示不旋转和原来的行为保持一致。然后在SkyBox.prototype.update方法里创建 DrawCommand 之前加一段更新逻辑if (defined(this._rotation)) { Matrix3.fromRotationY(this._rotation, this._rotationMatrix); }接下来找到创建 DrawCommand 时传入的uniformMap。SkyBox 内部本来就会绑定u_cubeMap我们只需要再加入一个u_rotationuniformMap: { u_cubeMap: function() { return skyBox._cubeMap; }, u_rotation: function() { return skyBox._rotationMatrix; } }这里要特别提醒一下不同版本 Cesium 中uniformMap对象的字段名可能不是u_cubeMap也可能是u_texture你需要以实际源码为准。但整体思路是完全一样的先找到原有 uniform再往里追加一个矩阵 uniform。你可以在控制台打印 SkyBox 的命令对象来调试也可以直接打开构建后的产物搜索SkyBoxFS字符串再回推相应位置。3.4 重新构建并接入项目修改完源码后执行 Cesium 的标准构建命令npm run build -- --release构建完成后会输出新的Cesium.js和Cesium.css把项目里的 Cesium 依赖替换成这个自编译版本即可。接入时只需要在创建 Viewer 后手动设置一次 skyBoxconst viewer new Cesium.Viewer(cesiumContainer); viewer.scene.skyBox new Cesium.SkyBox({ sources: { positiveX: ./skybox/px.jpg, negativeX: ./skybox/nx.jpg, positiveY: ./skybox/py.jpg, negativeY: ./skybox/ny.jpg, positiveZ: ./skybox/pz.jpg, negativeZ: ./skybox/nz.jpg }, rotation: Cesium.Math.toRadians(30) });如果希望太阳和星空随时间连续旋转可以直接监听 Cesium Clock 的 tick 事件viewer.clock.onTick.addEventListener(function(clock) { const date Cesium.JulianDate.toDate(clock.currentTime); const hours date.getHours() date.getMinutes() / 60; // 一天转一圈负号根据实际方向调整 const angle -Cesium.Math.TWO_PI * hours / 24; viewer.scene.skyBox._rotation angle; });我这里写的是_rotation因为如果只改了SkyBox.js而没有为它写 setter 方法那么直接访问内部变量是最快的办法。如果你打算长期使用最好在SkyBox上定义一个正式的rotation属性内部再同步更新_rotationMatrix这样代码会干净很多。3.5 同步场景光照方向不然太阳会“分裂”如果只旋转天空盒你会看到一个很尴尬的问题天空贴图里的太阳已经转到西边了但建筑物、地形的阴影还保持在上午方向。这是因为 Cesium 默认的光照方向和天空盒完全是两套逻辑。解决办法是手动指定场景光照方向让它跟随天空盒的旋转矩阵const originalSunDir new Cesium.Cartesian3(1.0, 0.2, 0.3); const rotatedSunDir new Cesium.Cartesian3(); viewer.clock.onTick.addEventListener(function(clock) { const angle ...; // 与天空盒旋转角度保持一致 const rotationMatrix Cesium.Matrix3.fromRotationY(angle, new Cesium.Matrix3()); Cesium.Matrix3.multiplyByVector(rotationMatrix, originalSunDir, rotatedSunDir); viewer.scene.lightDirection rotatedSunDir; });这样设置以后场景里的地形、3D Tiles、模型的光照方向都会跟着旋转。太阳在天空盒里的位置和实体的受光面就能基本对齐视觉上才完整。这部分内容看着不难但极其容易被忽略我在第五章会再展开一次真实太阳方向的计算。4. 实战方案B不改引擎的序列帧动态天空盒4.1 序列帧的原理和适用边界如果你的项目不允许改引擎源码或者临时要出一个效果给客户看那可以用序列帧方案。原理不复杂提前渲染好一组六面平方图每组对应一个时间点。比如从日出到日落每隔一分钟渲染一帧总共 720 帧然后用定时器按顺序不断替换scene.skyBox的纹理源。这个方案本质上是在用“图片序列”模拟“连续旋转”。每一帧里太阳的位置都略微偏移连续切换时就会出现天空旋转的视觉效果。它比改源码简单得多不碰任何底层实现只是在 JS 层替换天空盒的资源。但代价也很明显。720 帧乘以六张贴图假设每张贴图 1MB就是 4GB 以上的资源量浏览器根本承受不了。实际项目中一般会降低到 30 帧或者 60 帧并且每帧贴图压缩后控制在几百 KB才勉强可接受。4.2 用预加载图片资源实现帧切换我这里给一个可运行的思路。先把所有帧的图片资源预加载到内存里而不是在切换时才发起 HTTP 请求可以大幅减少闪烁。const FRAME_COUNT 60; const frameImages []; // 预加载第 i 帧的六张贴图 async function preloadFrames() { for (let i 0; i FRAME_COUNT; i) { const promises [ loadImage(./skybox/frame_${i}_px.jpg), loadImage(./skybox/frame_${i}_nx.jpg), loadImage(./skybox/frame_${i}_py.jpg), loadImage(./skybox/frame_${i}_ny.jpg), loadImage(./skybox/frame_${i}_pz.jpg), loadImage(./skybox/frame_${i}_nz.jpg) ]; frameImages.push(await Promise.all(promises)); } } function updateSkyBoxFrame(index) { const views [positiveX, negativeX, positiveY, negativeY, positiveZ, negativeZ]; const sources {}; for (let j 0; j views.length; j) { sources[views[j]] frameImages[index][j]; } viewer.scene.skyBox new Cesium.SkyBox({ sources: sources }); }定时切换时建议 8 到 12 帧每秒就已经能看出较流畅的动画不需要 60fps。帧率太高一方面资源消耗大另一方面 Cesium 内部每帧都在创建新的纹理资源容易造成 GPU 内存抖动。4.3 序列帧方案的性能优化与注意事项序列帧方案最大的问题是每次新建SkyBox实例都会重新创建 GPU 纹理。如果每秒切换 12 次那就是每秒创建 72 张纹理长时间跑下来内存占用会逐渐增加。我建议控制切换频率8fps 足够。使用ImageBitmap代替HTMLImageElement可以避免主线程解码卡顿。在切换出旧帧后手动调用相关纹理的销毁方法或者至少置空引用方便 GC 回收。如果发现页面在摄像机大幅旋转时出现明显卡顿甚至崩溃多半是纹理创建和销毁竞争导致这时候需要降低切换频率或者回到方案A。另外现实项目中很少会自己预渲染天空盒序列。比较常见的做法是从天气服务商购买动态天空盒视频或序列帧或者用 Blender、Houdini 渲染好一段天穹动画后拆帧。千万不要试图从 Cesium 默认天空盒里直接抓帧会产生接缝和畸变。5. 动态光照同步让太阳、阴影和天空盒“步调一致”5.1 为什么 Cesium 默认光照和天空盒是两码事Cesium 场景中的物体光照方向由scene.lightDirection控制。如果你不手动设置它Cesium 会根据当前时刻和相机方位自动计算一个太阳方向。问题在于这个自动计算用的是 Cesium 内部天文算法和我们自己旋转天空盒贴图时的角度没有任何关联。这就可能导致一个反直觉的现象天空盒贴图里的太阳明明在东边但实体模型的阴影却朝向北边。尤其在做智慧城市楼宇光影分析时这个错误是致命的。所以动态天空盒必须和动态光照一起做否则等于只做了一半。5.2 手动指定光照方向最简单的同步方法是强制设置viewer.scene.lightDirection。你可以先固定一个方向的单位向量然后把它乘以天空盒的旋转矩阵。这样天空转到哪个角度光照方向就跟着转到哪个角度两者天然一致。const baseSunDir Cesium.Cartesian3.normalize( new Cesium.Cartesian3(-1.0, 0.4, 0.5), new Cesium.Cartesian3() ); function updateLight(rotationMatrix) { Cesium.Matrix3.multiplyByVector( rotationMatrix, baseSunDir, viewer.scene.lightDirection ); }这段代码里的viewer.scene.lightDirection是 Cesium 的一个可写属性设置后就会覆盖默认的自动太阳方向。地形启用光照后viewer.scene.globe.enableLighting true地表亮度也会随之变化。5.3 按真实时刻计算太阳方位如果你的项目需要模拟真实世界某个日期、某个地理位置的太阳轨迹可以用 Cesium 自带的Simon1994PlanetaryPositions计算太阳方向这个 API 也是 Cesium 官方自己计算自动光照时用的const now Cesium.JulianDate.now(); const sunDir Cesium.Simon1994PlanetaryPositions.computeSunDirectionInWorld( now, new Cesium.Cartesian3() );拿到真实太阳方向后再叠加我们想要的时间偏移模拟另一天的效果或旋转矩阵就能做到“基础方向来自真实天文计算视觉展示上再按需求缩放和旋转”。有一点要注意computeSunDirectionInWorld返回的是世界坐标系下的方向而 Cesium 的 Y 轴、Z 轴和经纬度关系需要你稍微熟悉一下才可以确定具体方位。如果发现阳光方向和经纬度对不上检查一下是不是坐标系轴方向理解反了。我自己实际项目里的做法是天数影响太阳方位角小时影响太阳高度角然后把这两个角度组合成旋转矩阵叠加到天空盒的旋转矩阵上再传给lightDirection。效果比单纯固定方向真实很多复杂度也没有明显上升。6. 常见问题与排查技巧实录6.1 天空盒不显示直接黑屏这是最常遇到的问题原因通常有三个第一六张贴图有一张加载失败。Cesium 对天空盒贴图加载失败经常是静默的控制台只报一个 404但画面就是黑屏。建议在加载前先自己检查所有 URL 是否有有效资源。第二贴图跨域问题。如果你的天空盒贴图放在 CDN 或 OSS 上必须配置 CORS 跨域访问否则 WebGL 无法读取像素。第三修改源码方案里没把 uniform 绑定好导致 Shader 编译报错此时控制台会有 GLSL 编译错误日志仔细看就会发现问题。解决方案很简单先任意替换成 Cesium 默认的天空盒贴图路径如果还能显示那就是你的贴图或 URL 问题如果替换后也不显示那就是代码里的 uniform 绑定或 Shader 修改有问题。6.2 旋转后纹理拉伸、接缝错乱天空盒纹理接缝错乱大概率是六面的图片顺序不对。CubeMap 的 X、-X、Y、-Y、Z、-Z 是有一套严格顺序的不同工具的导出顺序可能完全不同。建议用最朴素的调试方法准备一张各面颜色都不同的测试图比如正X用红色、负X用蓝色然后顺时针去看确认每张贴图应该放在哪个面上。旋转后出现轻微拉伸则一般发生在textureCube采样边界。处理方法是在采样前把方向向量 normalize并保证旋转矩阵用的是规范正交矩阵。Cesium 的Matrix3.fromRotationY生成的是标准旋转矩阵不会有比例拉伸问题。6.3 光照方向始终对不上如果你已经设置了viewer.scene.lightDirection但太阳光看起来还是不对很可能是光照方向向量没有单位化或者旋转矩阵和天空盒旋转矩阵不是同一个。因为lightDirection在实际计算中会被归一化所以长度问题不大关键是两个矩阵要严格一致。另外3D Tiles 的光照方向可能在数据本身的法线贴图上有特殊设置不排除个别模型法线烘焙固化导致阴影和实时光照不一致。这种情况和天空盒无关属于模型制作问题。6.4 摄像机大幅旋转时出现卡顿甚至崩溃动态天空盒本身不会导致这种问题但如果用序列帧方案在摄像机旋转时高频新建 SkyBox 对象确实可能因为纹理创建竞争导致崩溃。我遇到过几次在 3D 地球快速滚动缩放时页面直接卡死的情况排查下来都是因为序列帧切换时创建了一张无效的ImageBitmap导致后续 Cesium 内部纹理对象状态错乱。解决方案是不要每帧都调用new Cesium.SkyBox()至少间隔 80ms 以上。预加载所有帧不要在切换时才异步请求图片。如果必须在旋转过程中平滑切换尽量升级到方案A让 GPU 只计算一个矩阵乘法不涉及纹理重建。6.5 真机性能表现改源码方案的性能开销几乎可以忽略。加了一个 3x3 矩阵乘法和一次 normalize这在中低端手机 GPU 上也是很小的工作量。真正影响帧率的往往是场景模型数量和地形瓦片加载天空盒旋转本身不会成为性能瓶颈。序列帧方案则要非常谨慎。我测试过 15fps 切换六张 1024x1024 的 JPEG在中端笔记本上勉强流畅在手机上是明显有卡顿感的。如果需要移动端展示建议把贴图压缩到 512x512并把切换频率降到 10fps 以下不然功耗和显存占用都会很难看。6.6 常见问题速查表为了方便后面排查我把这几个高频问题整理成一张表现象可能原因解决思路天空盒黑屏贴图加载失败 / CORS / uniform 未生效先替换默认贴图测试检查控制台错误日志接缝错乱CubeMap 六面顺序不对用单色测试图逐面确认太阳位置正确但阴影错误lightDirection 未同步旋转把光照方向乘同一个旋转矩阵卡顿或崩溃频繁重建 SkyBox / 纹理资源竞争降低帧率预加载图片或改引擎方案个人体会是动态天空盒最大的难点不在 Shader 或矩阵而在问题定位画面不对时你很难一眼看出是贴图问题、矩阵问题还是光照问题。所以建议一开始就把天空盒旋转和光照同步做成一个独立的模块单独调试通过后再集成到业务场景里别等整个场景都加载完再排查。最后再分享一个小技巧如果只需要在某个时间段做快速验证可以先写死一个小的旋转角度比如rotation: Cesium.Math.toRadians(15)确认天空背景变化无误后再接入 Clock 或真实天文算法。这样能把变量隔离到最小踩坑的概率会低很多。