Plugins: create DebugTilesPlugin (#646)

* Create DebugTilesPlugin.js

* Update DebugTilesPlugin.js

* Update DebugTilesPlugin.js

* Create DebugTilesPlugin.d.ts

* Update DebugTilesRenderer.js

* Update index.js

* Update index.d.ts

* Update README.md

* Update README.md

* Update PLUGINS.md

* Update index.d.ts

* Update index.js

* Update index.js

* Update index.js

* Update DebugTilesPlugin.js

* Update mars.js

* Update vr.js

* Handle already-loaded tiles

* Fix handling of intermediate registration

* Remove separate colors file, fix disposal

* Fix disposal

Author: gkjohnson

PLUGINS.md

@@ -198,6 +198,119 @@ tiles.registerPlugin( new TilesCompressionPlugin() );
 tiles.registerPlugin( new TilesFadePlugin() );
 ```
 
+## DebugTilesPlugin
+
+Plugin TilesRenderer that includes helpers for debugging and visualizing the various tiles in the tile set. Material overrides will not work as expected with this plugin. The plugin includes additional logic and initialization code which can cause performance loss so it's recommended to only use this when needed.
+
+### .colorMode
+
+```js
+colorMode = NONE : ColorMode
+```
+
+Which color mode to use when rendering the tile set. The following exported enumerations can be used:
+
+```js
+// No special color mode. Uses the default materials.
+NONE
+
+// Render the screenspace error from black to white with errorTarget
+// being the maximum value.
+SCREEN_ERROR
+
+// Render the geometric error from black to white with maxDebugError
+// being the maximum value.
+GEOMETRIC_ERROR
+
+// Render the distance from the camera to the tile as black to white
+// with maxDebugDistance being the maximum value.
+DISTANCE
+
+// Render the depth of the tile relative to the root as black to white
+// with maxDebugDepth being the maximum value.
+DEPTH
+
+// Render the depth of the tile relative to the nearest rendered parent
+// as black to white with maxDebugDepth being the maximum value.
+RELATIVE_DEPTH
+
+// Render leaf nodes as white and parent nodes as black.
+IS_LEAF
+
+// Render the tiles with a random color to show tile edges clearly.
+RANDOM_COLOR
+
+// Render every individual mesh in the scene with a random color.
+RANDOM_NODE_COLOR
+
+// Sets a custom color using the customColorCallback call back.
+CUSTOM_COLOR
+```
+
+### .customColorCallback
+
+```js
+customColorCallback: (tile: Tile, child: Object3D) => void
+```
+
+The callback used if `debugColor` is set to `CUSTOM_COLOR`. Value defaults to `null` and must be set explicitly.
+
+### .displayBoxBounds
+
+```js
+displayBoxBounds = false : Boolean
+```
+
+Display wireframe bounding boxes from the tiles `boundingVolume.box` (or derived from the region bounds) for every visible tile.
+
+### .displaySphereBounds
+
+```js
+displaySphereBounds = false : Boolean
+```
+
+Display wireframe bounding boxes from the tiles `boundingVolume.sphere` (or derived from the bounding box / region bounds) for every visible tile.
+
+### .displayRegionBounds
+
+```js
+displayRegionBounds = false : Boolean
+```
+
+Display wireframe bounding rgions from the tiles `boundingVolume.region` for every visible tile if it exists.
+
+### .maxDebugDepth
+
+```js
+maxDebugDepth = - 1 : Number
+```
+
+The depth value that represents white when rendering with `DEPTH` or `RELATIVE_DEPTH` [colorMode](#colorMode). If `maxDebugDepth` is `-1` then the maximum depth of the tile set is used.
+
+### .maxDebugError
+
+```js
+maxDebugError = - 1 : Number
+```
+
+The error value that represents white when rendering with `GEOMETRIC_ERROR` [colorMode](#colorMode). If `maxDebugError` is `-1` then the maximum geometric error in the tile set is used.
+
+### .maxDebugDistance
+
+```js
+maxDebugDistance = - 1 : Number
+```
+
+The distance value that represents white when rendering with `DISTANCE` [colorMode](#colorMode). If `maxDebugDistance` is `-1` then the radius of the tile set is used.
+
+### .getDebugColor
+
+```js
+getDebugColor : ( val : Number, target : Color ) => void
+```
+
+The function used to map a [0, 1] value to a color for debug visualizations. By default the color is mapped from black to white.
+
 ## GoogleCloudAuthPlugin
 
 ### constructor

README.md

@@ -565,120 +565,6 @@ dispose() : void
 
 Disposes of all the tiles in the renderer. Calls dispose on all materials, textures, and geometries that were loaded by the renderer and subsequently calls [onDisposeModel](#onDisposeModel) for any loaded tile model.
 
-## DebugTilesRenderer
-
-_extends [TilesRenderer](#TilesRenderer)_
-
-Special variant of TilesRenderer that includes helpers for debugging and visualizing the various tiles in the tile set. Material overrides will not work as expected with this renderer. The debug renderer includes additional logic and initialization code which can cause performance loss so it's recommended to only use this when needed.
-
-### .colorMode
-
-```js
-colorMode = NONE : ColorMode
-```
-
-Which color mode to use when rendering the tile set. The following exported enumerations can be used:
-
-```js
-// No special color mode. Uses the default materials.
-NONE
-
-// Render the screenspace error from black to white with errorTarget
-// being the maximum value.
-SCREEN_ERROR
-
-// Render the geometric error from black to white with maxDebugError
-// being the maximum value.
-GEOMETRIC_ERROR
-
-// Render the distance from the camera to the tile as black to white
-// with maxDebugDistance being the maximum value.
-DISTANCE
-
-// Render the depth of the tile relative to the root as black to white
-// with maxDebugDepth being the maximum value.
-DEPTH
-
-// Render the depth of the tile relative to the nearest rendered parent
-// as black to white with maxDebugDepth being the maximum value.
-RELATIVE_DEPTH
-
-// Render leaf nodes as white and parent nodes as black.
-IS_LEAF
-
-// Render the tiles with a random color to show tile edges clearly.
-RANDOM_COLOR
-
-// Render every individual mesh in the scene with a random color.
-RANDOM_NODE_COLOR
-
-// Sets a custom color using the customColorCallback call back.
-CUSTOM_COLOR
-```
-### .customColorCallback
-
-```js
-customColorCallback: (tile: Tile, child: Object3D) => void
-```
-
-The callback used if `debugColor` is set to `CUSTOM_COLOR`. Value defaults to `null` and must be set explicitly.
-
-### .displayBoxBounds
-
-```js
-displayBoxBounds = false : Boolean
-```
-
-Display wireframe bounding boxes from the tiles `boundingVolume.box` (or derived from the region bounds) for every visible tile.
-
-### .displaySphereBounds
-
-```js
-displaySphereBounds = false : Boolean
-```
-
-Display wireframe bounding boxes from the tiles `boundingVolume.sphere` (or derived from the bounding box / region bounds) for every visible tile.
-
-### .displayRegionBounds
-
-```js
-displayRegionBounds = false : Boolean
-```
-
-Display wireframe bounding rgions from the tiles `boundingVolume.region` for every visible tile if it exists.
-
-### .maxDebugDepth
-
-```js
-maxDebugDepth = - 1 : Number
-```
-
-The depth value that represents white when rendering with `DEPTH` or `RELATIVE_DEPTH` [colorMode](#colorMode). If `maxDebugDepth` is `-1` then the maximum depth of the tile set is used.
-
-### .maxDebugError
-
-```js
-maxDebugError = - 1 : Number
-```
-
-The error value that represents white when rendering with `GEOMETRIC_ERROR` [colorMode](#colorMode). If `maxDebugError` is `-1` then the maximum geometric error in the tile set is used.
-
-### .maxDebugDistance
-
-```js
-maxDebugDistance = - 1 : Number
-```
-
-The distance value that represents white when rendering with `DISTANCE` [colorMode](#colorMode). If `maxDebugDistance` is `-1` then the radius of the tile set is used.
-
-### .getDebugColor
-
-```js
-getDebugColor : ( val : Number, target : Color ) => void
-```
-
-The function used to map a [0, 1] value to a color for debug visualizations. By default the color is mapped from black to white.
-
 ## PriorityQueue
 
 Piority-sorted queue to prioritize file downloads and parsing.

example/index.js

@@ -1,5 +1,7 @@
 import {
-	DebugTilesRenderer as TilesRenderer,
+	TilesRenderer,
+	DebugTilesPlugin,
+	GLTFCesiumRTCExtension,
 	NONE,
 	SCREEN_ERROR,
 	GEOMETRIC_ERROR,
@@ -11,7 +13,6 @@ import {
 	RANDOM_NODE_COLOR,
 	CUSTOM_COLOR,
 	LOAD_ORDER,
-	GLTFCesiumRTCExtension,
 } from '../src/index.js';
 import {
 	Scene,
@@ -95,6 +96,7 @@ function reinstantiateTiles() {
 	}
 
 	tiles = new TilesRenderer( url );
+	tiles.registerPlugin( new DebugTilesPlugin() );
 
 	// 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.
@@ -484,10 +486,13 @@ function animate() {
 	tiles.stopAtEmptyTiles = params.stopAtEmptyTiles;
 	tiles.displayActiveTiles = params.displayActiveTiles;
 	tiles.maxDepth = params.maxDepth;
-	tiles.displayBoxBounds = params.displayBoxBounds;
-	tiles.displaySphereBounds = params.displaySphereBounds;
-	tiles.displayRegionBounds = params.displayRegionBounds;
-	tiles.colorMode = parseFloat( params.colorMode );
+
+	// update plugin
+	const plugin = tiles.getPluginByName( 'DEBUG_TILES_PLUGIN' );
+	plugin.displayBoxBounds = params.displayBoxBounds;
+	plugin.displaySphereBounds = params.displaySphereBounds;
+	plugin.displayRegionBounds = params.displayRegionBounds;
+	plugin.colorMode = parseFloat( params.colorMode );
 
 	if ( params.orthographic ) {
 

example/mars.js

@@ -1,5 +1,6 @@
 import {
-	DebugTilesRenderer as TilesRenderer,
+	TilesRenderer,
+	DebugTilesPlugin,
 } from '../src/index.js';
 import {
 	Scene,
@@ -66,12 +67,14 @@ function init() {
 	scene.add( tilesParent );
 
 	groundTiles = new TilesRenderer( 'https://raw.githubusercontent.com/NASA-AMMOS/3DTilesSampleData/master/msl-dingo-gap/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_colorize_tileset.json' );
+	groundTiles.registerPlugin( new DebugTilesPlugin() );
 	groundTiles.fetchOptions.mode = 'cors';
 	groundTiles.lruCache.minSize = 900;
 	groundTiles.lruCache.maxSize = 1300;
 	groundTiles.errorTarget = 12;
 
 	skyTiles = new TilesRenderer( 'https://raw.githubusercontent.com/NASA-AMMOS/3DTilesSampleData/master/msl-dingo-gap/0528_0260184_to_s64o256_colorize/0528_0260184_to_s64o256_sky/0528_0260184_to_s64o256_sky_tileset.json' );
+	skyTiles.registerPlugin( new DebugTilesPlugin() );
 	skyTiles.fetchOptions.mode = 'cors';
 	skyTiles.lruCache = groundTiles.lruCache;
 
@@ -109,8 +112,8 @@ function render() {
 	camera.updateMatrixWorld();
 
 	groundTiles.errorTarget = params.errorTarget;
-	groundTiles.displayBoxBounds = params.displayBoxBounds;
-	skyTiles.displayBoxBounds = params.displayBoxBounds;
+	groundTiles.getPluginByName( 'DEBUG_TILES_PLUGIN' ).displayBoxBounds = params.displayBoxBounds;
+	skyTiles.getPluginByName( 'DEBUG_TILES_PLUGIN' ).displayBoxBounds = params.displayBoxBounds;
 
 	groundTiles.setCamera( camera );
 	groundTiles.setResolutionFromRenderer( camera, renderer );

example/vr.js

@@ -1,14 +1,4 @@
-import {
-	DebugTilesRenderer as TilesRenderer,
-	NONE,
-	SCREEN_ERROR,
-	GEOMETRIC_ERROR,
-	DISTANCE,
-	DEPTH,
-	RELATIVE_DEPTH,
-	IS_LEAF,
-	RANDOM_COLOR,
-} from '../src/index.js';
+import { TilesRenderer } from '../src/index.js';
 import {
 	Scene,
 	DirectionalLight,
@@ -47,8 +37,6 @@ const upVector = new Vector3( 0, 1, 0 );
 
 const params = {
 
-	'displayBoxBounds': false,
-	'colorMode': 0,
 	'displayGrid': true,
 
 };
@@ -174,19 +162,6 @@ function init() {
 	const gui = new GUI();
 	gui.width = 300;
 	gui.add( params, 'displayGrid' );
-	gui.add( params, 'displayBoxBounds' );
-	gui.add( params, 'colorMode', {
-
-		NONE,
-		SCREEN_ERROR,
-		GEOMETRIC_ERROR,
-		DISTANCE,
-		DEPTH,
-		RELATIVE_DEPTH,
-		IS_LEAF,
-		RANDOM_COLOR,
-
-	} );
 	gui.open();
 
 }
@@ -292,10 +267,6 @@ function animate() {
 
 	grid.visible = params.displayGrid;
 
-	// update options
-	tiles.displayBoxBounds = params.displayBoxBounds;
-	tiles.colorMode = parseFloat( params.colorMode );
-
 	// update tiles center
 	if ( tiles.getBoundingBox( box ) ) {
 

src/index.d.ts

@@ -1,5 +1,5 @@
 // three.js
-export * from './three/DebugTilesRenderer';
+export { DebugTilesRenderer } from './three/DebugTilesRenderer';
 export { TilesRenderer } from './three/TilesRenderer';
 export { TilesGroup } from './three/TilesGroup';
 export { B3DMLoader } from './three/loaders/B3DMLoader';
@@ -18,6 +18,7 @@ export * from './three/renderers/CesiumIonTilesRenderer';
 // three.js plugins
 export { CesiumIonAuthPlugin } from './three/plugins/CesiumIonAuthPlugin';
 export { GoogleCloudAuthPlugin } from './three/plugins/GoogleCloudAuthPlugin';
+export * from './three/plugins/DebugTilesPlugin';
 
 // common
 export { TilesRendererBase } from './base/TilesRendererBase';