Cesium Basemap Migration: When Changing Tile URLs Moves Every Marker 400 Meters

Any Cesium deployment that serves users in China will hit this coordinate split, and the cost of getting it wrong is a map where every asset lands in the wrong block. The article's patterns—override the tile scheme, not the data; load-once-and-toggle layers; treat preferences as live state—apply directly to any multi-provider basemap architecture, including Western apps that switch between WGS84-compliant providers but need to support GCJ-02 data for Chinese users.

A real-world migration from Tianditu to AMap in a Cesium application starts with a simple URL change but quickly exposes a deeper problem: every icon and 3D model on the map shifts southeast by hundreds of meters. The cause is the coordinate datum difference—Tianditu uses WGS84, AMap uses GCJ-02, a non-linear offset applied to public coordinates in China—and no constant correction fixes it.

The fix is to leave business data in WGS84 and override the Cesium TilingScheme's two key methods: converting lat/lng to tile numbers and tile numbers back to lat/lng rectangles, inserting a WGS84↔GCJ-02 conversion at that boundary. The forward transform has an analytic expression; the inverse does not, so the author uses four iterations of residual-feedback to get sub-millimeter accuracy. The second problem is that switching basemaps by rebuilding the imagery provider causes a white flash and camera reset; the solution is to load all four layers (two imagery + two label layers) once and just toggle `.show`. The third problem is state: the preference must persist, propagate to live instances (via `WeakMap` and `WeakRef`), and be re-read from storage on every entry point, avoiding the module-level snapshot trap.