tile-labeler

Convert map label features into WebGL buffers for rendering

Feature layout is guided by a MapLibre style document, as parsed by tile-stencil. The returned buffers are consistent with the format returned by tile-mixer.

See the simple test plotting computed character positions over a pre-rendered tile.

Installation

tile-labeler is provided as an ESM import

import * as tileLabeler from 'tile-labeler';

tileLabeler exposes two methods:

• initAtlasGetter
• initShaping

initAtlasGetter

Returns a function that collects font names and character codes for each label, and constructs an atlas of glyph SDFs (via sdf-manager).

Syntax

const getAtlas = tileLabeler.initAtlasGetter(params);

Parameters

The supplied parameters object has the following properties:

• parsedStyles (Array): An array of MapLibre style layers, with style functions already parsed by tile-stencil
• glyphEndpoint (String): The URL template from the glyphs property of a MapLibre style document. Any Mapbox-specific domains or API keys must have been already expanded by tile-stencil

API

The returned atlas getter function inputs tile data, and returns a Promise that resolves to an atlas of glyph SDFs. For example,

getAtlas(layers, zoom).then(atlas => {
  // Use atlas to shape label features and construct WebGL buffers
});

The parameters for the getAtlas function are:

• layers (Object): A dictionary of tile layers, keyed on the .id property of the style for that layer. (NOTE: this is probably NOT the natural order of the tile data—it should be pre-filtered. See filter-source.js in tile-mixer.) Each layer should have a .features property pointing to an array of GeoJSON features.
• zoom (Number): The zoom level at which style layout functions will be evaluated

The data returned from the labeler function includes:

• { width, height, data } = atlas: The signed distance field (SDF) data to be loaded as an Alpha texture. data is a Uint16Array

NOTE also that any label features in layer.features will have the following properties added (MODIFIED IN PLACE):

• feature.font (String): The name of the font used to render this label
• feature.charCodes (Array): The character codes of the characters in the label text

initShaping

Returns utilities to construct WebGL buffers for valid label features.

The syntax is as follows:

const { serialize, getLength, styleKeys } = tileLabeler
  .initShaping(style, spriteData);

where the arguments are:

• style: A 'symbol' layer from a MapLibre style document, with the .layout property parsed into value getters by tile-stencil.
• spriteData: The data retrieved by tile-stencil from the URL described in the sprite property of the style document

There are three named returns: { serialize, getLength, styleKeys}

serialize

The serialize method can serialize a feature, using the following signature:

const buffers = serialize(feature, zoom, atlas, tree);

where the arguments are as follows:

• feature: A GeoJSON feature, to which the properties .font and .charCodes have been added by a previous call to a getAtlas function (see above under initAtlasGetter).
• zoom: The map zoom level at which this label will be displayed
• atlas: An atlas of glyph SDFs, as generated by the getAtlas call
• tree: An rbush object used for checking collisions with previous labels. The user is responsible for initializing this object, and supplying layers in the correct order.

getLength

The getLength method inputs the buffers returned by serialize, and returns the number of instances that must be rendered to display the serialized feature.

const numInstances = getLength(buffers);

styleKeys

The styleKeys property is an Array of Strings, each representing the key of a symbol style layer property. The values of these properties, if they are specified as feature property functions, will need to be loaded into buffers for rendering. tile-labeler does not construct these buffers, but .getLength and .styleKeys provide the information needed to construct them. See tile-gl code for an example of how to do this.