企业官网建设流程全解析

简介：面向需要在Cesium三维场景中展示动态GIF图片的WebGIS开发者，这份资源聚焦Cesium不直接支持GIF格式的痛点，提出一套基于@loaders.gl的渐进式实现方案，而非单纯贴图或生成Spritesheet的简易替代。资源围绕五个关键环节展开说明：依赖安装与版本搭配、GIF图像异步读取、TextureAtlas帧序列拆分、自定义Material与着色器绑定，以及利用postRender事件驱动逐帧更新动画；其中对于多帧GIF如何切分纹理坐标、如何规避WebGL纹理尺寸限制和性能损耗等细节也有具体交代，能帮助读者梳理从图片解码到纹理上传再到动画播放的完整链路。压缩包约15.03MB，体积适中，以示例代码和说明为主体，适合具备一定Cesium基础、正在开发动态标记、广告牌或信息弹窗特效的开发者移植复用。目前已有731人学习下载，不失为一份聚焦Cesium动图应用的实用参考资料。

1. Cesium 加载 GIF 图片为什么不能直接挂 URL

把 GIF 地址直接塞给viewer.entities.add({ billboard: { image: url } })，大概率只有第一帧固定在地球上，或者干脆变成一张空白图。原因不在 Cesium，而在 WebGL 的纹理接口texImage2D只接受静态图像源，浏览器里的 GIF 动画播放是靠 HTML 引擎独立调度，并不会自动把每一帧同步到 GPU 纹理。更麻烦的是，@loaders.gl/images虽然能解 GIF，默认也只返回当前帧，要让它真正动起来，必须自己拆帧、传纹理、再按帧切换。下面从拆帧到挂接BillboardCollection写一遍完整流程，适合做雷达回放、告警点、轨迹流动标记的开发者；方案可以原样搬进 3D Tiles、热力图或 MVT 叠加的项目里。

2. 拆帧与数据管线：用 gifuct-js 把 GIF 变成逐帧位图

2.1 为什么 WebGL 不认 GIF 动图

WebGL 的纹理上传最终都会落到texImage2D/texSubImage2D，它们接受HTMLImageElement、HTMLCanvasElement、ImageData或ImageBitmap，却没有“GIF 动画序列”这个类型。浏览器渲染 GIF 动图是在img元素所在的文档渲染管线里完成的，每一帧由解码器推进，然后由页面合成器显示出来，这个过程的结果不会自动出现在一个可供 WebGL 查询的纹理对象里。Cesium 的 Billboard 虽然支持image直接传 URL，但 URL 经过异步加载后已经变成静态纹理，所以你会看到第一帧。

2.2 静态图让 @loaders.gl/images 处理，动态帧交给 gifuct-js

先装依赖：

npm install cesium gifuct-js @loaders.gl/core @loaders.gl/images

@loaders.gl/images在这个场景里的价值是统一加载 JPEG、PNG、WebP 这类静态图，生成ImageBitmap后可以快速传给Cesium.TextureAtlas。但对 GIF，它的ImageLoader默认只拿到一帧，所以动画拆帧我用gifuct-js：

