leaflet-vector-tile-layer

Leaflet.VectorTileLayer
=======================

This module provides a [Leaflet][L] layer that displays [vector tiles][VT].
It is very similar to [Leaflet.VectorGrid][LVG].

The biggest difference to VectorGrid is the styling.
VectorTileLayer also supports two options min/maxDetailZoom which are
subtly different from VectorGrid's min/maxNativeZoom. Both provide the
possibility to specify a range of zoom levels that offer an optimal
trade-off between detail and size. When using the native variants, tiles
above or below the zoom range are scaled, changing the stroke weight. The
detail settings offer the same trade-off while still rendering the tiles
at the correct zoom levels, meaning stroke weight is visually consistent
across all zoom levels.

Furthermore, VectorTileLayer gives clients full control over the SVG DOM
created for vector tile features. The layer option featureToLayer accepts
a function that can return any graphics for visualising a given feature
while making it easy to fall back to the default implementation.

In contrast to VectorGrid, this class has been designed as much as
possible in terms of Leaflet's public API. This makes it more likely to
continue working with future versions of Leaflet.

Use
---

Loads vector tiles from a URL template like

https://{s}.example.com/tiles/{z}/{x}/{y}.pbf

The URL template also supports the undocumented {-y} option for
»[inverted Y][Y]« if the map's [coordinate reference system][CRS] is finite
(the default).

This pacakge can be used as an ES6 module.

``js
import vectorTileLayer from 'leaflet-vector-tile-layer';

const tileLayer = vectorTileLayer(url, options);
`

The AMD build comes with all dependencies included. If imported as an ES6
module, the dependencies need to be made available to the build system, for
example:

`sh
$ npm install @mapbox/vector-tile pbf
`

See this package's development dependencies for version information.


Layer options
-------------

The main difference to VectorGrid is that VectorTileLayer takes a
different approach to styling. Whereas VectorGrid only supports styling a
previously known set of vector-tile layer names, this class allows
specifying a single style for all layers irrespective of their names. When
specifying a function, it is called with the vector-tile feature, the layer
name and the current zoom level, enabling clients can handle layer names
dynamically or ignore them altogether.

Another feature not supported by VectorGrid is a setStyle() call which
allows changing the style of the entire layer.

For compatibility, support for the vectorTileLayerStyles option and
set/resetFeatureStyle() method is also provided.

VectorTileLayer also supports ordering the layers based on their names
using an option like layers: ["a", "b", "c"].

Another added feature of VectorTileLayer is a getBounds() function.
After the load event, it returns the bounds occupied by the features on
all currently loaded tiles.

VectorTileLayer allows clients to create their own DOM representation for
any given layer. A function provided to the featureToLayer option takes a
vector-tile feature, the layer name, the number of SVG coordinate units per
vector-tile unit and the feature's style object. It should return an object
that eventually delegates to [Leaflet.Layer][LYR] and provides the
following:
- a bbox() function that returns the feature's bounding box in SVG
coordinate units.
- a graphics property that holds the top-level SVG DOM element.
- a setStyle(style) function that takes a style object and applies it
to the generated SVG elements.

VectorTileLayer supports all options provided by [GridLayer][GL].
Additionally, the following options are provided:

`js
const url = 'https://{s}.example.com/tiles/{z}/{x}/{y}.pbf';
const options = {
// A function that will be passed a vector-tile feature, the layer
// name, the number of SVG coordinate units per vector-tile unit
// and the feature's style object to create each feature layer.
featureToLayer, // default undefined

// Options passed to the fetch function when fetching a tile.
fetchOptions, // default undefined

// A function that will be used to decide whether to include a
// feature or not. If specified, it will be passed the vector-tile
// feature, the layer name and the zoom level. The default is to
// include all features.
filter, // default undefined

// A function that receives a list of vector-tile layer names and
// the zoom level and returns the names in the order in which they
// should be rendered, from bottom to top. The default is to render
// all layers as they appear in the tile.
layerOrder, // default undefined

// An array of vector-tile layer names from bottom to top. Layers
// that are missing from this list will not be rendered. The
// default is to render all layers as they appear in the tile.
layers, // default undefined

// Specify zoom range in which tiles are loaded. Tiles will be
// rendered from the same data for Zoom levels outside the range.
minDetailZoom, // default undefined
maxDetailZoom, // default undefined

// Either a single style object for all features on all layers or a
// function that receives the vector-tile feature, the layer name
// and the zoom level and returns the appropriate style options.
style, // default undefined

// This works like the same option for Leaflet.VectorGrid.
// Ignored if style is specified.
vectorTileLayerStyles, // default undefined
};

