@mapbox/vtshaver

Vector Tile Shaver

Style-optimized vector tiles. The shaver takes a Mapbox Vector Tile and a Mapbox GL Style and removes layers, features, and properties in the tile that are not used by the style to reduce the size of the tile. Read the feature release blog post and the api-documentation for more info.

Installation

npm install @mapbox/vtshaver

If you want to install locally you can also do:

git clone https://github.com/mapbox/vtshaver
cd vtshaver
npm install

API Usage

• styleToFilters
• Filters
• shave

CLI

Shaver provides 2 command line tools:

vtshave

vtshave [args]

  --tile:    required: path to the input vector tile
  --style:   required: path to a gl style to use to shave
  --zoom:    required: the zoom level
  --maxzoom: optional: the maxzoom of a tileset relevant to the tile buffer being shaved
  --out:     optional: pass a path if you want the shaved tile to be saved

Will output a size comparison of how many bytes were shaved off the tile.

Example:

  vtshave --tile tile.mvt --zoom 0 --maxzoom 16 --style style.json

vtshaver-filters

vtshaver-filters [args]

  --style:   required: path to a gl style to parse
  --sources: optional: list of one or more sources (comma separated) to display in the output (default is all sources)
  --pretty:  optional: whether to pretty print the output (default false). Pass '--pretty' to indent the JSON.

Will output a json object describing each of the source-layers and their parsed metadata to be used for shaving.

Example:

  vtshaver-filters --style style.json > meta.json

Develop

Build binaries

make

For Mac M1 users, there are a couple of extra steps before building

• Comment out linking instructions in your local binding.gyp as follows

#  'make_global_settings': [
#    ['CXX', '<(module_root_dir)/mason_packages/.link/bin/clang++'],
#    ['CC', '<(module_root_dir)/mason_packages/.link/bin/clang'],
#    ['LINK', '<(module_root_dir)/mason_packages/.link/bin/clang++'],
#    ['AR', '<(module_root_dir)/mason_packages/.link/bin/llvm-ar'],
#    ['NM', '<(module_root_dir)/mason_packages/.link/bin/llvm-nm']
#  ],

• Switch to x86_64 processor since arm64 has unresolved issues with the latest mbgl-core library

$ arch --x86_64 zsh

Test

make test

Run bench test

node bench/bench-batch.js --iterations 50 --concurrency 10

Optionally combine with the time command

Docs

Documentation is generated using Documentation.js --polyglot mode. Generate docs in API.md by running:

make docs

NOTE: we are pinned to documentation@4.0.0 because 5.x removed C++ support: https://github.com/documentationjs/documentation/blob/master/CHANGELOG.md#500-2017-07-27