tile-worker

Load and parse map tiles on Web Worker threads

Tiles are requested (via HTTP) from the URL endpoints specified in one of the sources specified in a MapLibre style document's 'sources' property. The returned tile data is parsed from the vector tile format to GeoJSON. This part of the work is delegated to the tile-retriever module.

The GeoJSON data is then re-mixed to a new set of layers defined by the style layers in the style document. The re-mixed data is also converted to WebGL buffers and other custom structures that can be rendered more quickly, e.g. by tile-setter. This part of the work is delegated to the tile-mixer module.

tile-worker manages tile-retriever and tile-mixer instances on Web Worker threads. The buffer data returned from the Workers is then loaded to the GPU. Loading tasks are broken up into chunks and submitted one at a time via the chunked-queue module, to avoid jank on the main thread.

Initialization

A tile-worker instance can be initialized as follows:

import * as tileWorker from 'tile-worker';

const loader = tileWorker.init(parameters);

The supplied parameters object has the following properties

• threads: Number of Web Workers that will be used to load and parse tiles from the API. Default: 2
• context: A WebGL context wrapper, as created by the tile-gl method initGLpaint. The returned buffer data will be loaded to the WebGL context by this wrapper
• queue: an instance of chunked-queue to use for managing long-running tasks. If not supplied, tile-mixer will initialize its own queue
• source: The desired source value from the 'sources' property of the style document. Note that any 'url' property will be ignored. The relevant TileJSON properties MUST be supplied directly. REQUIRED
• glyphs: The glyphs property from the style document. Used for processing text labels in symbol layers
• spriteData: The data referenced in the sprite property from the style document, loaded into an object with properties { image, meta }, as returned by tile-stencil
• layers: An array containing the layers from the style document that use data from the specified source. REQUIRED

API

Initialization returns an object that you can use to request and process a tile, as follows:

const request = loader.request({ z, x, y, getPriority, callback });

where the parameters are:

• z, x, y (REQUIRED): The coordinate indices of the desired tile
• getPriority: An optional function (with no arguments) that will return the current priority of this tile. This can be used to dynamically prioritize loading tasks. See chunked-queue for details
• callback (REQUIRED): A callback function which will be executed with the signature callback(error, data) when the request is complete

The return value is a request handle, which can be used to cancel the request as follows:

request.abort();

Other API methods on the loader object include:

• .activeTasks(): Returns the (integer) number of active tasks
• .workerTasks(): Returns the number of tasks active on worker threads
• .queuedTasks(): Returns the number of tasks queued on the main thread
• .terminate(): Cancels all tasks and terminates the Web Workers