Tiles Traversal: Only load necessary tiles (#1421)

* Add flag for optimized loading

* Add conditions for loading the tiles at the error target

* Remove conditions

* Update traversal

* comments

* handle kicking on zoom in

* Update examples for testing

* Remove unused lines

* Updates, comments

* Fix zoom out case

* Adjust used behavior

* Small fix

* Small fixes

* Basic fixes

* Small fixes

* Small improvements

* Get it working

* Fix raycasting

* Readd optimization

* Prevent intermediate tiles from loading

* Fix trickle in

* Rename traverse functions

* Add old traversal approach

* Add toggle for traversal strategy

* Fix up example

* Cleanup

* Improve tiles to load

* Load tiles in frustum first, add loadSiblings option

* Fix low lod tiles loading too early, adjust load priority

* Update LRUCache

* Add additive refinement support

* Fix case where children were not processed

* Fix active flag

* remove unneeded field

* Small fix

* Small cleanup

* default loadSiblings to "true"

* Update demos

* Add optimized settings option

* Add more queue information

* Add types

* README update

* Improve demo

* Update README

* Fix controls issues

* Simplification, variable rename

* Re-add fade plugin

* README update

* update demo

* update traversal

Author: gkjohnson

README.md

@@ -393,6 +393,31 @@ displayActiveTiles = false : Boolean
 
 Active tiles not currently visible in a camera frustum are removed from the scene as an optimization. Setting `displayActiveTiles` to true will keep them in the scene to be rendered from an outside camera view not accounted for by the tiles renderer.
 
+### .optimizedLoadStrategy
+
+```js
+optimizedLoadStrategy = false : Boolean
+```
+
+Enables an **experimental** optimized tile loading strategy that loads only the tiles needed for the current view, reducing memory usage and improving initial load times. Tiles are loaded independently based on screen space error without requiring all parent tiles to load first. Prevents visual gaps and flashing during camera movement.
+
+Based in part on [Cesium Native tile selection](https://cesium.com/learn/cesium-native/ref-doc/selection-algorithm-details.html).
+
+Default is `false` which uses the previous approach of loading all parent and sibling tiles for guaranteed smooth transitions.
+
+> [!WARN]
+> Setting is currently incompatible with plugins that split tiles and on-the-fly generate and dispose of child tiles including the ImageOverlaysPlugin enableTileSplitting setting, QuantizedMeshPlugin, & ImageFormatPlugins (XYZ, TMS, etc). Any tile sets that share caches or queues must also use the same setting.
+
+### .loadSiblings
+
+```js
+loadSiblings = true : Boolean
+```
+
+**Experimental** setting that, when true, causes sibling tiles to together to prevent gaps during camera movement. When false, only visible tiles are loaded, minimizing memory but potentially causing brief gaps during rapid movement.
+
+Only applies when `optimizedLoadStrategy` is enabled.
+
 ### .autoDisableRendererCulling
 
 ```js

example/styles.css

@@ -40,6 +40,7 @@ canvas {
 	display: flex;
 	padding: 5px;
 	box-sizing: border-box;
+	pointer-events: none;
 }
 
 #credits {

example/three/googleMapsExample.js

@@ -34,9 +34,13 @@ const params = {
 
 	orthographic: false,
 
+	optimizedLoadStrategy: false,
+	loadSiblings: true,
+
 	enableCacheDisplay: false,
 	enableRendererStats: false,
 	useBatchedMesh: Boolean( new URLSearchParams( window.location.hash.replace( /^#/, '' ) ).get( 'batched' ) ),
+	useFadePlugin: true,
 	displayTopoLines: false,
 	errorTarget: 20,
 
@@ -58,18 +62,25 @@ function reinstantiateTiles() {
 	}
 
 	tiles = new TilesRenderer();
+	tiles.lruCache.minSize = 0;
 	tiles.registerPlugin( new CesiumIonAuthPlugin( { apiToken: import.meta.env.VITE_ION_KEY, assetId: '2275207', autoRefreshToken: true } ) );
 	tiles.registerPlugin( new TileCompressionPlugin() );
 	tiles.registerPlugin( new UpdateOnChangePlugin() );
 	tiles.registerPlugin( new UnloadTilesPlugin() );
-	tiles.registerPlugin( new TilesFadePlugin() );
 	tiles.registerPlugin( new TopoLinesPlugin( { projection: 'ellipsoid' } ) );
 	tiles.registerPlugin( new GLTFExtensionsPlugin( {
 		// Note the DRACO compression files need to be supplied via an explicit source.
 		// We use unpkg here but in practice should be provided by the application.
 		dracoLoader: new DRACOLoader().setDecoderPath( 'https://unpkg.com/three@0.153.0/examples/jsm/libs/draco/gltf/' )
 	} ) );
+	tiles.optimizedLoadStrategy = params.optimizedLoadStrategy;
+	tiles.loadSiblings = params.loadSiblings;
+
+	if ( params.useFadePlugin ) {
 
+		tiles.registerPlugin( new TilesFadePlugin() );
+
+	}
 
 	if ( params.useBatchedMesh ) {
 
@@ -155,7 +166,17 @@ function init() {
 	} );
 
 	const mapsOptions = gui.addFolder( 'Google Photorealistic Tiles' );
+	if ( new URLSearchParams( window.location.search ).has( 'showOptimizedSettings' ) ) {
+
+		params.optimizedLoadStrategy = true;
+		tiles.optimizedLoadStrategy = true;
+		mapsOptions.add( params, 'optimizedLoadStrategy' ).listen();
+		mapsOptions.add( params, 'loadSiblings' ).listen();
+
+	}
+
 	mapsOptions.add( params, 'useBatchedMesh' ).listen();
+	mapsOptions.add( params, 'useFadePlugin' ).listen();
 	mapsOptions.add( params, 'reload' );
 
 	const exampleOptions = gui.addFolder( 'Example Options' );
@@ -168,6 +189,7 @@ function init() {
 
 	} );
 
+	// add stats
 	statsContainer = document.createElement( 'div' );
 	document.getElementById( 'info' ).appendChild( statsContainer );
 
@@ -317,6 +339,9 @@ function animate() {
 
 	if ( ! tiles ) return;
 
+	// ensure transforms are up to date for controls update
+	scene.updateMatrixWorld();
+
 	controls.enabled = ! transition.animating;
 	controls.update();
 	transition.update();
@@ -351,7 +376,7 @@ function updateHtml() {
 
 		const lruCache = tiles.lruCache;
 		const cacheFullness = lruCache.cachedBytes / lruCache.maxBytesSize;
-		str += `Queued: ${ tiles.stats.queued } Downloading: ${ tiles.stats.downloading } Parsing: ${ tiles.stats.parsing } Visible: ${ tiles.visibleTiles.size }<br/>`;
+		str += `Queued: ${ tiles.stats.queued } Downloading: ${ tiles.stats.downloading } Parsing: ${ tiles.stats.parsing } Loaded: ${ tiles.stats.loaded }<br/>Visible: ${ tiles.visibleTiles.size } Active: ${ tiles.activeTiles.size }<br/>`;
 		str += `Cache: ${ ( 100 * cacheFullness ).toFixed( 2 ) }% ~${ ( lruCache.cachedBytes / 1000 / 1000 ).toFixed( 2 ) }mb<br/>`;
 
 	}
@@ -374,7 +399,7 @@ function updateHtml() {
 
 			} );
 
-			fadePlugin.batchedMesh?._instanceInfo.forEach( info => {
+			fadePlugin?.batchedMesh?._instanceInfo.forEach( info => {
 
 				if ( info.visible && info.active ) tot ++;
 

example/three/quantMeshOverlays.js

@@ -226,7 +226,7 @@ function updateHtml() {
 
 		const lruCache = tiles.lruCache;
 		const cacheFullness = lruCache.cachedBytes / lruCache.maxBytesSize;
-		str += `Queued: ${ tiles.stats.queued } Downloading: ${ tiles.stats.downloading } Parsing: ${ tiles.stats.parsing } Visible: ${ tiles.visibleTiles.size }<br/>`;
+		str += `Queued: ${ tiles.stats.queued } Downloading: ${ tiles.stats.downloading } Parsing: ${ tiles.stats.parsing } Loaded: ${ tiles.stats.loaded }<br/>Visible: ${ tiles.visibleTiles.size } Active: ${ tiles.activeTiles.size }<br/>`;
 		str += `Cache: ${ ( 100 * cacheFullness ).toFixed( 2 ) }% ~${ ( lruCache.cachedBytes / 1000 / 1000 ).toFixed( 2 ) }mb<br/>`;
 
 	}

src/core/renderer/tiles/TilesRendererBase.d.ts

@@ -12,6 +12,8 @@ export class TilesRendererBase {
 	errorThreshold : number;
 	displayActiveTiles : boolean;
 	maxDepth : number;
+	loadSiblings : number;
+	optimizedLoadStrategy : number;
 
 	loadProgress: number;
 

src/core/renderer/tiles/TilesRendererBase.js

@@ -1,7 +1,8 @@
 import { getUrlExtension } from '../utilities/urlExtension.js';
 import { LRUCache } from '../utilities/LRUCache.js';
 import { PriorityQueue } from '../utilities/PriorityQueue.js';
-import { markUsedTiles, toggleTiles, markVisibleTiles, markUsedSetLeaves } from './traverseFunctions.js';
+import { runTraversal as optimizedRunTraversal } from './optimizedTraverseFunctions.js';
+import { runTraversal } from './traverseFunctions.js';
 import { UNLOADED, QUEUED, LOADING, PARSING, LOADED, FAILED } from '../constants.js';
 import { throttle } from '../utilities/throttle.js';
 import { traverseSet } from '../utilities/TraversalUtils.js';
@@ -10,7 +11,7 @@ const PLUGIN_REGISTERED = Symbol( 'PLUGIN_REGISTERED' );
 
 // priority queue sort function that takes two tiles to compare. Returning 1 means
 // "tile a" is loaded first.
-const priorityCallback = ( a, b ) => {
+const defaultPriorityCallback = ( a, b ) => {
 
 	const aPriority = a.priority || 0;
 	const bPriority = b.priority || 0;
@@ -46,6 +47,43 @@ const priorityCallback = ( a, b ) => {
 
 };
 
+// Optimized priority callback - prioritizes distance over error for better user experience
+const optimizedPriorityCallback = ( a, b ) => {
+
+	const aPriority = a.priority || 0;
+	const bPriority = b.priority || 0;
+
+	if ( aPriority !== bPriority ) {
+
+		// lower priority value sorts first
+		return aPriority > bPriority ? 1 : - 1;
+
+	} else if ( a.__used !== b.__used ) {
+
+		// load tiles that have been used
+		return a.__used ? 1 : - 1;
+
+	} else if ( a.__inFrustum !== b.__inFrustum ) {
+
+		// load tiles that have are in the frustum
+		return a.__inFrustum ? 1 : - 1;
+
+	} else if ( a.__hasUnrenderableContent !== b.__hasUnrenderableContent ) {
+
+		// load internal tile sets first
+		return a.__hasUnrenderableContent ? 1 : - 1;
+
+	} else if ( a.__distanceFromCamera !== b.__distanceFromCamera ) {
+
+		// load closer tiles first
+		return a.__distanceFromCamera > b.__distanceFromCamera ? - 1 : 1;
+
+	}
+
+	return 0;
+
+};
+
 // lru cache unload callback that takes two tiles to compare. Returning 1 means "tile a"
 // is unloaded first.
 const lruPriorityCallback = ( a, b ) => {
@@ -144,11 +182,11 @@ export class TilesRendererBase {
 
 		const downloadQueue = new PriorityQueue();
 		downloadQueue.maxJobs = 25;
-		downloadQueue.priorityCallback = priorityCallback;
+		downloadQueue.priorityCallback = defaultPriorityCallback;
 
 		const parseQueue = new PriorityQueue();
 		parseQueue.maxJobs = 5;
-		parseQueue.priorityCallback = priorityCallback;
+		parseQueue.priorityCallback = defaultPriorityCallback;
 
 		const processNodeQueue = new PriorityQueue();
 		processNodeQueue.maxJobs = 25;
@@ -169,6 +207,7 @@ export class TilesRendererBase {
 			queued: 0,
 			downloading: 0,
 			parsing: 0,
+			loaded: 0,
 			failed: 0,
 
 			inFrustum: 0,
@@ -190,6 +229,8 @@ export class TilesRendererBase {
 		this._errorThreshold = Infinity;
 		this.displayActiveTiles = false;
 		this.maxDepth = Infinity;
+		this.optimizedLoadStrategy = false;
+		this.loadSiblings = true;
 
 	}
 
@@ -341,7 +382,7 @@ export class TilesRendererBase {
 
 	update() {
 
-		const { lruCache, usedSet, stats, root, downloadQueue, parseQueue, processNodeQueue } = this;
+		const { lruCache, usedSet, stats, root, downloadQueue, parseQueue, processNodeQueue, optimizedLoadStrategy } = this;
 		if ( this.rootLoadingState === UNLOADED ) {
 
 			this.rootLoadingState = LOADING;
@@ -403,10 +444,21 @@ export class TilesRendererBase {
 		usedSet.forEach( tile => lruCache.markUnused( tile ) );
 		usedSet.clear();
 
-		markUsedTiles( root, this );
-		markUsedSetLeaves( root, this );
-		markVisibleTiles( root, this );
-		toggleTiles( root, this );
+		// assign the correct callbacks
+		const priorityCallback = optimizedLoadStrategy ? optimizedPriorityCallback : defaultPriorityCallback;
+		downloadQueue.priorityCallback = priorityCallback;
+		parseQueue.priorityCallback = priorityCallback;
+
+		// run traversal
+		if ( optimizedLoadStrategy ) {
+
+			optimizedRunTraversal( root, this );
+
+		} else {
+
+			runTraversal( root, this );
+
+		}
 
 		// remove any tiles that are loading but no longer used
 		this.removeUnusedPendingTiles();
@@ -504,6 +556,7 @@ export class TilesRendererBase {
 			downloading: 0,
 			failed: 0,
 			inFrustum: 0,
+			traversed: 0,
 			used: 0,
 			active: 0,
 			visible: 0,
@@ -965,6 +1018,10 @@ export class TilesRendererBase {
 
 				stats.parsing --;
 
+			} else if ( t.__loadingState === LOADED ) {
+
+				stats.loaded --;
+
 			}
 
 			t.__loadingState = UNLOADED;
@@ -1088,6 +1145,7 @@ export class TilesRendererBase {
 				}
 
 				stats.parsing --;
+				stats.loaded ++;
 				tile.__loadingState = LOADED;
 				loadingTiles.delete( tile );
 				lruCache.setLoaded( tile, true );
@@ -1151,13 +1209,17 @@ export class TilesRendererBase {
 
 						stats.queued --;
 
+					} else if ( tile.__loadingState === LOADING ) {
+
+						stats.downloading --;
+
 					} else if ( tile.__loadingState === PARSING ) {
 
 						stats.parsing --;
 
-					} else if ( tile.__loadingState === LOADING ) {
+					} else if ( tile.__loadingState === LOADED ) {
 
-						stats.downloading --;
+						stats.loaded --;
 
 					}