leaflet-vector-tile-layer/README.md

Leaflet layer for vector tiles

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](#style-options).
`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 `<image>` element.
  - `applyPathStyle(element, style)` applies [`Leaflet.Path`][PT] style
    properties to the SVG `<path>` 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