const layer = vectorTileLayer(url, options);
`

The style can be updated at any time using the setStyle() method.

`js
layer.setStyle({ weight: 3 });
`

All omitted options will be substituted by the default options for
[L.CircleMarker][CM], [L.Polyline][PL] or [L.Polygon][PG], as
appropriate.


Style options
-------------

Style options are interpreted by the individual feature layers. For points,
these are L.CircleMarker options, or the icon property supplies an
L.Icon to determine the appearance. For polylines or polygons, these are
L.Path options. If the options.style property is a function, it will be
passed the vector-tile feature, the layer name and the zoom level as
parameters.

If the style option interactive is true, the created SVG elements will
listen to mouse events.

The style option hidden permits any feature to be hidden. It operates by
setting the SVG attribute visibility to hidden.


Feature layer helpers
---------------------

A few functions are made available to simplify creating custom layers for
individual features:

- defaultFeatureLayer(feature, layerName, pxPerExtent, options). This
function is used if the featureToLayer option is unset. It takes the
vector-tile feature, the layer name, the number of SVG coordinate units
per vector-tile unit and a style object and returns an appropriate layer
object to visualise it.
- featureCircleLayer(feature, layerName, pxPerExtent, options) returns a
layer object that visualises a vector-tile point feature.
- featureIconLayer(feature, layerName, pxPerExtent, options) returns a
layer object that visualises a vector-tile point feature using the
[Leaflet.Icon][ICO] specified by options.icon.
- featurePathLayer(feature, layerName, pxPerExtent, options) returns a
layer object to visualise a vector-tile line or polygon feature.
- featureLayerBase(feature, layerName, pxPerExtent, options) can be used
to create a layer object for a vector-tile feature. It returns an object
that eventually delegates to a [Leaflet.Layer][LYR] instantiated with
the given options. The delegating object must provide:

- a graphics property that holds the top-level SVG DOM element.
- a setStyle(style) method that applies the given style to the
layer's DOM after enhancing it with the feature layer's default
options.

Objects created by this function provide the following:

- An applyOptions(style) function that should be called by a
delegating object once the graphics property is initialised. It
applies the style.className option to it and then invokes
setStyle({}) to allow the delegating object to apply its default
style.
- A bbox() function that returns the feature's bounding box in SVG
coordinate units and is used by VectorTileLayer.getBounds().
- A scalePoint(point) function converts from vector-tile coordinates
to SVG coordinates.

A few functions are provided to simplify the implementation of
setStyle(style) functions:

- applyBasicStyle(element, style) applies the style.interactive and
style.hidden options to the given SVG DOM element.
- applyImageStyle(element, style) applies the height, width and
href proprties from the [Leaflet.Icon][ICO] object in style.icon
to the SVG element.
- applyPathStyle(element, style) applies [Leaflet.Path][PT] style
properties to the SVG element.


Feature layer example
---------------------

The featureToLayer option on VectorTileLayer accepts a function that
can render custom SVG elements depending on feature properties, options,
layer names and zoom level.

Example drawing a thickened transparent overlay for polyline interaction:
`js
import {SVG} from "leaflet";
import {defaultFeatureLayer, featureLayerBase} from "leaflet-vector-tile-layer";

function interactiveLinesLayer(feature, layerName, pxPerExtent, options) {
// Construct a base feature layer.
const self = featureLayerBase(feature, layerName, pxPerExtent, options);

// Compose this feature layer of two sub-layers, one for the visible
// line controlled by options and a second controlled by the path
// options contained in options.interaction. Both will share the same
// path geometry.
self.visibleLine = defaultFeatureLayer(
feature,
layerName,
pxPerExtent,
options
);
self.interactionLine = defaultFeatureLayer(
feature,
layerName,
pxPerExtent,
options.interaction
);

// Place the two layers in an SVG group.
const group = SVG.create("g");
group.appendChild(self.visibleLine.graphics);
group.appendChild(self.interactionLine.graphics);
self.graphics = group;

// Setting of style is delegated to the sub layers.
self.setStyle = function setStyle(style) {
self.visibleLine.setStyle(style);
self.interactionLine.setStyle(style.interaction);
};

// Initial setup of this feature layer.
self.applyOptions(options);

return self;
}

// Example options for the above custom renderer:
const interactiveLineOptions = {
color: "red",
weight: 2,
interaction: {
opacity: 0.0,
weight: 10
}
};
`


Events
------

Events attached to this layer provide access to the vector-tile feature
and the layerName through their layer attribute. For compatibility with
VectorGrid, the feature's properties are also made directly available.


Installing and building
-----------------------

You can install this package using

`sh
$ npm install leaflet-vector-tile-layer
`

It can be built by

`sh
$ npm run build
`


Limitations
-----------

At this time, only SVG rendering and vector tiles in [protobuf`][PBF]
format are supported, but support for other renderers or formats may be
added through options in the future.

[CM]: https://leafletjs.com/reference.html#circlemarker
[CRS]: https://leafletjs.com/reference#crs
[ICO]: https://leafletjs.com/reference.html#icon
[GL]: https://leafletjs.com/reference.html#gridlayer
[LVG]: https://github.com/Leaflet/Leaflet.VectorGrid
[LYR]: https://leafletjs.com/reference.html#layer
[L]: http://leafletjs.com/
[PBF]: https://developers.google.com/protocol-buffers/
[PG]: https://leafletjs.com/reference.html#polygon
[PL]: https://leafletjs.com/reference.html#polyline
[PT]: https://leafletjs.com/reference.html#path
[VT]: https://github.com/mapbox/vector-tile-spec
[Y]: https://github.com/Leaflet/Leaflet/issues/4284