Adds support for external imagery providers in CesiumIonOverlay (#1385)

* Adds support for external imagery providers

Extends CesiumIonOverlay to support external imagery providers like Google Maps and Bing Maps, fetching metadata and adjusting tile URL structures accordingly.

Updates the example to showcase this new feature by adding base map options for different map providers.

* update ImageOverlayPlugin based on PR review

* Small cleanup

* Fix lint

* Separate quad key file

---------

Co-authored-by: Garrett Johnson <garrett.kjohnson@gmail.com>

Author: Brakebein

example/quantMeshOverlays.js

@@ -26,7 +26,7 @@ const params = {
 	enableCacheDisplay: false,
 	enableRendererStats: false,
 	enableTileSplitting: true,
-	mapBase: false,
+	mapBase: 3954,
 	errorTarget: 2,
 	opacity: 1.0,
 	color: '#ffffff',
@@ -114,7 +114,14 @@ function init() {
 	gui.add( params, 'enableCacheDisplay' );
 	gui.add( params, 'enableRendererStats' );
 	gui.add( params, 'enableTileSplitting' );
-	gui.add( params, 'mapBase' ).name( 'OpenStreetMap' ).onChange( updateBaseOverlay );
+	gui.add( params, 'mapBase', {
+		'Sentinel-2': 3954,
+		OpenStreetMap: 0,
+		'Google Maps Satellite': 3830183,
+		'Google Maps Roadmap': 3830184,
+		'Bing Maps Aerial': 3,
+		'Bing Maps Road': 4,
+	} ).name( 'Base map' ).onChange( updateBaseOverlay );
 	gui.add( params, 'errorTarget', 1, 30, 1 );
 
 	const washingtonFolder = gui.addFolder( 'Washington DC Layer' );
@@ -146,7 +153,7 @@ function updateBaseOverlay() {
 
 	}
 
-	if ( params.mapBase ) {
+	if ( params.mapBase === 0 ) {
 
 		baseOverlay = new XYZTilesOverlay( {
 			url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
@@ -155,7 +162,7 @@ function updateBaseOverlay() {
 	} else {
 
 		baseOverlay = new CesiumIonOverlay( {
-			assetId: '3954',
+			assetId: params.mapBase,
 			apiToken: import.meta.env.VITE_ION_KEY,
 		} );
 

src/three/plugins/images/ImageOverlayPlugin.js

@@ -3,6 +3,7 @@ import { PriorityQueue } from '3d-tiles-renderer/core';
 import { CesiumIonAuth, GoogleCloudAuth } from '3d-tiles-renderer/core/plugins';
 import { TiledTextureComposer } from './overlays/TiledTextureComposer.js';
 import { XYZImageSource } from './sources/XYZImageSource.js';
+import { QuadKeyImageSource } from './sources/QuadKeyImageSource.js';
 import { TMSImageSource } from './sources/TMSImageSource.js';
 import { forEachTileInBounds, getMeshesCartographicRange, getMeshesPlanarRange } from './overlays/utils.js';
 import { wrapOverlaysMaterial } from './overlays/wrapOverlaysMaterial.js';
@@ -969,14 +970,19 @@ export class ImageOverlayPlugin {
 
 		if ( ! overlay.isInitialized ) {
 
-			overlay.imageSource.fetchData = ( ...args ) => tiles
-				.downloadQueue
-				.add( { priority: - performance.now() }, () => {
+			overlay.init();
 
-					return overlay.fetch( ...args );
+			overlay.whenReady().then( () => {
 
-				} );
-			overlay.init();
+				overlay.imageSource.fetchData = ( ...args ) => tiles
+					.downloadQueue
+					.add( { priority: - performance.now() }, () => {
+
+						return overlay.fetch( ...args );
+
+					} );
+
+			} );
 
 		}
 
@@ -1622,30 +1628,85 @@ export class CesiumIonOverlay extends ImageOverlay {
 		super( options );
 
 		const { apiToken, autoRefreshToken, assetId } = options;
+		this.options = options;
 		this.assetId = assetId;
 		this.auth = new CesiumIonAuth( { apiToken, autoRefreshToken } );
-		this.imageSource = new TMSImageSource( options );
 
 		this.auth.authURL = `https://api.cesium.com/v1/assets/${ assetId }/endpoint`;
-		this.imageSource.fetchData = ( ...args ) => this.fetch( ...args );
 		this._attributions = [];
 
+		this.externalType = false;
+
 	}
 
 	init() {
 
 		this._whenReady = this
 			.auth
 			.refreshToken()
-			.then( json => {
+			.then( async ( json ) => {
 
 				this._attributions = json.attributions.map( att => ( {
 					value: att.html,
 					type: 'html',
 					collapsible: att.collapsible,
 				} ) );
 
-				this.imageSource.url = json.url;
+				if ( json.type !== 'IMAGERY' ) {
+
+					throw new Error( 'CesiumIonOverlay: Only IMAGERY is supported as overlay type.' );
+
+				}
+
+				this.externalType = Boolean( json.externalType );
+
+				switch ( json.externalType ) {
+
+					case 'GOOGLE_2D_MAPS': {
+
+						const { url, session, key, tileWidth } = json.options;
+						const xyzUrl = `${ url }/v1/2dtiles/{z}/{x}/{y}?session=${ session }&key=${ key }`;
+						this.imageSource = new XYZImageSource( {
+							...this.options,
+							url: xyzUrl,
+							tileDimension: tileWidth,
+
+							// Google maps tiles have a fixed depth of 22
+							// https://developers.google.com/maps/documentation/tile/2d-tiles-overview
+							levels: 22,
+						} );
+						break;
+
+					}
+
+					case 'BING': {
+
+						const { url, mapStyle, key } = json.options;
+						const metadataUrl = `${ url }/REST/v1/Imagery/Metadata/${ mapStyle }?incl=ImageryProviders&key=${ key }&uriScheme=https`;
+						const response = await fetch( metadataUrl ).then( res => res.json() );
+						const metadata = response.resourceSets[ 0 ].resources[ 0 ];
+
+						this.imageSource = new QuadKeyImageSource( {
+							...this.options,
+							url: metadata.imageUrl,
+							subdomains: metadata.imageUrlSubdomains,
+							tileDimension: metadata.tileWidth,
+							levels: metadata.zoomMax,
+						} );
+						break;
+
+					}
+
+					default:
+						this.imageSource = new TMSImageSource( {
+							...this.options,
+							url: json.url,
+						} );
+
+				}
+
+				this.imageSource.fetchData = ( ...args ) => this.fetch( ...args );
+
 				return this.imageSource.init();
 
 			} );
@@ -1656,7 +1717,8 @@ export class CesiumIonOverlay extends ImageOverlay {
 
 	fetch( ...args ) {
 
-		return this.auth.fetch( ...args );
+		// bypass auth fetch if asset is external type to prevent CORS error due to wrong bearer token
+		return this.externalType ? super.fetch( ...args ) : this.auth.fetch( ...args );
 
 	}
 

src/three/plugins/images/sources/QuadKeyImageSource.js

@@ -0,0 +1,55 @@
+import { XYZImageSource } from './XYZImageSource.js';
+
+// Bing Maps Tile System
+// https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system
+export class QuadKeyImageSource extends XYZImageSource {
+
+	constructor( options = {} ) {
+
+		const {
+			subdomains = [ 't0' ],
+			...rest
+		} = options;
+
+		super( rest );
+
+		this.subdomains = subdomains;
+		this.subDomainIndex = 0;
+
+	}
+
+	getUrl( x, y, level ) {
+
+		return this.url
+			.replace( /{\s*subdomain\s*}/gi, this._getSubdomain() )
+			.replace( /{\s*quadkey\s*}/gi, this._tileToQuadKey( x, y, level ) );
+
+	}
+
+	_tileToQuadKey( x, y, level ) {
+
+		let quadKey = '';
+		for ( let i = level; i > 0; i -- ) {
+
+			let digit = 0;
+			const mask = 1 << ( i - 1 );
+			if ( ( x & mask ) !== 0 ) digit += 1;
+			if ( ( y & mask ) !== 0 ) digit += 2;
+			quadKey += digit.toString();
+
+		}
+
+		return quadKey;
+
+	}
+
+	_getSubdomain() {
+
+		// Spread requests among different subdomains to circumvent browser URL request limits per domain
+		// https://learn.microsoft.com/en-us/bingmaps/rest-services/directly-accessing-the-bing-maps-tiles
+		this.subDomainIndex = ( this.subDomainIndex + 1 ) % this.subdomains.length;
+		return this.subdomains[ this.subDomainIndex ];
+
+	}
+
+}