import { load } from '@loaders.gl/core'; import { ImageLoader } from '@loaders.gl/images'; import { parseGIF, decompressFrames } from 'gifuct-js'; async function loadGifFrames(url) { const buffer = await fetch(url).then((res) => res.arrayBuffer()); // 解析 GIF 头与图像控制扩展 const gif = parseGIF(buffer); // 第二个参数传 true，让每一帧都输出为完整帧，避免增量帧不合成 const frames = decompressFrames(gif, true); return frames; }

这里parseGIF负责解读 GIF87a/89a 的文件结构，decompressFrames负责还原每一帧的像素数据。第二个参数true是必须的：很多 GIF 为了压缩体积，后一帧只记录和前一个静态帧不同的区域，也就是增量帧；不合成的话，你拿到的frame.patch只是局部像素，直接上传纹理就会出现残缺画面。

2.3 把帧数据转成 Canvas 帧序列

decompressFrames返回的每个frame包含patch、dims、delay等字段。patch是Uint8ClampedArray，顺序是 RGBA，正好可以塞进ImageData。我一般会把它转成一组HTMLCanvasElement，因为这是 Cesium 纹理上传兼容性最好的格式：

function framesToCanvas(frames, width, height) { const tempCanvas = document.createElement('canvas'); tempCanvas.width = width; tempCanvas.height = height; const ctx = tempCanvas.getContext('2d'); const imageData = ctx.createImageData(width, height); return frames.map((frame) => { imageData.data.set(frame.patch); ctx.putImageData(imageData, 0, 0); const frameCanvas = document.createElement('canvas'); frameCanvas.width = width; frameCanvas.height = height; frameCanvas.getContext('2d').drawImage(tempCanvas, 0, 0); return frameCanvas; }); }

tempCanvas只是中转站，每一帧都重新绘制一份独立 canvas，避免后面TextureAtlas.addImage异步处理时引用了同一块正在变化的画布。width和height从gif.lsd.width/gif.lsd.height取，lsd是逻辑屏幕描述符，代表 GIF 画布尺寸。如果你的 GIF 有大量透明背景，RGBA 的 alpha 通道会原样保留，后续纹理就不容易出现黑底。

到这里，数据管线已经打通：GIF 变成了一个可索引的 canvas 数组，下一步要做的是把它们合并进 Cesium 的 GPU 纹理体系。

3. TextureAtlas 合并帧序列：让 BillboardCollection 动起来

3.1 为什么不建议把 Canvas 直接传给 entity.billboard.image

很多入门代码会让你把canvas塞给billboard.image，然后自己用setInterval重绘画布。这在单独跑一个 GIF 时确实能显示，但有两个问题：Cesium 不会主动监听 canvas 内容变化，要让它重新上传纹理，往往得再触发一次entity.billboard.image = canvas，而这个赋值会重新走一遍纹理创建，频繁操作会堆积纹理对象；另外一个 canvas 只能服务一个 billboard，当日志点数量超过几十个，浏览器内存和 GPU 显存都会很难看。更稳的做法是用Cesium.TextureAtlas。

3.2 创建 TextureAtlas 并挂到 BillboardCollection

TextureAtlas本质上是一张大纹理，你可以把 GIF 的每一帧作为一个小图往里塞，之后用imageIndex指向具体帧。Cesium 的BillboardCollection自带atlas属性，新增 billboard 时只要指定imageIndex，就可以在同一张大纹理上来回切换：

async function createGifAtlas(viewer, frameCanvases) { const atlas = new Cesium.TextureAtlas({ context: viewer.scene.context, borderWidthInPixels: 1, // 避免相邻帧采样串色 }); await Promise.all( frameCanvases.map( (canvas) => new Promise((resolve) => { atlas.addImage(canvas, resolve); }) ) ); return atlas; } const gifAtlas = await createGifAtlas(viewer, frameCanvases); const billboards = viewer.scene.primitives.add( new Cesium.BillboardCollection({ atlas: gifAtlas, }) ); const billboard = billboards.add({ position: Cesium.Cartesian3.fromDegrees(120.1, 30.2, 50), imageIndex: 0, scale: 1.0, verticalOrigin: Cesium.VerticalOrigin.BOTTOM, });

context来自viewer.scene.context，它是 Cesium 为 WebGL 上下文做的封装，TextureAtlas必须用它来创建。borderWidthInPixels设为 1，是为了在图集内部每个子图四周留一点空白边界，防止纹理过滤时采样到相邻 GIF 帧的颜色。atlas.addImage是异步操作，回调在 GPU 纹理真正更新后触发，所以要用Promise包一层，等全部添加完成再创建 billboard，否则imageIndex可能会报错或显示成空白。

3.3 postRender 驱动帧切换

帧切换不需要重建图集，只需在每一帧把billboard.imageIndex改为下一帧。这里我直接用viewer.scene.postRender事件：

let frameIndex = 0; let lastSwitchAt = performance.now(); viewer.scene.postRender.addEventListener(() => { const now = performance.now(); const delay = frames[frameIndex].delay || 100; if (now - lastSwitchAt >= delay) { frameIndex = (frameIndex + 1) % frames.length; billboard.imageIndex = frameIndex; lastSwitchAt = now; } });

frames是loadGifFrames返回的原始帧数组，拿delay做时间闸门，而不是每帧都切一次。GIF 的帧延时不会特别均匀，有的帧 30ms，有的帧 80ms，直接用performance.now()累加，比setInterval(fixedRate)更接近原始动画节奏。frameIndex到达末尾后回卷到 0，相当于完成了循环播放；如果某个 GIF 只需要播一次，判断frameIndex + 1 === frames.length后移除即可。

表格里顺带提了 video，这是另一个可考虑的方向，但没有 GIF 灵活，后面第 5 章再展开。

4. 实战：多 GIF 标记、3DTiles 与热力图场景的叠加写法

4.1 多个 GIF 标记共享一个 TextureAtlas

实际项目里很少只挂一个 GIF。比如雷达回波范围、设备状态灯、车辆运行动画，多个标记可以共用同一个TextureAtlas，只是每个 billboard 持有不同的imageIndex。我一般会把这些状态封装成一个简单的动画管理器：

const animatedItems = []; function addGifBillboard(options) { const billboard = billboards.add({ position: options.position, imageIndex: options.startFrame || 0, scale: options.scale || 1.0, }); animatedItems.push({ billboard, frames: options.frames, currentIndex: options.startFrame || 0, lastSwitchAt: performance.now(), }); }

更新时遍历这个列表，按各自的delay切帧：

viewer.scene.postRender.addEventListener(() => { const now = performance.now(); for (const item of animatedItems) { const delay = item.frames[item.currentIndex].delay || 100; if (now - item.lastSwitchAt >= delay) { item.currentIndex = (item.currentIndex + 1) % item.frames.length; item.billboard.imageIndex = item.currentIndex; item.lastSwitchAt = now; } } });

这样做的收益是：所有 GIF 帧都在同一张大纹理里，imageIndex切换不涉及上传操作，GPU 只需要按索引采样，性能远好于每个标记独立创建 canvas 或 URL。

4.2 让标记跟随 3DTiles 单体化对象

当动态 GIF 想跟随某个 3DTiles 单体化对象时，不需要把 GIF 挂到 model 上，直接在postRender里更新billboard.position就行。常见做法是先用viewer.scene.pick拿到Cesium3DTileFeature，从 feature 的primitive和content里算出包围球中心，再转成Cartesian3：

const picked = viewer.scene.pick(windowPosition); if (picked instanceof Cesium.Cesium3DTileFeature) { const center = picked.content.boundingSphere?.center; if (center) { billboard.position = center; } }

这种方式对 3D Tiles 本身没有任何侵入，模型照样走 LOD 调度，动态告警点也不会因为频繁修改模型材质而触发重新编译着色器。与 cesium 3dtiles 单体化配套时，最关键的是不要把scene.pick放进每一帧调用，postRender本身就发生在渲染后，此时再 pick 会多做一次 CPU 遍历；我一般在鼠标点击或定时器的低频率事件里更新目标位置，动画只负责切imageIndex。

4.3 与 MVT、动态光照和热力图叠加时的刷新节奏

场景里一旦出现 cesium 加载 MVT 格式、动态光照、热力图这类高频 CPU 计算任务，就要控制 GIF 动画的刷新节奏。不要为每个 GIF 单独开setInterval，统一收敛到一个postRender回调，并且把帧切换和requestRender错开。如果项目已经打开requestRenderMode，必须在切换imageIndex后调用viewer.scene.requestRender()，否则画面不会重绘，GIF 停在旧帧；如果关闭了requestRenderMode，Cesium 默认持续渲染，反而不需要额外调用，但要注意 GIF 帧数别太多。

代码里可以加个简单的可见性判断：

if (document.hidden) { return; // 后台标签页不再切帧，恢复时继续 }

这样在切换到后台时不会白白消耗 CPU 和 GPU，尤其是同时叠加热力图和 3D Tiles 的场景，后台解帧很容易把移动端设备拖到发热。

5. 性能、内存与常见坑：GIF 动画的排错清单

5.1 三个高频问题排查

还有一个很容易踩的坑：TextureAtlas.addImage是异步完成的，如果你在回调前就执行billboards.add，某些 Cesium 版本会直接抛Invalid image index。所以第 3 章的createGifAtlas必须处理 Promise。

5.2 用 requestRenderMode 控制渲染

如果场景中数据层不多，我一般会开启按需渲染来省电：

const viewer = new Cesium.Viewer('cesiumContainer', { requestRenderMode: true, maximumRenderTimeChange: Infinity, });

开启后，Cesium 只在场景变更时渲染，GIF 切帧也要主动触发：在postRender里把billboard.imageIndex改完之后，调用viewer.scene.requestRender()。注意maximumRenderTimeChange会影响时钟相关动画，如果同时用到时间轴，把它设成一个小值而不是Infinity。这个参数的作用是告诉 Cesium：当仿真时间前进多大时，即使没有场景事件也要重绘一次。

5.3 有没有必要转成 WebM

如果 GIF 本身分辨率大、帧数多，比如超过 1024 尺寸的演示动画，图集方案会占用较多显存。这时可以换思路：把 GIF 转成带透明通道的 WebM，用<video>元素作为 Cesium 的图片源，Cesium 对 video 元素有原生支持，播放节奏由解码器控制，不需要自己维护imageIndex。缺点是 video 解码会增加 CPU 占用，并且移动端透明通道兼容性需要单独测试。大多数场景下，TextureAtlas拆帧方案在可控帧数内反而是最平稳的，因为所有帧在初始化阶段已经进入 GPU，后续只是换索引，没有连续解码开销。如果你是给 cesium for unity 或 Unreal 等非 Web 环境做类似功能，思路也一致：先拆帧，再拼一张精灵图，最后按时间切 UV 或索引，只是 API 换成对应引擎的 TextureAtlas。

本文还有配套的精品资源，点击获取