Load a MapLibre style document and parse it into Javascript functions
MapLibre style documents describe how a map should be drawn. The document begins with input information, such as:
- Data sources to be used (tiles, GeoJSON, etc.)
- Where to get sprites (small images used as labels)
Then, it specifies a list of layers, in the order in which they should be drawn. Layers further down the list are drawn on top of the earlier layers. For each layer, the style document describes:
- Which data source to use
- A data filter, to select features from the source to draw in this layer
- What style properties (colors, line thicknesses, fonts, etc) to use when drawing
The style properties (colors, etc) are specified as functionsโi.e., they can vary depending on the zoom level or some property of the feature.
tile-stencil reads the document, loads relevant data about the source, loads the sprite data, and parses the specified filters and property functions into Javascript functions that can be used by a renderer.
tile-stencil is provided as an ESM import.
import * as tileStencil from 'tile-stencil';
tileStencil exposes three methods:
- getStyleFuncs
- loadStyle
- buildFeatureFilter
const parsedLayer = tileStencil.getStyleFuncs(inputLayer);
layer
: An element from the [layers][] property of a MapLibre style document
A copy of inputLayer
, where the .layout
and .paint
properties have been
replaced by value getter dictionaries
The returned objects can be used to retrieve style properties as follows
(where our example layer has layer.type === "line"
):
var lineColor = paint["line-color"](zoom, feature);
where zoom
is the zoom level of the map being drawn, and feature
is the
feature being drawn.
Some styles do not depend on feature properties, or even the zoom level.
Each .layout
and .paint
property function has a defined .type
, e.g.,
styleFunctionType = paint["style-property"].type;
where .type
may take one of three values:
constant
: Defines a style property that does not varyzoom
: Style value depends on the map zoom levelproperty
: Style value depends on feature properties
Loads a style document and any linked information.
You can test this method live using the validator example.
const loadedStyle = loadStyle(styleDoc, mapboxToken);
styleDoc
: A MapLibre Style document, OR a URL pointing to a style documentmapboxToken
: Your Mapbox API key (Optional). This is only needed if your style document includes references to Mapbox-hosted resources, such as TileJSON or sprite data.
A Promise that resolves to a parsed style document.
The parsed document will have the following changes relative to the input:
styleDoc.sources
: If a source was specified as a URL pointing to a TileJSON document, the properties of that source will be augmented by properties retrieved from the linked documentstyleDoc.spriteData
: This additional object contains the data pointed to by the URL instyleDoc.sprite
..spriteData
has two properties:.spriteData.image
: A PNG image file containing the sprite data.spriteData.meta
: The JSON document containing the description of each image contained in the sprite
styleDoc.layers
: Some MapLibre styles have non-standard layers that do not list all of the required properties, but rather 'reference' these properties from another layer. The layers in the parsed document will have these references resolved, so that the returned document is standards-compliant.
Converts the filter description from a MapLibre layer into a JavaScript function for filtering GeoJSON features.
The returned function can be used to filter features to the appropriate subset to be used in rendering this layer, e.g.,
const parsedFilter = buildFeatureFilter(layer.filter);
layerFeatures = features.filter(parsedFilter);
Note: the supplied filter description MUST follow the deprecated syntax!
tile-stencil does not implement the following features of the style specification:
- Image or video sources
- Zoom-and-property functions
- Expressions
While expressions are not yet implemented, tile-stencil does implement the following older features: