NASA-AMMOS · gkjohnson · May 16, 2026 · Apr 12, 2026 · Apr 12, 2026 · Apr 13, 2026
diff --git a/example/three/deepZoom.js b/example/three/deepZoom.js
@@ -5,7 +5,7 @@ import {
 	OrthographicCamera,
 } from 'three';
 import { EnvironmentControls, TilesRenderer, CameraTransitionManager } from '3d-tiles-renderer';
-import { DeepZoomImagePlugin, UpdateOnChangePlugin } from '3d-tiles-renderer/plugins';
+import { UpdateOnChangePlugin, DeepZoomOverlay, GeneratedSurfacePlugin } from '3d-tiles-renderer/plugins';
 import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
 
 let controls, scene, renderer;
@@ -14,8 +14,6 @@ let tiles, transition;
 const params = {
 
 	errorTarget: 1,
-	renderScale: 1,
-
 	orthographic: false,
 
 };
@@ -53,8 +51,12 @@ function init() {
 	} );
 
 	// tiles
-	tiles = new TilesRenderer( 'https://openseadragon.github.io/example-images/duomo/duomo.dzi' );
-	tiles.registerPlugin( new DeepZoomImagePlugin( { center: true } ) );
+	tiles = new TilesRenderer();
+	tiles.registerPlugin( new GeneratedSurfacePlugin( {
+		overlay: new DeepZoomOverlay( {
+			url: 'https://openseadragon.github.io/example-images/duomo/duomo.dzi',
+		} ),
+	} ) );
 	tiles.registerPlugin( new UpdateOnChangePlugin() );
 	tiles.fetchOptions.mode = 'cors';
 	tiles.lruCache.minSize = 900;
@@ -91,12 +93,11 @@ function init() {
 
 	} );
 
