tile-painter

Canvas 2D rendering for vector maps, guided by a Mapbox style document

Rendering is done with Canvas 2D methods rather than WebGL. This makes the code simpler, but slower.

See a simple example using data and styles from OpenMapTiles.

Please note: many features in Mapbox's specification are not implemented. tile-painter is intended to be an 80/20 solution for vector tile rendering: implementing ~80% of the style specification with 20% of the code.

Installation

tile-painter is provided as an ESM import.

import * as tilePainter from 'tile-painter';

tilePainter exposes four methods:

• initMapPainter
• initPainterOnly
• initPainter
• addPainters

initMapPainter

Returns a painter function that will paint one layer from one tile, at a given location and scale on the supplied context's canvas.

Syntax

const painter = tilePainter.initMapPainter(params);

Parameters

The supplied parameters object has the following properties:

• tileSize (number): the pixel size of the (square) input tiles, in the same coordinates as the feature geometries. Default: 512
• styleLayer (object): an element from the layers array of a Mapbox style document, where the .layout and .paint properties have been parsed into functions. See the getStyleFuncs method of tile-stencil for the expected signature of these functions. REQUIRED
• spriteObject (object): an object pointing to the data for a sprite atlas. Must include image and meta properties, pointing to the actual data (PNG and JSON). If you are starting from a style document with a URL string, you will need to load the data from the URL and put it in an object before calling initPainter. REQUIRED if layer.type === "symbol" and icon-<property> parameters are set
• context: A link to the Canvas 2D rendering context to which the painter will draw. REQUIRED

Return value

initMapPainter returns a painter function, which will render the styleLayer on the context's canvas. The painter function has the following signature:

var modified = painter(params);

where modified is a (Boolean) flag indicating whether context.canvas has changed. The supplied params object has the following properties:

• source: Map data from the source property of the style layer, to be rendered on the map. Vector tile sources must be pre-processed by the tile-mixer module. See below for details. REQUIRED for all layer types except "background"
• position: An object describing the area on the output map to which the supplied source data will be rendered. Required properties:
  • x: The x-coordinate of the top left corner of the area to be rendered, in map pixels from the left edge of the map
  • y: The y-coordinate of the top left corner of the area to be rendered, in map pixels from the top edge of the map
  • w: The width of the (square) area to be rendered, in map pixels
• crop: An object describing the portion of the supplied source data to be rendered. Required properties:
  • x: The x-coordinate of the source data that will be aligned with the left edge of the rendered area on the map
  • y: The y-coordinate of the source data that will be aligned with the top edge of the rendered area on the map
  • w: The width of the (square) portion of the source data that will be rendered, in source data coordinates
• zoom: The current zoom level of the map, to be used in style calculations
• boxes (Optional): For layers of "symbol" type. An array containing the bounding boxes of "symbols" (labels and sprites) already rendered on the Canvas from previous layers. Bounding boxes of any new symbols in the current layer will be computed and checked for collisions with previously rendered symbols. If there is a collision, the new symbol will not be rendered. If there is no collision, the new symbol will be rendered, and its bounding box added to the array. Bounding boxes are supplied in the form [[xmin, ymin], [xmax, ymax]] in the current tile's pixel coordinates

Required vector source pre-processing

The supplied source object for vector layers is assumed to be a dictionary of GeoJSON FeatureCollections, where each FeatureCollection corresponds to the data for one style layer (as returned by tile-mixer).

Each FeatureCollection may have two non-standard properties:

• properties: For layers of type symbol, this top-level properties object should contain a font property, with the value being a CSS font string to be used for all symbols in the layer.
• compressed: An array of features as pre-processed by tile-mixer

For style layers with type circle, line, or fill, each feature in the compressed array should have the following properties:

• properties: The feature properties that affect styling.
• path: A Path2D object corresponding to the geometry of the feature Path coordinates must be scaled from the vector tile's .extent to the desired pixel size of the rendered tile. Layers of type circle have a path of the form M x y L x y (in SVG notation) for each point in the layer.

For style layers with type symbol, each feature in the compressed array may have the following properties:

