MapLibre/Mapbox vector tiles (MVT) reader/writer library for Swift, together with a powerful tool for working with vector tiles and GeoJSONs from the command line.
- Load and write MapLibre/Mapbox Vector Tiles from/to disk, data objects or URLs (also handles gzipped input).
- Export options: Zipped, buffered (in pixels or extents), simplified (in meters or extents).
- Can dump a tile as a GeoJSON object.
- Supported projections: EPSG:4326, EPSG:3857 or none (uses the tile's coordinate space).
- Fast search (supports indexing), either within a bounding box or with center and radius.
- Extract selected layers into a new tile.
- Merge tiles into one.
- Can extract some infos from tiles like feature count, etc.
- Powerful command line tool (via Homebrew, documentation below) for working with vector tiles and GeoJSON files.
This package requires Swift 5.10 or higher (at least Xcode 14), and compiles on iOS (>= iOS 13), macOS (>= macOS 13), tvOS (>= tvOS 13), watchOS (>= watchOS 6) as well as Linux.
dependencies: [
.package(url: "https://github.com/Outdooractive/mvt-tools", from: "1.8.0"),
],
targets: [
.target(name: "MyTarget", dependencies: [
.product(name: "MVTTools", package: "mvt-tools"),
]),
]This package uses the gis-tools library, and is being used by the mvt-postgis library, please have a look at them as well.
See the API documentation (via Swift Package Index).
import MVTTools
// Load
let mvtData = Data(contentsOf: URL(fileURLWithPath: "14_8716_8015.vector.mvt"))!
let tile = VectorTile(data: mvtData, x: 8716, y: 8015, z: 14, indexed: .hilbert)!
print(tile.isIndexed)
print(tile.layerNames.sorted())
let tileAsGeoJsonData: Data? = tile.toGeoJson(prettyPrinted: true)
...
let result = tile.query(at: Coordinate3D(latitude: 3.870163, longitude: 11.518585), tolerance: 100.0)
...import MVTTools
var tile = VectorTile(x: 8716, y: 8015, z: 14)!
var feature = Feature(Point(Coordinate3D(latitude: 3.870163, longitude: 11.518585)))
feature.properties = [
"test": 1,
"test2": 5.567,
"test3": [1, 2, 3],
"test4": [
"sub1": 1,
"sub2": 2
]
]
tile.setFeatures([feature], for: "test")
// Also have a look at ``VectorTile.ExportOptions``
let tileData = tile.data()
...On macOS you can use a Swift Playground to inspect the MVTTools API such as layerNames and projection.
- Load tile using MVTTools
- Inspect the properties of the
VectorTile
You can install the command line tool mvt either
- with homebrew:
brew install Outdooractive/homebrew-tap/mvt-tools - or locally to
/usr/local/binwith./install_mvt.sh
mvt works with vector tiles or GeoJSON files from local disk or served from a web server.
GeoJSONs can contain a layer name in their Feature properties (default name is vt_layer), and any resulting GeoJSON will automatically include this property.
This can be controlled with the options --property-name (or -P), --disable-input-layer-property (or -Di) and --disable-output-layer-property (or -Do).
Some commands allow limiting the result to certain layers with --layer (or -l), which can be repeated for as many layers as necessary.
# mvt -h
OVERVIEW: A utility for inspecting and working with vector tiles (MVT) and GeoJSON files.
A x/y/z tile coordinate is needed for encoding/decoding vector tiles (MVT).
This tile coordinate can be extracted from the file path/URL if it's either in the form '/z/x/y' or 'z_x_y'.
Tile coordinates are not necessary for GeoJSON input files.
Examples:
- Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt
- https://demotiles.maplibre.org/tiles/2/2/1.pbf
USAGE: mvt <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
dump (default) Print the input file (mvt or GeoJSON) as pretty-printed GeoJSON to the console
info Print information about the input file (mvt or GeoJSON)
query Query the features in the input file (mvt or GeoJSON)
merge Merge any number of vector tiles or GeoJSONs
import Import some GeoJSONs into a vector tile
export Export a vector tile as GeoJSON to a file
See 'mvt help <subcommand>' for detailed help.Print a vector tile or GeoJSON file as pretty-printed GeoJSON.
mvt dump Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt
{
"type" : "FeatureCollection",
"features" : [
{
"bbox" : [
11.516327261924731,
3.8807821163834175,
11.516590118408191,
3.8815421167424793
],
"properties" : {
"oneway" : 1,
"vt_layer" : "tunnel",
"class" : "motorway"
},
"geometry" : {
"coordinates" : [
...
],
"type" : "LineString"
},
"id" : 1,
"type" : "Feature"
},
...
}Print some informations about vector tiles/GeoJSONs:
- The number of features, points, linestrings, polygons per layer
- The properties for each layer
- Counts of specific properties
Example 1: Print information about the MVTTools test vector tile at zoom 14, at Yaoundé, Cameroon.
mvt info Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt
Name | Features | Points | LineStrings | Polygons | Unknown | Version
--------------------+----------+--------+-------------+----------+---------+--------
area_label | 55 | 55 | 0 | 0 | 0 | 2
barrier_line | 4219 | 0 | 4219 | 0 | 0 | 2
bridge | 14 | 0 | 14 | 0 | 0 | 2
building | 5414 | 0 | 0 | 5414 | 0 | 2
building_label | 413 | 413 | 0 | 0 | 0 | 2
...
road | 502 | 1 | 497 | 4 | 0 | 2
road_label | 309 | 0 | 309 | 0 | 0 | 2Example 2: Inspect a MapLibre vector tile at zoom 2, with an extent showing Norway to India.
mvt info https://demotiles.maplibre.org/tiles/2/2/1.pbf
Name | Features | Points | LineStrings | Polygons | Unknown | Version
-----------+----------+--------+-------------+----------+---------+--------
centroids | 104 | 104 | 0 | 0 | 0 | 2
countries | 113 | 0 | 0 | 113 | 0 | 2
geolines | 4 | 0 | 4 | 0 | 0 | 2Example 3: Print information about the properties for each layer.
mvt info Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt
Name | area | class | group | layer | ldir | len | name | name_de | name_en | name_es | name_fr | network | oneway | ref | reflen | scalerank | type
--------------------+------+-------+-------+-------+------+-----+------+---------+---------+---------+---------+---------+--------+-----+--------+-----------+-----
airport_label | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
area_label | 55 | 55 | 0 | 0 | 0 | 0 | 55 | 55 | 55 | 55 | 55 | 0 | 0 | 0 | 0 | 0 | 0
barrier_line | 0 | 4219 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
bridge | 0 | 14 | 0 | 13 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 14 | 0 | 0 | 0 | 0
...Example 4: Print information about specific properties.
mvt info -p class Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt
Name | cemetery | driveway | fence | hedge | hospital | industrial | main | major_rail | mini_roundabout | minor_rail | motorway | park | parking | path | pitch | rail | school | service | street | street_limited | wetland | wood
-------+----------+----------+-------+-------+----------+------------+------+------------+-----------------+------------+----------+------+---------+------+-------+------+--------+---------+--------+----------------+---------+-----
class | 4 | 36 | 3895 | 324 | 9 | 2 | 113 | 21 | 1 | 13 | 30 | 95 | 59 | 46 | 21 | 2 | 59 | 187 | 376 | 4 | 4 | 12Example 1: Query a vector tile or GeoJSON file with a search term.
mvt query Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt "École"
{
"features" : [
{
"bbox" : [
11.537318229675295,
3.8732409490233337,
11.537318229675295,
3.8732409490233337
],
"geometry" : {
"coordinates" : [
11.537318229675295,
3.8732409490233337
],
"type" : "Point"
},
"id" : 51,
"layer" : "building_label",
"properties" : {
"area" : 173.97920227050781,
"name" : "École Maternelle",
"name_de" : "École Maternelle",
"name_en" : "École Maternelle",
"name_es" : "École Maternelle",
"name_fr" : "École Maternelle"
},
"type" : "Feature"
},
...
}Example 2: Query a tile with latitude,longitude,radius.
mvt query Tests/MVTToolsTests/TestData/14_8716_8015.geojson "3.87324,11.53731,1000"
{
"features" : [
{
"bbox" : [
11.529276967048643,
3.8803432426251487,
11.530832648277283,
3.8823074685255259
],
"geometry" : {
"coordinates" : [
...
],
"type" : "LineString"
},
"id" : 48,
"layer" : "road",
"properties" : {
"class" : "driveway",
"oneway" : 0
},
"type" : "Feature"
},
...
}Example 3: Query Feature properties in a tile.
mvt query -p Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvt ".area > 40000 and .class == 'hospital'"
{
"features" : [
{
"bbox" : [
11.510410308837876,
3.871287406415171,
11.510410308837876,
3.871287406415171
],
"geometry" : {
"coordinates" : [
11.510410308837876,
3.871287406415171
],
"type" : "Point"
},
"id" : 2,
"properties" : {
"area" : 48364.9375,
"class" : "hospital",
"name" : "Hopital Central de Yaoundé",
"name_de" : "Hopital Central de Yaoundé",
"name_en" : "Hopital Central de Yaoundé",
"name_es" : "Hopital Central de Yaoundé",
"name_fr" : "Hopital Central de Yaoundé",
"vt_layer" : "area_label"
},
"type" : "Feature"
}
],
"type" : "FeatureCollection"
}The query language is very loosely modeled after the jq query language.
The output will contain all features where the query returns true.
Here is an overview. Example:
"properties": {
"foo": {"bar": 1},
"some": ["a", "b"],
"value": 1,
"string": "Some name"
}
Values are retrieved by putting a . in front of the property name. The property name must be quoted
if it is a number or contains non-alphabetic characters. Elements in arrays can be
accessed either by simply using the array index after the dot, or by wrapping it in brackets.
.foo // true, property "foo" exists
.foo.bar // true, property "foo" is a dictionary containing "bar"
."foo"."bar" // true, same as above but quoted
.'foo'.'bar' // true, same as above but quoted
.foo.x // false, "foo" doesn't contain "x"
."foo.bar" // false, property "foo.bar" doesn't exist
.foo.[0] // false, "foo" is not an array
.some.[0] // true, "some" is an array and has an element at index "0"
.some.0 // true, same as above but without brackets
.some."0" // false, "0" is a string key but "some" is not a dictionary
Comparisons can be expressed like this:
.value == "bar" // false
.value == 1 // true
.value != 1 // false
.value > 1 // false
.value >= 1 // true
.value < 1 // false
.value <= 1 // true
.string =~ /[Ss]ome/ // true
.string =~ /some/ // false
.string =~ /some/i // true, case insensitive regexp
.string =~ "^Some" // true, can also use quotes
Conditions (evaluated left to right):
.foo.bar == 1 and .value == 1 // true
.foo == 1 or .bar == 2 // false
.foo == 1 or .value == 1 // true
.foo not // false, true if foo does not exist
.foo and .bar not // true, foo and bar don't exist together
.foo or .bar not // false, true if neither foo nor bar exist
.foo.bar not // false, true if "bar" in dictionary "foo" doesn't exist
Other:
near(latitude,longitude,tolerance) // true if the feature is within "tolerance" around the coordinate
Some complete examples:
// Can use single quotes for strings
mvt query -p 14_8716_8015.vector.mvt ".area > 20000 and .class == 'hospital'"
// ... or double quotes, but they must be escaped
mvt query -p 14_8716_8015.vector.mvt ".area > 20000 and .class == \"hospital\""
// No need to quote the query if it doesn't conflict with your shell
// Print all features that have an "area" property
mvt query -p 14_8716_8015.vector.mvt .area
// Features which don't have "area" and "name" properties
mvt query -p 14_8716_8015.vector.mvt .area and .name not
// Case insensitive regular expression
vt query -p 14_8716_8015.vector.mvt ".name =~ /hopital/i"
// Case sensitive regular expression
mvt query -p 14_8716_8015.vector.mvt ".name =~ /Recherches?/"
// Can also use quotes instead of slashes
mvt query -p 14_8716_8015.vector.mvt ".name =~ 'Recherches?'"
// Features around a coordinate
mvt query -p 14_8716_8015.vector.mvt "near(3.87324,11.53731,1000)"
// With other conditions
mvt query -p 14_8716_8015.vector.mvt ".name =~ /^lac/i and near(3.87324,11.53731,10000)"
Merge two or more vector tiles or GeoJSON files in any combination.
# All vector tiles:
mvt merge --output merged.mvt path/to/first.mvt path/to/second.mvt
# All GeoJSON files:
mvt merge --output merged.geojson path/to/first.geojson path/to/second.geojson
# Merge GeoJSON files into a vector tile:
mvt merge --output merged.mvt --output-format mvt path/to/first.geojson path/to/second.geojson
# Merge vector tiles into a GeoJSOn file:
mvt merge --output merged.geojson --output-format geojson path/to/first.mvt path/to/second.mvtWrite a vector tile as GeoJSON to a file.
mvt export --output dumped.geojson --pretty-print Tests/MVTToolsTests/TestData/14_8716_8015.vector.mvtCreate a vector tile from GeoJSON.
mvt import new.mvt -x 8716 -y 8015 -z 14 Tests/MVTToolsTests/TestData/14_8716_8015.geojsonPlease create an issue or open a pull request.
brew install protobuf swift-protobuf swiftlint
-
Documentation (!)
-
Tests
-
Locking (when updating/deleting features, indexing)
-
Query option: within/intersects
-
Libraries
-
Vector tiles
-
Sample data for testing:
-
Other code for inspiration:
MIT
Thomas Rasch, Outdooractive