vtcomposite

npm install @mapbox/vtcomposite --save

vtcomposite is a tool to combine multiple vector tiles into a single tile. It allows you to ...

• Merge tiles. Combine 2 or more tiles into a single tile at the same zoom level.
• Overzoom tiles. For displaying data at a higher zoom level than that the tile's original zoom level.
• Clip tiles. Clips the extraneous buffer of a tile that’s been overzoomed to match a tile's extent or to retain data beyond the extent.
• Drop layers. Remove any layers from a tile.
• Localize. Modify localization-related features and properties such as language and worldview properties.

You can learn more about compositing in TUTORIAL.md. This module is a Node.js Addon and will install prebuilt binaries for your version of Node.js and computer architecture. Uncommon setups will build from source when installed via NPM.

Usage

composite

Combine multiple vector tiles from different zooms into a single tile at one zoom. This function will overzoom geometries to match the extent of the destination zoom.

Parameters

• tiles Array(Object) an array of tile objects
  • buffer Buffer a vector tile buffer, gzip compressed or not
  • z Number z value of the input tile buffer
  • x Number x value of the input tile buffer
  • y Number y value of the input tile buffer
  • layers Array an array of layer names to keep in the final tile. An empty array is invalid. (optional, default keep all layers)
• zxy Object the output tile zxy location, used to determine if the incoming tiles need to overzoom their data
  • z Number z value of the output tile buffer
  • x Number x value of the output tile buffer
  • y Number y value of the output tile buffer
• options Object
  • options.compress Boolean a boolean value indicating whether or not to return a compressed buffer. Default is to return a uncompressed buffer. (optional, default false)
  • options.buffer_size Number the buffer size of a tile, indicating the tile extent that should be composited and/or clipped. Default is buffer_size=0. (optional, default 0)
• callback Function callback function that returns err, and buffer parameters

Example

const { composite } = require('@mapbox/vtcomposite');
const fs = require('fs');

const tiles = [
  { buffer: fs.readFileSync('./path/to/tile.mvt'), z: 15, x: 5238, y: 12666 },
  { buffer: fs.readFileSync('./path/to/tile.mvt'), z: 15, x: 5238, y: 12666, layers: ['building'] }
];

const zxy = { z: 5, x: 5, y: 12 };

const options = {
  compress: true,
  buffer_size: 0
};

composite(tiles, zxy, options, function(err, result) {
  if (err) throw err;
  console.log(result); // tile buffer
});

localize

A filtering function for modifying a tile's features and properties to support localized languages and worldviews. This function requires the input vector tiles to match a specific schema for language translation and worldviews.

Parameters

• params Object
  • params.buffer Buffer a vector tile buffer, gzip compressed or not.
  • params.compress Boolean a boolean value indicating whether or not to return a compressed buffer.
    • Default value: false (i.e. return an uncompressed buffer).
  • params.hidden_prefix String prefix for any additional properties that will be used to override non-prefixed properties.
    • Default value: _mbx_.
    • Any property that starts with this prefix are considered hidden properties and thus will be dropped.
  • params.languages Array<Optional> array of IETF BCP 47 language codes or the string local, used to search for matching translations available in a feature's properties.
    • Optional parameter.
    • All language-related properties must match the following format: {hidden_prefix}{language_property}_{language}.
    • Default properties are _mbx_name_{language}; for example, the _mbx_name_jp property contains the Japanese translation for the value in name.
    • local language code represents "{language_property} is in a script that is not in the params.omit_scripts list".
      • The script of {language_property}, if available, must be stored in the {language_property}_script property.
      • If {language_property}_script not in the params.omit_scripts list, use {language_property} when searching for matching translation.
      • If {language_property}_script is in the params.omit_scripts list, skip {language_property} when searching for matching translation.
    • all language code returns {language_property}, {language_property}_local and all possible language properties that have different values than {language_property}
  • params.omit_scripts Array<Optional> array of scripts to skip local language code.
  • params.language_property String the primary property in features that identifies the feature in a language.
    • Default value: name.
    • This values is used to search for additional translations that match the following format {language_property}_{language}.
  • params.worldviews Array<Optional> array of ISO 3166-1 alpha-2 country codes used to filter out features of different worldviews.
    • Optional parameter.
    • For now, only the first item in the array will be processed; the rest are discarded (TODO in the future: expand support for more than one worldviews).
    • When there is only the single value ALL, all the different worldviews are returned.
  • params.worldview_property String the name of the property that specifies in which worldview a feature belongs.
    • Default value: worldview.
    • The vector tile encoded property must contain a single ISO 3166-1 alpha-2 country code or a comma-separated string of country codes that define which worldviews the feature represents (for example: JP, IN,RU,US).
  • params.worldview_default String default worldview to assume when params.worldviews is not provided.
    • Default value: US.
  • params.class_property String the name of the property that specifies the class category of a feature.
    • Default value: class.
  • callback Function callback function that returns err and buffer parameters

The existence of the parameters params.languages and params.worldviews determines the type of features that will be returned:

• Non-localized feature: when params.languages and params.worldviews both do not exist.

  • No new language property.
  • The property {language_property} retains its original value.
  • Properties like {language_property}_{language} are kept.
  • Properties like {hidden_prefix}{language_property}_{language} are dropped.
  • All features with {worldview_property} are kept.
  • All features with {hidden_prefix}{worldview_property} are dropped except for those that have the value all.
  • Property {class_property} retains its original value.
  • Property {hidden_prefix}{class_property} is dropped.

• Localized feature: when either params.languages or params.worldviews exists.

  • A new {language_property}_local property is created to keep the original value of {language_property}
  • The value of {language_property} is replaced with the first translation found by looping through params.languages.
    • First searches for {language_property}_{language} and then {hidden_prefix}{language_property}_{language} before moving on to the next language in params.languages.
  • Properties like {language_property}_{language} are dropped.
  • Properties like {hidden_prefix}{language_property}_{language} are dropped.
  • All features with {worldview_property} are dropped except for those that have the value all.
  • Features with {hidden_prefix}{worldview_property} are kept if their {hidden_prefix}{worldview_property} value is
    • all, or
    • a comma-separated list that contains the first item of parmas.worldviews, in which a property {worldview_property} is created from that one single worldview country code and the property {hidden_prefix}{worldview_property} is dropped.
  • If {hidden_prefix}{class_property} exists,
    • Property {class_property} is replaced with the value in {hidden_prefix}{class_property}.
    • Property {hidden_prefix}{class_property} is dropped.

Example

Example 1: a tile of non-localized features

const { localize } = require('@mapbox/vtcomposite');

const params = {
  // REQUIRED
  buffer: require('fs').readFileSync('./path/to/tile.mvt'),
};

localize(params, function(err, result) {
  if (err) throw err;
  console.log(result); // tile buffer
});

Example 2: a tile of localized features in Japan worldview

const { localize } = require('@mapbox/vtcomposite');

const params = {
  // REQUIRED
  buffer: require('fs').readFileSync('./path/to/tile.mvt'),
  // OPTIONAL (defaults)
  languages: ['ja']
  worldviews: ['JP'],
  compress: true
};

localize(params, function(err, result) {
  if (err) throw err;
  console.log(result); // tile buffer
});

Contributing & License

• LICENSE
• CONTRIBUTING
• CODE OF CONDUCT

This project is based off the node-cpp-skel framework, which is licensed under CC0.