• geometry: A GeoJSON geometry where the symbol will be drawn. Only Point geometries are currently supported. REQUIRED.
• properties.labelText: The text to be written at this label position
• properties.textWidth: The measured width of the text, as given by ctx.measureText(labelText).width
• properties.spriteID: The key to the metadata of the sprite to be written. This will be retrieved from the spriteObject supplied on initialization as follows: spriteMeta = spriteObject.meta[spriteId]

initPainterOnly

Returns a painter function for a single style layer

Syntax

const painter = tilePainter.initPainterOnly(params);

Parameters

The supplied parameters object has the following properties:

• canvasSize (integer): the pixel size of the (square) Canvas to which the layer will be rendered. Default: 512
• styleLayer (object): an element from the layers array of a Mapbox style document, where the .filter, .layout, and .paint properties have been parsed into functions. See the parseLayer function of tile-stencil for the expected signature of these functions. REQUIRED
• spriteObject (object): an object pointing to the data for a sprite atlas. Must include image and meta properties, pointing to the actual data (PNG and JSON). If you are starting from a style document with a URL string, you will need to load the data from the URL and put it in an object before calling initPainter. REQUIRED if layer.type === "symbol" and icon-<property> parameters are set

Return value

initPainterOnly returns a painter function, which will render the styleLayer on a supplied Canvas. The painter function has the following signature:

var modified = painter(context, zoom, data, boundingBoxes);

where modified is a (Boolean) flag indicating whether context.canvas has been changed. The supplied parameters are:

• context (REQUIRED): The Canvas 2D rendering context on which the rendering calls will be executed
• zoom (REQUIRED): The map zoom level at which the layer will be rendered
• data: Map data from the source property of the style layer, to be rendered on the map. Vector tile sources must be pre-processed by the tile-mixer module, as described above under initMapPainter. REQUIRED for all layer types except "background"
• boundingBoxes (Optional): For layers of "symbol" type. An array containing the bounding boxes of "symbols" (labels and sprites) already rendered on the Canvas from previous layers. Bounding boxes of any new symbols in the current layer will be computed and checked for collisions with previously rendered symbols. If there is a collision, the new symbol will not be rendered. If there is no collision, the new symbol will be rendered, and its bounding box added to the array. Bounding boxes are supplied in the form [[xmin, ymin], [xmax, ymax]] in the current tile's pixel coordinates

initPainter

Wrapper method for initPainterOnly. The returned function takes a sources object instead of a data object. This sources object MUST have the same structure as the sources property of the style document, but containing actual data for a tile.

Each individual source key points to a data object as described above for initPainterOnly.

Syntax

const painter = tilePainter.initPainter(params);

Parameters

See above under initPainterOnly

Return value

initPainter returns a painter function, which will render the styleLayer on a supplied Canvas. The painter function has the following signature:

var modified = painter(context, zoom, sources, boundingBoxes);

where modified is a (Boolean) flag indicating whether context.canvas has been changed. The supplied parameters are:

• context (REQUIRED): The Canvas 2D rendering context on which the rendering calls will be executed
• zoom (REQUIRED): The map zoom level at which the layer will be rendered
• sources: An object with the same structure as the sources property of the style document, but containing actual data for a tile. Vector tile sources must be pre-processed into a GeoJSON-style object, as output by the tile-mixer module. See initPainterOnly for details. REQUIRED for all layer types except "background"
• boundingBoxes (Optional): For layers of "symbol" type. See initPainterOnly for details

addPainters

Adds a painter function to every layer of a style document

Syntax

const styleDoc = tilePainter.addPainters(styleDoc, canvasSize);

Parameters

• canvasSize: The size (in pixels) of the canvas to which the supplied context is drawing. Default: 512
• styleDoc: A parsed Mapbox style document, as output by the parseStyle function from tile-stencil.

Return value

A link back to the modified style document. (NOTE: input document is changed!) Each layer in the document will have an added .painter property, which is a function constructed by initPainter as described above.

Un-implemented features

tile-painter is a work in progress. Many features are not implemented yet. Incomplete features include:

• This list
• symbol-placement values other than "point". Text following roads or riverbeds will not be rendered!
• Rotated symbols (text and sprites)
• Text wrapping for long labels. text-max-width is ignored
• text-letter-spacing

Pull requests are welcomed!