-	gui.add( params, 'errorTarget', 0, 100 ).onChange( () => {
+	gui.add( params, 'errorTarget', 1, 100 ).onChange( () => {
 
 		tiles.getPluginByName( 'UPDATE_ON_CHANGE_PLUGIN' ).needsUpdate = true;
 
 	} );
-	gui.add( params, 'renderScale', 0.1, 1.0, 0.05 ).onChange( v => renderer.setPixelRatio( v * window.devicePixelRatio ) );
 
 	gui.open();
 

diff --git a/example/three/geojson.js b/example/three/geojson.js
diff --git a/example/three/mapTiles.html b/example/three/mapTiles.html
@@ -6,6 +6,19 @@
 
 		<title>XYZ & TMS Tiles</title>
 		<link rel="stylesheet" href="../styles.css">
+		<style>
+			#coords {
+				position: absolute;
+				bottom: 0;
+				left: 0;
+				padding: 8px;
+				color: white;
+				font-size: 12px;
+				pointer-events: none;
+				font-family: monospace;
+				text-shadow: 0 0 2px black;
+			}
+		</style>
     </head>
     <body>
 		<div id="info">
@@ -14,6 +27,7 @@
 			<br/>
 			Example courtesy of <a href="https://www.openstreetmap.org/">OpenStreetMap</a>.
 		</div>
+		<div id="coords"></div>
         <script src="./mapTiles.js" type="module"></script>
     </body>
 </html>
diff --git a/example/three/mapTiles.js b/example/three/mapTiles.js
@@ -2,18 +2,28 @@ import {
 	Scene,
 	WebGLRenderer,
 	PerspectiveCamera,
+	Raycaster,
+	Vector2,
+	Matrix4,
+	MathUtils,
 } from 'three';
 import { TilesRenderer, GlobeControls, EnvironmentControls } from '3d-tiles-renderer';
-import { TilesFadePlugin, UpdateOnChangePlugin, XYZTilesPlugin, } from '3d-tiles-renderer/plugins';
+import { TilesFadePlugin, UpdateOnChangePlugin, GeneratedSurfacePlugin, XYZTilesOverlay, CesiumIonOverlay } from '3d-tiles-renderer/plugins';
 import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
 
 let controls, scene, renderer;
-let tiles, camera;
+let tiles, camera, surfacePlugin;
+
+const toLocalMat = new Matrix4();
+const raycaster = new Raycaster();
+const mouse = new Vector2();
+const coordsEl = document.getElementById( 'coords' );
 
 const params = {
 
 	errorTarget: 1,
 	planar: false,
+	overlay: 'OpenStreetMap',
 
 };
 
@@ -44,10 +54,12 @@ function init() {
 	// events
 	onWindowResize();
 	window.addEventListener( 'resize', onWindowResize, false );
+	renderer.domElement.addEventListener( 'mousemove', onMouseMove, false );
 
 	// gui initialization
 	const gui = new GUI();
 	gui.add( params, 'planar' ).onChange( initTiles );
+	gui.add( params, 'overlay', [ 'OpenStreetMap', 'Sentinel-2' ] ).onChange( initTiles );
 	gui.add( params, 'errorTarget', 1, 40 ).onChange( () => {
 
 		tiles.getPluginByName( 'UPDATE_ON_CHANGE_PLUGIN' ).needsUpdate = true;
@@ -73,21 +85,26 @@ function initTiles() {
 
 	}
 
+	const overlay = params.overlay === 'Sentinel-2'
+		? new CesiumIonOverlay( { assetId: 3954, apiToken: import.meta.env.VITE_ION_KEY } )
+		: new XYZTilesOverlay( { url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png' } );
+
 	// tiles
 	tiles = new TilesRenderer();
 	tiles.registerPlugin( new TilesFadePlugin( { maximumFadeOutTiles: 200 } ) );
 	tiles.registerPlugin( new UpdateOnChangePlugin() );
-	tiles.registerPlugin( new XYZTilesPlugin( {
-		center: true,
+	surfacePlugin = new GeneratedSurfacePlugin( {
+		overlay,
 		shape: params.planar ? 'planar' : 'ellipsoid',
-		url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
-	} ) );
+	} );
+	tiles.registerPlugin( surfacePlugin );
 
 	tiles.lruCache.minSize = 900;
 	tiles.lruCache.maxSize = 1300;
 	tiles.parseQueue.maxJobs = 3;
 	tiles.setCamera( camera );
 	scene.add( tiles.group );
+	window.TILES = tiles;
 
 	if ( params.planar ) {
 
@@ -158,6 +175,31 @@ function render() {
 
 }
 
+function onMouseMove( e ) {
+
+	mouse.x = ( e.clientX / window.innerWidth ) * 2 - 1;
+	mouse.y = - ( e.clientY / window.innerHeight ) * 2 + 1;
+
+	raycaster.setFromCamera( mouse, camera );
+	const hits = raycaster.intersectObject( tiles.group, true );
+	if ( hits.length > 0 ) {
+
+		toLocalMat.copy( tiles.group.matrixWorld ).invert();
+		hits[ 0 ].point.applyMatrix4( toLocalMat );
+
+		const cart = surfacePlugin.getCartographicFromPosition( hits[ 0 ].point );
+		const lat = MathUtils.radToDeg( cart.lat ).toFixed( 2 );
+		const lon = MathUtils.radToDeg( cart.lon ).toFixed( 2 );
+		coordsEl.textContent = `${ lat }°  ${ lon }°`;
+
+	} else {
+
+		coordsEl.textContent = '';
+
+	}
+
+}
+
 function throttle( callback ) {
 
 	let scheduled = false;

diff --git a/example/three/wmsTiles.js b/example/three/wmsTiles.js
@@ -1,6 +1,6 @@
 import { Scene, WebGLRenderer, PerspectiveCamera } from 'three';
 import { TilesRenderer, GlobeControls } from '3d-tiles-renderer';
-import { TilesFadePlugin, UpdateOnChangePlugin, WMSCapabilitiesLoader, WMSTilesPlugin } from '3d-tiles-renderer/plugins';
+import { TilesFadePlugin, UpdateOnChangePlugin, WMSCapabilitiesLoader, WMSTilesOverlay, GeneratedSurfacePlugin } from '3d-tiles-renderer/plugins';
 import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
 
 const url =
@@ -110,9 +110,8 @@ function rebuildTiles() {
 	tiles = new TilesRenderer();
 	tiles.registerPlugin( new TilesFadePlugin() );
 	tiles.registerPlugin( new UpdateOnChangePlugin() );
-	tiles.registerPlugin(
-		new WMSTilesPlugin( {
-			shape: 'ellipsoid',
+	tiles.registerPlugin( new GeneratedSurfacePlugin( {
+		overlay: new WMSTilesOverlay( {
 			url: capabilities.request.GetMap.href,
 			layer: params.layer,
 			contentBoundingBox: layer.contentBoundingBox,
@@ -122,7 +121,8 @@ function rebuildTiles() {
 			styles: params.styles,
 			version: capabilities.version,
 		} ),
-	);
+		shape: 'ellipsoid',
+	} ) );
 
 	tiles.group.rotation.x = - Math.PI / 2;
 	scene.add( tiles.group );

diff --git a/example/three/wmtsTiles.js b/example/three/wmtsTiles.js
@@ -4,7 +4,7 @@ import {
 	PerspectiveCamera,
 } from 'three';
 import { TilesRenderer, GlobeControls, EnvironmentControls } from '3d-tiles-renderer';
-import { TilesFadePlugin, UpdateOnChangePlugin, WMTSCapabilitiesLoader, WMTSTilesPlugin } from '3d-tiles-renderer/plugins';
+import { TilesFadePlugin, UpdateOnChangePlugin, WMTSCapabilitiesLoader, WMTSTilesOverlay, GeneratedSurfacePlugin } from '3d-tiles-renderer/plugins';
 import { GUI } from 'three/addons/libs/lil-gui.module.min.js';
 
 const url = window.location.hash.replace( /^#/, '' ) || 'https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/wmts.cgi?SERVICE=WMTS&request=GetCapabilities';
@@ -169,18 +169,19 @@ function rebuildTiles() {
 	tiles = new TilesRenderer();
 	tiles.registerPlugin( new TilesFadePlugin() );
 	tiles.registerPlugin( new UpdateOnChangePlugin() );
-	tiles.registerPlugin( new WMTSTilesPlugin( {
+	tiles.registerPlugin( new GeneratedSurfacePlugin( {
+		overlay: new WMTSTilesOverlay( {
+			url,
+			tileMatrices: tileMatrixSet.tileMatrices,
+			contentBoundingBox,
+			projection: 'EPSG:4326',
+			dimensions: params.dimensions,
+			style: params.style,
+			layer: params.layer,
+			tileMatrixSet: params.tileMatrixSet,
+		} ),
 		shape: params.planar ? 'planar' : 'ellipsoid',
 		center: true,
-
-		url,
-		tileMatrices: tileMatrixSet.tileMatrices,
-		contentBoundingBox,
-		projection: 'EPSG:4326',
-		dimensions: params.dimensions,
-		style: params.style,
-		layer: params.layer,
-		tileMatrixSet: params.tileMatrixSet,
 	} ) );
 
 	tiles.setCamera( camera );

diff --git a/src/three/plugins/API.md b/src/three/plugins/API.md
@@ -192,6 +192,25 @@ Manages a `TiledImageSource` and a `RegionImageSource` that handles compositing
 multiple source tiles into a single texture per 3D tile region.
 
 
+## DeepZoomOverlay
+
+_extends [`TiledImageOverlay`](#tiledimageoverlay)_
+
+Plugin that renders a Deep Zoom Image (DZI) as a tiled overlay. Only a single embedded "Image" is supported.
+See the [Deep Zoom specification](https://learn.microsoft.com/en-us/previous-versions/windows/silverlight/dotnet-windows-silverlight/cc645077(v=vs.95))
+and [OpenSeadragon](https://openseadragon.github.io).
+
+
+### .constructor
+
+```js
+constructor(
+	{
+		url?: string,
+	}
+)
+```
+
 ## GoogleMapsOverlay
 
 _extends [`TiledImageOverlay`](#tiledimageoverlay)_
@@ -566,6 +585,53 @@ constructor(
 )
 ```
 
+## GeneratedSurfacePlugin
+
+Plugin that generates tiled surface geometry from a tiling scheme, optionally loading
+image overlay data.
+
+The tiling scheme and projection are derived from a provided overlay.
+If the source's projection is cartographic (any EPSG scheme), the plugin supports
+both planar and ellipsoidal geometry via the `shape` option.
+
+
+### .constructor
+
+```js
+constructor(
+	{
+		overlay = null: ImageOverlay,
+		shape = 'ellipsoid': string,
+		endCaps = true: boolean,
+		center = true: boolean,
+		useRecommendedSettings = true: boolean,
+	}
+)
+```
+
+### .getCartographicFromPosition
+
+```js
+getCartographicFromPosition( position: Vector3, target = {}: Object ): Object
+```
+
+Returns the cartographic coordinates for a given world-space position. "lat" and "lon" are assigned
+to the target object.
+
+
+### .getPositionFromCartographic
+
+```js
+getPositionFromCartographic(
+	lat: number,
+	lon: number,
+	target = new Vector3(): Vector3
+): Vector3
+```
+
+Returns the world-space position for a given cartographic coordinate.
+
+
 ## GLTFCesiumRTCExtension
 
 GLTF loader plugin that applies the [CESIUM_RTC](https://github.com/KhronosGroup/glTF/blob/main/extensions/1.0/Vendor/CESIUM_RTC/README.md)