# MVTAnnotationsDriver

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

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

Bundles the callbacks the "MVTAnnotationsPlugin" needs into a single object. Subclass and override
the methods to customize which features become annotations, their placement priority, per-character
sizing, the displayed text, and how visibility changes are rendered. By default all points of interest
are rendered as circles and labels are rendered as white text with a black outline. Custom implementations
can be used for more sophisticated text rendering, variable font weights based on properties, and custom
icons.

## Properties

### .needsUpdate: boolean

Set to "true" when the filters or settings have changed to trigger an
update to the annotations in the plugin.

### .group: Group

Render group for the driver's own three.js objects. The plugin mounts it under
`tiles.group` on `init` unless it has already been parented elsewhere, eg to render
annotations in a separate pass, and removes it on `dispose`; add any objects the
driver draws to it.

### .performSettleRaycast: MVTRaycastCallback | null

Optional callback overriding the default surface raycast used when settling annotations
onto the tile geometry, letting the caller analyze the hits and return a better point.
Leave null to use the plugin's default raycasting.

### .sampleCartographicElevation: MVTElevationSampleCallback | null

Optional callback used to settle annotations by sampling elevations directly, which is
much faster than raycasting. Takes precedence over any registered plugin providing
"sampleCartographicElevation" while "performSettleRaycast" takes precedence over both.
Leave null to use the plugin's default behavior.

## Methods

### .filterAnnotation

```js
.filterAnnotation( layer: string, properties: Object, type: number ): boolean
```

Whether an MVT feature should be included as an annotation.

- `layer`, `string`: The MVT layer name the feature belongs to.
- `properties`, `Object`: The feature's property map.
- `type`, `number`: The MVT geometry type: `1` = point, `2` = line.

Returns `boolean`: True to include the feature as an annotation.

### .getAnnotationRank

```js
.getAnnotationRank( annotation: Object ): number
```

Placement priority for an annotation. Lower values are placed first and win collisions.
Values are clamped to the [ 0, 4095 ] integer range.

- `annotation`, `Object`: The annotation to prioritize.

Returns `number`: The placement priority.

### .measureChar

```js
.measureChar( char: string, layer: layer, properties: Object ): number
```

Advance width of a single character, in pixels, used to space glyphs along text labels.

- `char`, `string`: The character to measure.
- `layer`, `layer`: The layer associated with the text.
- `properties`, `Object`: The properties associated with the text.

Returns `number`: The advance width in pixels.

### .getText

```js
.getText( properties: Object ): string
```

The string a line / road annotation should display for the given feature.

- `properties`, `Object`: The feature's property map.

Returns `string`: The label text, or an empty string to render nothing.

### .isAnnotationEnabled

```js
.isAnnotationEnabled( layer: string, properties: Object, type: number ): boolean
```

Whether a parsed annotation should currently be displayed. Unlike `filterAnnotation` which
decides what is parsed once.

- `layer`, `string`: The MVT layer name the feature belongs to.
- `properties`, `Object`: The feature's property map.
- `type`, `number`: The MVT geometry type: `1` = point, `2` = line.

Returns `boolean`: True to display the annotation.

### .onPointsUpdate

```js
.onPointsUpdate( added: Array<Object>, removed: Array<Object> ): void
```

Called each frame with the point ( PoI ) annotations whose visibility changed, for the caller
to render.

- `added`, `Array<Object>`: Point annotations that became visible this frame.
- `removed`, `Array<Object>`: Point annotations that became hidden this frame.

### .onLabelsUpdate

```js
.onLabelsUpdate( added: Array<Object>, removed: Array<Object> ): void
```

Called each frame with the line / label annotations whose visibility changed, for the caller
to render.

- `added`, `Array<Object>`: Label annotations that became visible this frame.
- `removed`, `Array<Object>`: Label annotations that became hidden this frame.

### .dispose

```js
.dispose(  ): void
```

Releases any resources the driver created (geometries, materials, textures, etc.). Called by
the plugin from its own `dispose`.