# TileFlatteningPlugin

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

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

Plugin that flattens tile geometry vertices onto the surface of one or more mesh
"shapes", useful for placing flat terrain overlays or cutting roads into terrain.
Shapes are added via `addShape()` and removed via `deleteShape()` or `clearShapes()`.

Example: Flattening a square of terrain

```js
import { Mesh, PlaneGeometry, Vector3 } from 'three';
import { TilesRenderer } from '3d-tiles-renderer/three';
import { TileFlatteningPlugin } from '3d-tiles-renderer/three/plugins';

// scene, camera and renderer are initialized here

const URL = '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';
const tiles = new TilesRenderer( URL );
const flattening = new TileFlatteningPlugin();
tiles.registerPlugin( flattening );
tiles.setCamera( camera );
tiles.setResolutionFromRenderer( camera, renderer );
tiles.group.rotation.x = Math.PI / 2;
scene.add( tiles.group );
camera.position.set( 20, 10, 20 );

const shape = new Mesh( new PlaneGeometry( 10, 10 ) );
shape.position.z = 1.5;
flattening.addShape( shape, new Vector3( 0, 0, 1 ) );

renderer.setAnimationLoop( () => {

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

} );
```

## Methods

### .hasShape

```js
.hasShape( mesh: Object3D ): boolean
```

Returns whether the given object has already been added as a shape.

- `mesh`, `Object3D`

### .addShape

```js
.addShape( mesh: Object3D, direction?: Vector3, options?: Object )
```

Adds the given mesh as a flattening shape. All coordinates must be in the tileset's local
frame. Throws if the shape has already been added.

- `mesh`, `Object3D`: The shape mesh to flatten tile vertices onto.
- `direction`, `Vector3`, optional: Direction to cast rays when flattening (default downward along -Z).
- `options`, `Object`, optional
  - `threshold`, `number`, optional, default `Infinity`: Maximum distance from the shape surface within which vertices are flattened. `Infinity` always flattens; `0` never flattens.

### .updateShape

```js
.updateShape( mesh: Object3D )
```

Notifies the plugin that a shape's geometry or transform has changed and tile
flattening needs to be regenerated.

- `mesh`, `Object3D`

### .deleteShape

```js
.deleteShape( mesh: Object3D ): boolean
```

Removes the given shape and triggers tile regeneration.

- `mesh`, `Object3D`

Returns `boolean`: `true` if the shape was found and removed.

### .clearShapes

```js
.clearShapes(  )
```

Removes all shapes and resets flattened tiles to their original positions.