CesiumIonOverlay with different imagery providers

[Brakebein]

For two months, Google Maps 2D tiles have also been available in Cesium by default next to Bing maps (https://cesium.com/blog/2025/10/02/introducing-google-maps-2d-tiles/). When I wanted to use the CesiumIonOverlay with the Bing maps imagery, I always got an error, but didn't investigate it further. Now, since I wanted to test the Google Maps 2D tiles, I tested it again, but the error remains.

Now, I had a closer look. I'm basically try to use the Quantized Mesh with Overlays example just with another overlay.

baseOverlay = new CesiumIonOverlay( {
  assetId: '3830184',
  apiToken: import.meta.env.VITE_ION_KEY,
} );

However, the error is thrown within TMSImageSource.init. But main issue is in CesiumIonOverlay.init with following line:

this.imageSource.url = json.url;

Looking at the endpoint requests, following data is returned:

{
    "type": "IMAGERY",
    "externalType": "BING",
    "options": {
        "url": "https://dev.virtualearth.net",
        "mapStyle": "Aerial",
        "key": "cesium_provided_access_key"
    },
    "attributions": [ ... ]
}

{
    "type": "IMAGERY",
    "externalType": "GOOGLE_2D_MAPS",
    "options": {
        "url": "https://assets.ion.cesium.com/proxy/3830184",
        "imageFormat": "png",
        "tileWidth": 256,
        "tileHeight": 256,
        "session": "cesium_provided_session_key",
        "key": "cesium_provided_access_key"
    },
    "attributions": [ ... ]
}

So, json.url is obviously not defined. But also this.imageSource.url = json.url ?? json.options?.url; or similar doesn't help either. Actually, each provider would require a special handling: these requests need to be sent with the provided access and session keys, url format may be different, etc. For Google Maps, the CesiumIonOverlay would probably need to use the GoogleCloudAuth class (maybe not needed if session key is already provided). Instead of TMSImageSource, it would need XYZImageSource. And so on.

So, I'm not sure if this is possible to support these different imagery providers via Cesium. I can also make a PR, if you want.

[gkjohnson]

So, I'm not sure if this is possible to support these different imagery providers via Cesium. I can also make a PR, if you want.

Bing maps has never been supported and I've never used Google Maps data through Cesium Ion but I've gotten it working separately (see #1188, though it was admittedly done quickly with no documentation). Through just Google Cloud console you can get it working like so with the "XYZTilesPlugin". There are some notes on "session options" for the Google Cloud API here:

tiles.registerPlugin( new GoogleCloudAuthPlugin( {
	apiToken: '<token>',
	// "sessionOptions" indicates to the plugin that a 2d map tiles session is being started rather than
	// for 3d tiles.
	sessionOptions: {
		mapType: 'roadmap',
		language: 'en-US',
		region: 'US',
	},
} ) );

// this is the API url used to fetch tiles
tiles.registerPlugin( new XYZTilesPlugin( {
	center: true,
	shape: params.planar ? 'planar' : 'ellipsoid',
	url: 'https://tile.googleapis.com/v1/2dtiles/{z}/{x}/{y}'
} ) );

And likewise for overlays:

googleOverlay = new GoogleMapsOverlay( {
	apiToken: '<token>',
	sessionOptions: {
		mapType: 'roadmap',
		language: 'en-US',
		region: 'US',
	},
} );

tiles.registerPlugin( new ImageOverlayPlugin( {
	renderer,
	overlays: [ googleOverlay ],
} ) );

---

I'm open to a PR that modifies the CesionIonAuthPlugin and CesiumIonOverlay that allow for the Google overlays to "just work" or at least be easier to set up, though. You can see that the CesionIonAuthPlugin automatically adds Google auth support when an external source is encountered and allows for registering custom plugins for handling the data (like XYZTilesPlugin) (see here). These if conditions will likely have to be restructured for this to work, though.

"url": "https://assets.ion.cesium.com/proxy/3830184",

But looking at the url returned from ion - if it's not structured like Google's Cloud API urls it may be less obvious how to use this key. Do you know what do to with this url? Should this url be used as an XYZ tiles url like so?

https://assets.ion.cesium.com/proxy/3830184/{z}/{x}/{y}

[Brakebein]

I have already tested the GoogleMapsOverlay. It's basically working. But when using it too extensively, I often get "429 Too Many Requests" error (also with OSM tiles, I was playing around with the ImageOverlayPlugin to get higher resolution textures for those blurry close range parts). Now, since Google Maps is also available via Cesium, I wanted to test, if this is still the case when using the Cesium proxy.

From the Cesium examples, I can see that the url looks like https://assets.ion.cesium.com/proxy/3830182/v1/2dtiles/{z}/{x}/{y}?session=...&key=.... So, it shouldn't be too complicated, at least for Google Maps. For Bing Maps it seems to be a bit more complicated as they use quadkeys instead of the xyz scheme. But I'm just digging in to it. I just will make a proposal.