docsby gkjohnson

MVTAnnotationsDriver

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.

On this page

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: ( ray: Ray, lat: number, lon: number, target: Vector3 ) => boolean | 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: ( lat: number, lon: number ) => number | null | 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

filterAnnotation(
	// The MVT layer name the feature belongs to.
	layer: string,

	// The feature's property map.
	properties: Object,

	// The MVT geometry type: `1` = point, `2` = line.
	type: number
): boolean

Whether an MVT feature should be included as an annotation.

getAnnotationRank

getAnnotationRank(
	// The annotation to prioritize.
	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.

measureChar

measureChar(
	// The character to measure.
	char: string,

	// The layer associated with the text.
	layer: layer,

	// The properties associated with the text.
	properties: Object
): number

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

getText

getText(
	// The feature's property map.
	properties: Object
): string

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

isAnnotationEnabled

isAnnotationEnabled(
	// The MVT layer name the feature belongs to.
	layer: string,

	// The feature's property map.
	properties: Object,

	// The MVT geometry type: `1` = point, `2` = line.
	type: number
): boolean

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

onPointsUpdate

onPointsUpdate(
	// Point annotations that became visible this frame.
	added: Array<Object>,

	// Point annotations that became hidden this frame.
	removed: Array<Object>
): void

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

onLabelsUpdate

onLabelsUpdate(
	// Label annotations that became visible this frame.
	added: Array<Object>,

	// Label annotations that became hidden this frame.
	removed: Array<Object>
): void

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

dispose

dispose(): void

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