[{"data":1,"prerenderedAt":1296},["ShallowReactive",2],{"\u002Fblog\u002Fcesium-image-subregion-version-flicker-investigation":3,"\u002Fblog\u002Fcesium-image-subregion-version-flicker-investigation-surround":1285},{"id":4,"title":5,"author":6,"body":10,"date":1276,"description":1277,"extension":1278,"image":1279,"meta":1280,"minRead":275,"navigation":380,"path":1281,"seo":1282,"stem":1283,"__hash__":1284},"blog\u002Fblog\u002Fcesium-image-subregion-version-flicker-investigation.md","Cesium imageSubRegion 多动图闪烁问题排查",{"name":7,"avatar":8},"Kevin",{"src":9,"alt":7},"\u002Favatar.jpg",{"type":11,"value":12,"toc":1263},"minimark",[13,17,26,37,44,51,54,60,63,77,80,86,89,92,142,145,216,219,227,230,233,424,428,442,445,508,518,617,620,630,640,646,700,706,710,713,719,732,735,987,990,1103,1106,1112,1116,1119,1128,1131,1134,1137,1140,1150,1165,1171,1174,1177,1184,1200,1203,1206,1212,1215,1221,1224,1231,1234,1237,1240,1250,1256,1259],[14,15,16],"h2",{"id":16},"这篇文章记录什么问题",[18,19,20,21,25],"p",{},"这次问题发生在一个看起来很确定的迁移场景里：Demo 中已经验证过的 Cesium 动画 Billboard 方案，需要迁移到业务标绘库中，让 ",[22,23,24],"code",{},"draw_apng_billboard"," 支持 APNG、animated WebP 和 GIF 的序列帧播放。",[18,27,28,29,32,33,36],{},"Demo 的方案是先用 ",[22,30,31],{},"ImageDecoder"," 把动图解码成帧，再把所有帧合成一张 sprite sheet。Cesium 侧只创建一个 Billboard，播放时通过 ",[22,34,35],{},"setImageSubRegion()"," 切换当前帧所在的贴图子区域。这个方案在 Demo 中运行很平滑，多个动画点同时播放也没有明显抖动。",[18,38,39,40,43],{},"但迁移到业务库后，单个动图基本正常，从第二个动图开始就会陆续出现不同程度的闪烁。降低 ",[22,41,42],{},"speed"," 只能缓解播放频率，不能消除问题。鼠标移动、标绘事件、重复加载销毁、贴图 padding、ticker 合并等方向都排查过后，问题仍然存在。",[18,45,46,47,50],{},"最后根因收敛到一个很容易被忽略的地方：Demo 与业务测试页虽然都叫 Cesium，但底层版本和 Billboard 贴图图集实现并不一样。序列帧方案依赖的 ",[22,48,49],{},"imageSubRegion"," 在不同 Cesium 版本里的行为差异，足以让同一套业务代码表现完全不同。",[14,52,53],{"id":53},"最初的几个错误判断",[18,55,56,57,59],{},"第一个判断是播放速度过快。因为问题出现时，视觉上像是动画瞬间跑完一轮，又像所有实例一起闪了一下。但实际调整 ",[22,58,42],{}," 后可以确认，播放倍率是生效的。问题不是动画时间计算错了，而是每次切帧引发了额外的渲染抖动。",[18,61,62],{},"第二个判断是业务库的鼠标事件影响渲染。标绘系统本身会注册点击、移动、拾取、拖拽等交互事件，确实可能带来 CPU 压力。但关闭或绕开相关事件后，闪烁仍然存在，说明事件不是根因。",[18,64,65,66,69,70,69,73,76],{},"第三个判断是加载链路重复触发。业务库里存在 ",[22,67,68],{},"loadAllSymbol","、",[22,71,72],{},"loadFeature",[22,74,75],{},"addFeatures"," 等多个入口，如果同一个动图被重复创建、销毁、再创建，确实会造成纹理 atlas 抖动。这个方向修过之后，重复加载问题得到收敛，但多实例闪烁仍然存在。",[18,78,79],{},"第四个判断是 sprite sheet 串帧。帧与帧之间没有 padding 时，线性采样可能读到相邻帧边缘，因此加了默认 padding，并把边缘像素扩展到 padding 区域。这个修复对抖边有价值，但仍然解释不了“第二个实例开始集体闪烁”的现象。",[18,81,82,83,85],{},"这些判断都不是完全离谱，只是它们都停留在业务层或资源层。真正的问题在 Cesium 内部：每次 ",[22,84,35],{}," 究竟会不会改变 texture atlas 结构。",[14,87,88],{"id":88},"关键环境差异",[18,90,91],{},"Demo 使用的是官方 npm 包：",[93,94,99],"pre",{"className":95,"code":96,"language":97,"meta":98,"style":98},"language-json shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","{\n  \"cesium\": \"^1.140.0\"\n}\n","json","",[22,100,101,110,136],{"__ignoreMap":98},[102,103,106],"span",{"class":104,"line":105},"line",1,[102,107,109],{"class":108},"sMK4o","{\n",[102,111,113,116,120,123,126,129,133],{"class":104,"line":112},2,[102,114,115],{"class":108},"  \"",[102,117,119],{"class":118},"spNyl","cesium",[102,121,122],{"class":108},"\"",[102,124,125],{"class":108},":",[102,127,128],{"class":108}," \"",[102,130,132],{"class":131},"sfazB","^1.140.0",[102,134,135],{"class":108},"\"\n",[102,137,139],{"class":104,"line":138},3,[102,140,141],{"class":108},"}\n",[18,143,144],{},"业务测试页并不是通过 npm import 获取 Cesium，而是在页面中直接加载静态文件：",[93,146,150],{"className":147,"code":148,"language":149,"meta":98,"style":98},"language-html shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","\u003Clink href=\"\u002FCesium\u002FWidgets\u002Fwidgets.css\" rel=\"stylesheet\" \u002F>\n\u003Cscript src=\"\u002FCesium\u002FCesium.js\">\u003C\u002Fscript>\n","html",[22,151,152,189],{"__ignoreMap":98},[102,153,154,157,161,164,167,169,172,174,177,179,181,184,186],{"class":104,"line":105},[102,155,156],{"class":108},"\u003C",[102,158,160],{"class":159},"swJcz","link",[102,162,163],{"class":118}," href",[102,165,166],{"class":108},"=",[102,168,122],{"class":108},[102,170,171],{"class":131},"\u002FCesium\u002FWidgets\u002Fwidgets.css",[102,173,122],{"class":108},[102,175,176],{"class":118}," rel",[102,178,166],{"class":108},[102,180,122],{"class":108},[102,182,183],{"class":131},"stylesheet",[102,185,122],{"class":108},[102,187,188],{"class":108}," \u002F>\n",[102,190,191,193,196,199,201,203,206,208,211,213],{"class":104,"line":112},[102,192,156],{"class":108},[102,194,195],{"class":159},"script",[102,197,198],{"class":118}," src",[102,200,166],{"class":108},[102,202,122],{"class":108},[102,204,205],{"class":131},"\u002FCesium\u002FCesium.js",[102,207,122],{"class":108},[102,209,210],{"class":108},">\u003C\u002F",[102,212,195],{"class":159},[102,214,215],{"class":108},">\n",[18,217,218],{},"这份业务 Cesium 是二开包，基于原生 Cesium 1.125 开发。表面上 1.125 到 1.140 只差十几个版本，但对应的 engine 版本跨度更大：",[93,220,225],{"className":221,"code":223,"language":224,"meta":98},[222],"language-text","cesium@1.125.0 -> @cesium\u002Fengine@13.1.0\ncesium@1.140.0 -> @cesium\u002Fengine@24.0.0\n","text",[22,226,223],{"__ignoreMap":98},[18,228,229],{},"这不是普通的小补丁差异。Billboard、TextureAtlas 和子区域贴图逻辑在这中间发生过结构性变化。",[14,231,232],{"id":232},"技术流程图",[93,234,238],{"className":235,"code":236,"language":237,"meta":98,"style":98},"language-mermaid shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","%%{init: {'theme':'tokyo-night', 'themeVariables':{'primaryColor':'#7aa2f7'}}}%%\nflowchart TD\n    A([开始]) --> B[业务库复现多实例动图闪烁]\n    B --> C[排查播放速度 鼠标事件 重复加载 padding]\n    C --> D{业务层修复后是否消除闪烁}\n    D -->|否| E[对比 Demo 与业务页 Cesium 运行时]\n    D -->|是| F[记录业务层根因]\n    E --> G[确认业务页使用二开 Cesium 1.125]\n    G --> H[追踪 setImageSubRegion 调用链]\n    H --> I[进入 TextureAtlas.addSubRegion]\n    I --> J{是否存在子区域缓存}\n    J -->|否| K[每次切帧追加 subRegion 并刷新 atlas guid]\n    K --> L[BillboardCollection 频繁重建渲染数据]\n    L --> M[定位 1.125 多实例闪烁根因]\n    J -->|是| N[复用已有 subRegion index]\n    N --> O[对比 1.140 子区域缓存机制]\n    M --> P{运行环境是否可以升级}\n    O --> P\n    P -->|是| Q[升级或回迁新版 Billboard 子区域机制]\n    P -->|否| R[避免高频 setImageSubRegion 或补缓存]\n    Q --> S([方案收敛])\n    R --> S\n    F --> S\n\n    style A fill:#7aa2f7,stroke:#7aa2f7,color:#fff\n    style S fill:#9ece6a,stroke:#9ece6a,color:#fff\n    style D fill:#e0af68,stroke:#e0af68,color:#1f2335\n    style J fill:#e0af68,stroke:#e0af68,color:#1f2335\n    style P fill:#e0af68,stroke:#e0af68,color:#1f2335\n    style K fill:#f7768e,stroke:#f7768e,color:#fff\n    style Q fill:#bb9af7,stroke:#bb9af7,color:#fff\n","mermaid",[22,239,240,245,250,255,261,267,273,279,285,291,297,303,309,315,321,327,333,339,345,351,357,363,369,375,382,388,394,400,406,412,418],{"__ignoreMap":98},[102,241,242],{"class":104,"line":105},[102,243,244],{},"%%{init: {'theme':'tokyo-night', 'themeVariables':{'primaryColor':'#7aa2f7'}}}%%\n",[102,246,247],{"class":104,"line":112},[102,248,249],{},"flowchart TD\n",[102,251,252],{"class":104,"line":138},[102,253,254],{},"    A([开始]) --> B[业务库复现多实例动图闪烁]\n",[102,256,258],{"class":104,"line":257},4,[102,259,260],{},"    B --> C[排查播放速度 鼠标事件 重复加载 padding]\n",[102,262,264],{"class":104,"line":263},5,[102,265,266],{},"    C --> D{业务层修复后是否消除闪烁}\n",[102,268,270],{"class":104,"line":269},6,[102,271,272],{},"    D -->|否| E[对比 Demo 与业务页 Cesium 运行时]\n",[102,274,276],{"class":104,"line":275},7,[102,277,278],{},"    D -->|是| F[记录业务层根因]\n",[102,280,282],{"class":104,"line":281},8,[102,283,284],{},"    E --> G[确认业务页使用二开 Cesium 1.125]\n",[102,286,288],{"class":104,"line":287},9,[102,289,290],{},"    G --> H[追踪 setImageSubRegion 调用链]\n",[102,292,294],{"class":104,"line":293},10,[102,295,296],{},"    H --> I[进入 TextureAtlas.addSubRegion]\n",[102,298,300],{"class":104,"line":299},11,[102,301,302],{},"    I --> J{是否存在子区域缓存}\n",[102,304,306],{"class":104,"line":305},12,[102,307,308],{},"    J -->|否| K[每次切帧追加 subRegion 并刷新 atlas guid]\n",[102,310,312],{"class":104,"line":311},13,[102,313,314],{},"    K --> L[BillboardCollection 频繁重建渲染数据]\n",[102,316,318],{"class":104,"line":317},14,[102,319,320],{},"    L --> M[定位 1.125 多实例闪烁根因]\n",[102,322,324],{"class":104,"line":323},15,[102,325,326],{},"    J -->|是| N[复用已有 subRegion index]\n",[102,328,330],{"class":104,"line":329},16,[102,331,332],{},"    N --> O[对比 1.140 子区域缓存机制]\n",[102,334,336],{"class":104,"line":335},17,[102,337,338],{},"    M --> P{运行环境是否可以升级}\n",[102,340,342],{"class":104,"line":341},18,[102,343,344],{},"    O --> P\n",[102,346,348],{"class":104,"line":347},19,[102,349,350],{},"    P -->|是| Q[升级或回迁新版 Billboard 子区域机制]\n",[102,352,354],{"class":104,"line":353},20,[102,355,356],{},"    P -->|否| R[避免高频 setImageSubRegion 或补缓存]\n",[102,358,360],{"class":104,"line":359},21,[102,361,362],{},"    Q --> S([方案收敛])\n",[102,364,366],{"class":104,"line":365},22,[102,367,368],{},"    R --> S\n",[102,370,372],{"class":104,"line":371},23,[102,373,374],{},"    F --> S\n",[102,376,378],{"class":104,"line":377},24,[102,379,381],{"emptyLinePlaceholder":380},true,"\n",[102,383,385],{"class":104,"line":384},25,[102,386,387],{},"    style A fill:#7aa2f7,stroke:#7aa2f7,color:#fff\n",[102,389,391],{"class":104,"line":390},26,[102,392,393],{},"    style S fill:#9ece6a,stroke:#9ece6a,color:#fff\n",[102,395,397],{"class":104,"line":396},27,[102,398,399],{},"    style D fill:#e0af68,stroke:#e0af68,color:#1f2335\n",[102,401,403],{"class":104,"line":402},28,[102,404,405],{},"    style J fill:#e0af68,stroke:#e0af68,color:#1f2335\n",[102,407,409],{"class":104,"line":408},29,[102,410,411],{},"    style P fill:#e0af68,stroke:#e0af68,color:#1f2335\n",[102,413,415],{"class":104,"line":414},30,[102,416,417],{},"    style K fill:#f7768e,stroke:#f7768e,color:#fff\n",[102,419,421],{"class":104,"line":420},31,[102,422,423],{},"    style Q fill:#bb9af7,stroke:#bb9af7,color:#fff\n",[14,425,427],{"id":426},"_1125-的子区域机制","1.125 的子区域机制",[18,429,430,431,433,434,437,438,441],{},"在 Cesium 1.125 时代，Billboard 的 ",[22,432,35],{}," 会重新进入 ",[22,435,436],{},"_loadImage()","，再调用 ",[22,439,440],{},"TextureAtlas.addSubRegion()","。",[18,443,444],{},"调用链大致是：",[93,446,450],{"className":447,"code":448,"language":449,"meta":98,"style":98},"language-js shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","Billboard.setImageSubRegion(id, subRegion)\n  -> Billboard._loadImage()\n  -> TextureAtlas.addSubRegion(id, subRegion)\n","js",[22,451,452,474,490],{"__ignoreMap":98},[102,453,454,458,461,465,468,471],{"class":104,"line":105},[102,455,457],{"class":456},"sTEyZ","Billboard",[102,459,460],{"class":108},".",[102,462,464],{"class":463},"s2Zo4","setImageSubRegion",[102,466,467],{"class":456},"(id",[102,469,470],{"class":108},",",[102,472,473],{"class":456}," subRegion)\n",[102,475,476,479,482,484,487],{"class":104,"line":112},[102,477,478],{"class":108},"  ->",[102,480,481],{"class":456}," Billboard",[102,483,460],{"class":108},[102,485,486],{"class":463},"_loadImage",[102,488,489],{"class":456},"()\n",[102,491,492,494,497,499,502,504,506],{"class":104,"line":138},[102,493,478],{"class":108},[102,495,496],{"class":456}," TextureAtlas",[102,498,460],{"class":108},[102,500,501],{"class":463},"addSubRegion",[102,503,467],{"class":456},[102,505,470],{"class":108},[102,507,473],{"class":456},[18,509,510,513,514,517],{},[22,511,512],{},"addSubRegion()"," 的核心逻辑是把传入的矩形转换成新的纹理坐标，并追加到 ",[22,515,516],{},"_textureCoordinates"," 中。",[93,519,521],{"className":447,"code":520,"language":449,"meta":98,"style":98},"const newIndex =\n  that._textureCoordinates.push(new BoundingRectangle(x, y, w, h)) - 1\nthat._indexHash[id] = newIndex\n\nthat._guid = createGuid()\n",[22,522,523,534,582,597,601],{"__ignoreMap":98},[102,524,525,528,531],{"class":104,"line":105},[102,526,527],{"class":118},"const",[102,529,530],{"class":456}," newIndex ",[102,532,533],{"class":108},"=\n",[102,535,536,539,541,543,545,548,551,554,557,560,562,565,567,570,572,575,578],{"class":104,"line":112},[102,537,538],{"class":456},"  that",[102,540,460],{"class":108},[102,542,516],{"class":456},[102,544,460],{"class":108},[102,546,547],{"class":463},"push",[102,549,550],{"class":456},"(",[102,552,553],{"class":108},"new",[102,555,556],{"class":463}," BoundingRectangle",[102,558,559],{"class":456},"(x",[102,561,470],{"class":108},[102,563,564],{"class":456}," y",[102,566,470],{"class":108},[102,568,569],{"class":456}," w",[102,571,470],{"class":108},[102,573,574],{"class":456}," h)) ",[102,576,577],{"class":108},"-",[102,579,581],{"class":580},"sbssI"," 1\n",[102,583,584,587,589,592,594],{"class":104,"line":138},[102,585,586],{"class":456},"that",[102,588,460],{"class":108},[102,590,591],{"class":456},"_indexHash[id] ",[102,593,166],{"class":108},[102,595,596],{"class":456}," newIndex\n",[102,598,599],{"class":104,"line":257},[102,600,381],{"emptyLinePlaceholder":380},[102,602,603,605,607,610,612,615],{"class":104,"line":263},[102,604,586],{"class":456},[102,606,460],{"class":108},[102,608,609],{"class":456},"_guid ",[102,611,166],{"class":108},[102,613,614],{"class":463}," createGuid",[102,616,489],{"class":456},[18,618,619],{},"这里有两个很关键的点。",[18,621,622,623,625,626,629],{},"第一，1.125 的 ",[22,624,512],{}," 没有按 ",[22,627,628],{},"id + subRegion"," 做缓存。即使同一个 sprite sheet、同一个帧矩形之前已经添加过，再次切到这一帧时仍然会创建新的 subRegion index。",[18,631,632,633,636,637,639],{},"第二，每次新增 subRegion 都会刷新 texture atlas 的 ",[22,634,635],{},"_guid","。这对于静态图标不是大问题，因为 ",[22,638,35],{}," 调用频率很低；但对序列帧动画来说，每个实例每一帧都会调用它。",[18,641,642,645],{},[22,643,644],{},"BillboardCollection"," 又会根据 texture atlas 的 guid 判断是否需要重建渲染数据。",[93,647,649],{"className":447,"code":648,"language":449,"meta":98,"style":98},"const textureAtlasGUID = textureAtlas.guid\nconst createVertexArray =\n  this._createVertexArray || this._textureAtlasGUID !== textureAtlasGUID\n",[22,650,651,668,677],{"__ignoreMap":98},[102,652,653,655,658,660,663,665],{"class":104,"line":105},[102,654,527],{"class":118},[102,656,657],{"class":456}," textureAtlasGUID ",[102,659,166],{"class":108},[102,661,662],{"class":456}," textureAtlas",[102,664,460],{"class":108},[102,666,667],{"class":456},"guid\n",[102,669,670,672,675],{"class":104,"line":112},[102,671,527],{"class":118},[102,673,674],{"class":456}," createVertexArray ",[102,676,533],{"class":108},[102,678,679,682,685,688,691,694,697],{"class":104,"line":138},[102,680,681],{"class":108},"  this.",[102,683,684],{"class":456},"_createVertexArray ",[102,686,687],{"class":108},"||",[102,689,690],{"class":108}," this.",[102,692,693],{"class":456},"_textureAtlasGUID ",[102,695,696],{"class":108},"!==",[102,698,699],{"class":456}," textureAtlasGUID\n",[18,701,702,703,705],{},"于是问题就串起来了：多个动图同时播放时，每个实例都在高频 ",[22,704,35],{},"，每次又可能新增 subRegion、刷新 atlas guid，最终导致 BillboardCollection 频繁重建或重写整批 Billboard buffer。视觉上就变成了闪烁、抖动、像瞬间刷帧。",[14,707,709],{"id":708},"_1140-做了什么改变","1.140 做了什么改变",[18,711,712],{},"在 Cesium 1.140 中，这块已经被拆成了新的结构：",[93,714,717],{"className":715,"code":716,"language":224,"meta":98},[222],"Scene\u002FBillboard.js\nScene\u002FBillboardTexture.js\nRenderer\u002FTextureAtlas.js\n",[22,718,716],{"__ignoreMap":98},[18,720,721,722,725,726,728,729,441],{},"Billboard 不再自己直接管理完整的贴图加载细节，而是通过 ",[22,723,724],{},"BillboardTexture"," 处理图像和子区域状态。TextureAtlas 也从旧的 ",[22,727,512],{}," 变成了 ",[22,730,731],{},"addImageSubRegion()",[18,733,734],{},"更重要的是，新版本有了子区域缓存查询：",[93,736,738],{"className":447,"code":737,"language":449,"meta":98,"style":98},"TextureAtlas.prototype.getCachedImageSubRegion = function (\n  id,\n  subRegion,\n  imageIndex\n) {\n  const imagePromise = this._indexPromiseById.get(id)\n  for (const [index, parentIndex] of this._subRegions.entries()) {\n    if (imageIndex === parentIndex) {\n      const boundingRegion = this._rectangles[index]\n      if (boundingRegion.equals(subRegion)) {\n        return imagePromise ? imagePromise.then(() => index) : index\n      }\n    }\n  }\n}\n",[22,739,740,765,774,781,786,794,822,865,885,908,933,968,973,978,983],{"__ignoreMap":98},[102,741,742,746,748,751,753,756,759,762],{"class":104,"line":105},[102,743,745],{"class":744},"sBMFI","TextureAtlas",[102,747,460],{"class":108},[102,749,750],{"class":456},"prototype",[102,752,460],{"class":108},[102,754,755],{"class":463},"getCachedImageSubRegion",[102,757,758],{"class":108}," =",[102,760,761],{"class":118}," function",[102,763,764],{"class":108}," (\n",[102,766,767,771],{"class":104,"line":112},[102,768,770],{"class":769},"sHdIc","  id",[102,772,773],{"class":108},",\n",[102,775,776,779],{"class":104,"line":138},[102,777,778],{"class":769},"  subRegion",[102,780,773],{"class":108},[102,782,783],{"class":104,"line":257},[102,784,785],{"class":769},"  imageIndex\n",[102,787,788,791],{"class":104,"line":263},[102,789,790],{"class":108},")",[102,792,793],{"class":108}," {\n",[102,795,796,799,802,804,806,809,811,814,816,819],{"class":104,"line":269},[102,797,798],{"class":118},"  const",[102,800,801],{"class":456}," imagePromise",[102,803,758],{"class":108},[102,805,690],{"class":108},[102,807,808],{"class":456},"_indexPromiseById",[102,810,460],{"class":108},[102,812,813],{"class":463},"get",[102,815,550],{"class":159},[102,817,818],{"class":456},"id",[102,820,821],{"class":159},")\n",[102,823,824,828,831,833,836,839,841,844,847,850,852,855,857,860,863],{"class":104,"line":275},[102,825,827],{"class":826},"s7zQu","  for",[102,829,830],{"class":159}," (",[102,832,527],{"class":118},[102,834,835],{"class":108}," [",[102,837,838],{"class":456},"index",[102,840,470],{"class":108},[102,842,843],{"class":456}," parentIndex",[102,845,846],{"class":108},"]",[102,848,849],{"class":108}," of",[102,851,690],{"class":108},[102,853,854],{"class":456},"_subRegions",[102,856,460],{"class":108},[102,858,859],{"class":463},"entries",[102,861,862],{"class":159},"()) ",[102,864,109],{"class":108},[102,866,867,870,872,875,878,880,883],{"class":104,"line":281},[102,868,869],{"class":826},"    if",[102,871,830],{"class":159},[102,873,874],{"class":456},"imageIndex",[102,876,877],{"class":108}," ===",[102,879,843],{"class":456},[102,881,882],{"class":159},") ",[102,884,109],{"class":108},[102,886,887,890,893,895,897,900,903,905],{"class":104,"line":287},[102,888,889],{"class":118},"      const",[102,891,892],{"class":456}," boundingRegion",[102,894,758],{"class":108},[102,896,690],{"class":108},[102,898,899],{"class":456},"_rectangles",[102,901,902],{"class":159},"[",[102,904,838],{"class":456},[102,906,907],{"class":159},"]\n",[102,909,910,913,915,918,920,923,925,928,931],{"class":104,"line":293},[102,911,912],{"class":826},"      if",[102,914,830],{"class":159},[102,916,917],{"class":456},"boundingRegion",[102,919,460],{"class":108},[102,921,922],{"class":463},"equals",[102,924,550],{"class":159},[102,926,927],{"class":456},"subRegion",[102,929,930],{"class":159},")) ",[102,932,109],{"class":108},[102,934,935,938,940,943,945,947,950,952,955,958,961,963,965],{"class":104,"line":299},[102,936,937],{"class":826},"        return",[102,939,801],{"class":456},[102,941,942],{"class":108}," ?",[102,944,801],{"class":456},[102,946,460],{"class":108},[102,948,949],{"class":463},"then",[102,951,550],{"class":159},[102,953,954],{"class":108},"()",[102,956,957],{"class":118}," =>",[102,959,960],{"class":456}," index",[102,962,882],{"class":159},[102,964,125],{"class":108},[102,966,967],{"class":456}," index\n",[102,969,970],{"class":104,"line":305},[102,971,972],{"class":108},"      }\n",[102,974,975],{"class":104,"line":311},[102,976,977],{"class":108},"    }\n",[102,979,980],{"class":104,"line":317},[102,981,982],{"class":108},"  }\n",[102,984,985],{"class":104,"line":323},[102,986,141],{"class":108},[18,988,989],{},"新增子区域前会先查缓存：",[93,991,993],{"className":447,"code":992,"language":449,"meta":98,"style":98},"let index = this.getCachedImageSubRegion(id, subRegion, imageIndex)\nif (defined(index)) {\n  return index\n}\n\nindex = this._nextIndex++\nthis._subRegions.set(index, imageIndex)\nthis._rectangles[index] = subRegion.clone()\n",[22,994,995,1021,1036,1043,1047,1051,1066,1085],{"__ignoreMap":98},[102,996,997,1000,1003,1005,1007,1009,1011,1013,1016,1018],{"class":104,"line":105},[102,998,999],{"class":118},"let",[102,1001,1002],{"class":456}," index ",[102,1004,166],{"class":108},[102,1006,690],{"class":108},[102,1008,755],{"class":463},[102,1010,467],{"class":456},[102,1012,470],{"class":108},[102,1014,1015],{"class":456}," subRegion",[102,1017,470],{"class":108},[102,1019,1020],{"class":456}," imageIndex)\n",[102,1022,1023,1026,1028,1031,1034],{"class":104,"line":112},[102,1024,1025],{"class":826},"if",[102,1027,830],{"class":456},[102,1029,1030],{"class":463},"defined",[102,1032,1033],{"class":456},"(index)) ",[102,1035,109],{"class":108},[102,1037,1038,1041],{"class":104,"line":138},[102,1039,1040],{"class":826},"  return",[102,1042,967],{"class":456},[102,1044,1045],{"class":104,"line":257},[102,1046,141],{"class":108},[102,1048,1049],{"class":104,"line":263},[102,1050,381],{"emptyLinePlaceholder":380},[102,1052,1053,1056,1058,1060,1063],{"class":104,"line":269},[102,1054,1055],{"class":456},"index ",[102,1057,166],{"class":108},[102,1059,690],{"class":108},[102,1061,1062],{"class":456},"_nextIndex",[102,1064,1065],{"class":108},"++\n",[102,1067,1068,1071,1073,1075,1078,1081,1083],{"class":104,"line":275},[102,1069,1070],{"class":108},"this.",[102,1072,854],{"class":456},[102,1074,460],{"class":108},[102,1076,1077],{"class":463},"set",[102,1079,1080],{"class":456},"(index",[102,1082,470],{"class":108},[102,1084,1020],{"class":456},[102,1086,1087,1089,1092,1094,1096,1098,1101],{"class":104,"line":281},[102,1088,1070],{"class":108},[102,1090,1091],{"class":456},"_rectangles[index] ",[102,1093,166],{"class":108},[102,1095,1015],{"class":456},[102,1097,460],{"class":108},[102,1099,1100],{"class":463},"clone",[102,1102,489],{"class":456},[18,1104,1105],{},"这意味着同一个 sprite sheet 的同一个帧区域，只会注册一次。后续再次切回这帧时，拿到的是已有 index，不会无休止追加 texture coordinates，也不会像旧版本那样每次都让 atlas 结构看起来发生变化。",[18,1107,1108,1109,1111],{},"所以 Demo 在 1.140 上平滑，并不代表这套写法天然适配所有 Cesium 版本。它刚好依赖了新版 Cesium 对 ",[22,1110,49],{}," 的缓存和状态管理能力。",[14,1113,1115],{"id":1114},"为什么预热和-padding-没能彻底解决","为什么预热和 padding 没能彻底解决",[18,1117,1118],{},"排查过程中做过两类看似合理的优化。",[18,1120,1121,1122,1124,1125,1127],{},"一类是播放前预注册所有帧区域。这个思路在新版本里很有价值，因为可以避免播放过程中首次切到某帧时才异步创建子区域。但在 1.125 里，即使预注册过，后续 ",[22,1123,35],{}," 仍然会再次进入 ",[22,1126,512],{},"。旧版本没有“这个 subRegion 已经存在”的缓存判断，因此预热不能阻止重复追加。",[18,1129,1130],{},"另一类是给 sprite sheet 加 padding。padding 能解决线性采样读到相邻帧的问题，尤其是火焰、烟雾这类透明边缘资源。如果看到的是边缘串色、抖边、相邻帧残影，这个方向有效。但这次主要问题是整批 Billboard 因 atlas guid 变化而发生渲染层面的抖动，padding 只能解决图像采样问题，不能解决 atlas 状态变化问题。",[18,1132,1133],{},"这也是这次最大的教训之一：同样叫“闪烁”，背后可能是完全不同的层级。资源采样问题、播放计时问题、渲染缓冲重建问题，视觉上都可能像闪烁，但修法完全不一样。",[14,1135,1136],{"id":1136},"更可靠的排查顺序",[18,1138,1139],{},"这次如果重新来一遍，我会把排查顺序调整为下面这样。",[18,1141,1142,1143,1145,1146,1149],{},"第一步，先确认 Demo 和业务页使用的 Cesium 是否真的是同一份运行时。不要只看 package.json，也要看页面是否直接引入 ",[22,1144,205],{},"，以及 ",[22,1147,1148],{},"window.Cesium.VERSION"," 或静态文件头部标识。",[18,1151,1152,1153,1155,1156,1158,1159,1161,1162,1164],{},"第二步，确认目标 API 是否只是名字相同，底层行为也相同。",[22,1154,49],{}," 在 1.125 和 1.140 都存在，但旧版本走 ",[22,1157,512],{},"，新版本走 ",[22,1160,731],{}," 和 ",[22,1163,724],{},"，这就是典型的“API 可用但语义不同”。",[18,1166,1167,1168,1170],{},"第三步，抓住高频路径。序列帧动画不是偶尔调用一次 ",[22,1169,35],{},"，而是每个实例每一帧都调用。任何看起来只有一点开销的内部逻辑，在多实例动画里都会被放大。",[18,1172,1173],{},"第四步，再看业务层加载和事件。业务层重复加载、鼠标拾取、拖拽事件当然可能影响性能，但它们应该建立在底层渲染路径已经稳定的前提下排查，否则容易被表象牵着走。",[14,1175,1176],{"id":1176},"后续方案选择",[18,1178,1179,1180,1183],{},"如果运行环境可以升级，最干净的方案是把业务 Cesium 的 Billboard 子区域机制升级到接近 1.140 的实现。这样 Demo 的 ",[22,1181,1182],{},"sprite sheet + imageSubRegion"," 播放模型可以继续保留，代码复杂度最低，也最接近 Cesium 新版本的设计方向。",[18,1185,1186,1187,1189,1190,1192,1193,1195,1196,1199],{},"如果运行环境短期不能升级，就不应该继续在 1.125 上高频调用 ",[22,1188,35],{},"。旧版本兼容方案需要绕开这条会反复 ",[22,1191,512],{}," 的路径，例如改成一次性创建固定帧 Billboard、只切换可见性，或者在二开 Cesium 内部给 ",[22,1194,512],{}," 补上 ",[22,1197,1198],{},"id + rectangle"," 缓存，避免每帧刷新 atlas guid。",[18,1201,1202],{},"这两条路线的取舍不只是技术实现问题，也涉及业务库的兼容策略。如果业务库要求支持旧 Cesium，那么动画 Billboard 工具就需要显式识别运行时能力，而不是默认认为新版 Cesium 行为存在。",[14,1204,1205],{"id":1205},"经验教训",[18,1207,1208,1209,1211],{},"第一，迁移 Demo 代码时，不能只迁移业务逻辑，还要迁移它成立的运行时条件。这个 Demo 成立的条件之一，就是新版 Cesium 对 ",[22,1210,49],{}," 做了更好的子区域缓存。",[18,1213,1214],{},"第二，遇到“Demo 正常、业务库异常”时，要优先对比环境，而不是立刻假设业务代码写错。框架版本、全局脚本、二开包、构建产物，都可能让同一个 API 出现不同底层行为。",[18,1216,1217,1218,1220],{},"第三，性能问题要沿着高频路径排查。序列帧动画的高频点是每帧切图，最终就应该落到 ",[22,1219,35],{}," 在当前 Cesium 版本里到底做了什么。",[18,1222,1223],{},"第四，不要被症状名字限制。这里用户看到的是“闪烁”，但根因既不是动画速度，也不是鼠标事件，而是 texture atlas guid 高频变化触发的 BillboardCollection 重建压力。",[18,1225,1226,1227,1230],{},"第五，技术方案要标注版本边界。",[22,1228,1229],{},"ImageDecoder -> sprite sheet -> Billboard.imageSubRegion"," 是一个好方案，但它不是对所有 Cesium 版本都等价稳定。文档、工具注释和业务接入说明里都应该写清楚对 Cesium 版本的要求。",[14,1232,1233],{"id":1233},"小结",[18,1235,1236],{},"这次问题最值得记录的地方，不是某个具体 bug，而是排查方向的转折。",[18,1238,1239],{},"一开始我们围绕业务层修了很多合理的问题：加载收敛、共享 ticker、共享 atlas imageId、delta 限制、纹理 ready、subRegion 预热、sprite sheet padding。它们各自都有价值，但没有击中最终根因。",[18,1241,1242,1243,1245,1246,1249],{},"真正的根因在 Cesium 版本差异：1.125 的 ",[22,1244,440],{}," 会在每次切帧时追加子区域并刷新 atlas guid，而 1.140 的 ",[22,1247,1248],{},"TextureAtlas.addImageSubRegion()"," 已经具备子区域缓存和更完整的 BillboardTexture 状态管理。",[18,1251,1252,1253,1255],{},"所以以后再做 Cesium 序列帧动画时，要先问一个问题：当前运行时的 ",[22,1254,49],{}," 是新版的稳定切帧能力，还是旧版的 atlas 子区域追加能力？",[18,1257,1258],{},"这个问题问对了，后面的方案才不会跑偏。",[1260,1261,1262],"style",{},"html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .s2Zo4, html code.shiki .s2Zo4{--shiki-light:#6182B8;--shiki-default:#82AAFF;--shiki-dark:#82AAFF}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .sbssI, html code.shiki .sbssI{--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C}html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}html pre.shiki code .sHdIc, html code.shiki .sHdIc{--shiki-light:#90A4AE;--shiki-light-font-style:italic;--shiki-default:#EEFFFF;--shiki-default-font-style:italic;--shiki-dark:#BABED8;--shiki-dark-font-style:italic}html pre.shiki code .swJcz, html code.shiki .swJcz{--shiki-light:#E53935;--shiki-default:#F07178;--shiki-dark:#F07178}html pre.shiki code .s7zQu, html code.shiki .s7zQu{--shiki-light:#39ADB5;--shiki-light-font-style:italic;--shiki-default:#89DDFF;--shiki-default-font-style:italic;--shiki-dark:#89DDFF;--shiki-dark-font-style:italic}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}",{"title":98,"searchDepth":112,"depth":112,"links":1264},[1265,1266,1267,1268,1269,1270,1271,1272,1273,1274,1275],{"id":16,"depth":112,"text":16},{"id":53,"depth":112,"text":53},{"id":88,"depth":112,"text":88},{"id":232,"depth":112,"text":232},{"id":426,"depth":112,"text":427},{"id":708,"depth":112,"text":709},{"id":1114,"depth":112,"text":1115},{"id":1136,"depth":112,"text":1136},{"id":1176,"depth":112,"text":1176},{"id":1205,"depth":112,"text":1205},{"id":1233,"depth":112,"text":1233},"2026-05-09","记录一次把序列帧动图迁移到业务标绘库后出现多实例闪烁的排查过程，重点分析 Cesium 1.125 与 1.140 在 Billboard 子区域贴图机制上的差异。","md","\u002Fimages\u002Fanimation\u002F立体火.png",{},"\u002Fblog\u002Fcesium-image-subregion-version-flicker-investigation",{"title":5,"description":1277},"blog\u002Fcesium-image-subregion-version-flicker-investigation","1pGIjaB0rw7VUQgEeIpEP8MsP1nZ3VjdaseD7SOKrOY",[1286,1291],{"title":1287,"path":1288,"stem":1289,"description":1290,"children":-1},"Cesium GeoJSON 热力图核心实现","\u002Fblog\u002Fcesium-geojson-heatmap-sdk-implementation","blog\u002Fcesium-geojson-heatmap-sdk-implementation","解析如何把 GeoJSON 点数据绘制成 canvas 热力纹理，并通过 GroundPrimitive 与 classificationType 贴到 Cesium 地形和 3D Tiles。",{"title":1292,"path":1293,"stem":1294,"description":1295,"children":-1},"Cesium 资源请求的 IndexedDB 离线缓存实现","\u002Fblog\u002Fcesium-indexeddb-resource-cache","blog\u002Fcesium-indexeddb-resource-cache","解析如何拦截 Cesium.Resource 请求，把影像瓦片、地形瓦片和 3D Tiles 写入 IndexedDB，并控制缓存范围与二次加载性能。",1778657542552]