# ImageOverlayPlugin

class in `3d-tiles-renderer/three/plugins`

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

Plugin that composites one or more tiled image overlays onto 3D tile geometry by
generating per-tile textures from image sources (XYZ, TMS, WMTS, WMS, GeoJSON, etc.).
Image sources are added via `addOverlay()` and removed via `deleteOverlay()`.

Example: Layering a transparent overlay over the globe's imagery

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

// scene, camera and renderer are initialized here

const URL = 'https://server.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer/tile/{z}/{y}/{x}';
const SATELLITE_URL = 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}';

const tiles = new TilesRenderer();
tiles.registerPlugin( new GeneratedSurfacePlugin( {
	overlay: new XYZTilesOverlay( { url: SATELLITE_URL } ),
	applyOverlayTexture: true,
} ) );
tiles.registerPlugin( new ImageOverlayPlugin( {
	renderer,
	overlays: [ new XYZTilesOverlay( { url: URL } ) ],
} ) );
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 ImageOverlayPlugin( options?: Object )
```

- `options`, `Object`, optional
  - `overlays`, `Array`, optional, default `[]`: Initial image overlay sources to add.
  - `resolution`, `number`, optional, default `256`: Resolution of each generated tile texture in pixels.
  - `enableTileSplitting`, `boolean`, optional, default `true`: Allow tiles to be split to match image tile boundaries.

## Methods

### .addOverlay

```js
.addOverlay( overlay: ImageOverlay, order?: number | null )
```

Adds an image overlay source to the plugin. The `order` parameter controls the draw
order among overlays; lower values are drawn first. If omitted, the overlay is appended
after all existing overlays.

- `overlay`, `ImageOverlay`: An image overlay instance.
- `order`, `number | null`, optional, default `null`: Draw order for this overlay.

### .setOverlayOrder

```js
.setOverlayOrder( overlay: ImageOverlay, order: number )
```

Updates the draw order for the given overlay.

- `overlay`, `ImageOverlay`: The overlay to reorder.
- `order`, `number`: New draw order value.

### .deleteOverlay

```js
.deleteOverlay( overlay: ImageOverlay )
```

Removes the given overlay from the plugin.

- `overlay`, `ImageOverlay`: The overlay to remove.

### .resetFailedOverlays

```js
.resetFailedOverlays(  )
```

Retries any overlay texture fetches that previously failed. Successfully loaded textures
are applied to their tiles without requiring a geometry reload. Pairs with the `load-error`
event, which fires on the `TilesRenderer` when an overlay texture fetch fails.