# XYZTilesOverlay

class in `3d-tiles-renderer/three/plugins`, extends `TiledImageOverlay`

```js
import { XYZTilesOverlay } from '3d-tiles-renderer/three/plugins';
```

Overlay that renders XYZ/Slippy-map image tiles (e.g. OpenStreetMap) on top of 3D tile
geometry. See the `Slippy map tilenames specification`.

Example: Wrapping XYZ map tiles around the globe

```js
import { TilesRenderer, GlobeControls } from '3d-tiles-renderer/three';
import { GeneratedSurfacePlugin, XYZTilesOverlay } from '3d-tiles-renderer/three/plugins';

// scene, camera and renderer are initialized here

const URL = 'https://tile.openstreetmap.org/{z}/{x}/{y}.png';

const tiles = new TilesRenderer();
tiles.registerPlugin( new GeneratedSurfacePlugin( {
	overlay: new XYZTilesOverlay( { url: URL } ),
	applyOverlayTexture: true,
} ) );
tiles.setCamera( camera );
tiles.group.rotation.x = - Math.PI / 2;
scene.add( tiles.group );

camera.position.set( 0, 0, 1.75e7 );

const controls = new GlobeControls( scene, camera, renderer.domElement );
controls.setEllipsoid( tiles.ellipsoid, tiles.group );
controls.enableDamping = true;

renderer.setAnimationLoop( () => {

	controls.update();
	camera.updateMatrixWorld();
	tiles.setResolutionFromRenderer( camera, renderer );
	tiles.update();
	renderer.render( scene, camera );

} );
```

## Constructor

```js
new XYZTilesOverlay( options?: Object )
```

- `options`, `Object`, optional
  - `url`, `string`, optional: URL template with `{x}`, `{y}`, `{z}` placeholders.
  - `levels`, `number`, optional, default `20`: Number of zoom levels.
  - `tileDimension`, `number`, optional, default `256`: Tile pixel size.
  - `projection`, `string`, optional, default `'EPSG:3857'`: Projection scheme identifier.
  - `opacity`, `number`, optional, default `1`: Overlay opacity (0–1).
  - `color`, `number | Color`, optional, default `0xffffff`: Tint color.
  - `frame`, `Matrix4`, optional, default `null`: Planar projection frame. If null, cartographic projection is used.
  - `preprocessURL`, `function`, optional, default `null`: URL rewriting callback.
  - `alphaMask`, `boolean`, optional, default `false`: Use alpha channel as a surface mask.
  - `alphaInvert`, `boolean`, optional, default `false`: Invert the alpha channel.