https://github.com/mapbox/vtcomposite
vtzero-based vector tile compositor (supporting overzooming)
https://github.com/mapbox/vtcomposite
Last synced: 5 months ago
JSON representation
vtzero-based vector tile compositor (supporting overzooming)
- Host: GitHub
- URL: https://github.com/mapbox/vtcomposite
- Owner: mapbox
- License: cc0-1.0
- Created: 2018-04-25T16:11:45.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T12:13:58.000Z (8 months ago)
- Last Synced: 2024-12-14T08:04:00.190Z (6 months ago)
- Language: JavaScript
- Size: 1.17 MB
- Stars: 38
- Watchers: 97
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# vtcomposite
[](https://travis-ci.com/mapbox/vtcomposite)
[](https://codecov.io/gh/mapbox/vtcomposite)
[](https://github.com/mapbox/node-cpp-skel)
```shell
npm install @mapbox/vtcomposite --save
```
vtcomposite is a tool to combine multiple [vector tiles](https://github.com/mapbox/vector-tile-spec) 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](/TUTORIAL.md). This module is a [Node.js Addon](https://nodejs.org/api/addons.html) 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
```js
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>** 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>** 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>** 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
```js
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
```js
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](https://github.com/mapbox/vtcomposite/blob/master/LICENSE.md)
- [CONTRIBUTING](https://github.com/mapbox/vtcomposite/blob/master/CONTRIBUTING.md)
- [CODE OF CONDUCT](https://github.com/mapbox/vtcomposite/blob/master/CODE_OF_CONDUCT.md)
This project is based off the node-cpp-skel framework, which is licensed under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). [](https://github.com/mapbox/node-cpp-skel)