The OpenMapTiles tools for generating TM2Source projects, imposm3 mappings and SQL instructions from OpenMapTiles layers. We encourage other people to use this for their vector tile projects as well since this approach works well for us.
Check out the OpenMapTiles project for a real world example.
You need either just Docker or Python 3 installed on your system. If running without Docker, some of the scripts require graphviz and sqlite3 dependencies.
The easiest is to use docker directly to run this command. You do not need to clone openmaptiles-tools locally, just clone the openmaptiles repo and run from its root.
Note: container scripts can only access files from the given directory and below, e.g. in this example - ${PWD} - current dir.
docker run -it --rm -u $(id -u ${USER}):$(id -g ${USER}) \
-v "${PWD}:/tileset" \
openmaptiles/openmaptiles-tools \
<script-name> <script-parameters>Where the <script-name> could be any of the scripts in the bin/ directory, e.g. generate-imposm3 openmaptiles.yaml.
python3 -m pip install openmaptiles-tools
# OR you can also install the package directly from git
python3 -m pip install git+https://github.com/openmaptiles/openmaptiles-tools
# Some tool require these packages. On Debian/Ubuntu you can install them with
sudo apt install graphviz sqlite3
# Run the script you want, e.g. from the openmaptiles dir:
generate-imposm3 openmaptiles.yaml
# If the script doesn't run, make sure your PATH includes default PIP bin directory.
# On Debian/Ubuntu that would be ~/.local/bin/ (under your home dir).
# Otherwise just run it with ~/.local/bin/generate-imposm3 ...Make sure you have all dependencies from the Usage section above.
# Get OpenMapTiles layer data
git clone https://github.com/openmaptiles/openmaptiles.git
# Get the tools repo
git clone https://github.com/openmaptiles/openmaptiles-tools.git
# Run scripts from the root of the tools repository
cd openmaptiles-tools
# The PYTHONPATH=$PWD allows script to find its modules located in the current dir.
PYTHONPATH=$PWD python3 bin/generate-imposm3 ../openmaptiles/openmaptiles.yamlUse make test to run all of the tests locally. The Makefile will build a docker image with all the code, run all tests, and compare the build result with the files in the testdata/expected dir.
Run make rebuild-expected after you modify the output produced by the generation scripts. This will re-create the expected test results to match the actual ones, and make sure the changes are what you want.
You define a self contained Layer together with SQL files and layer and data source definitions (like an imposm3 mapping file) that you can then reference in a Tileset where you mix and match with other layers.
Take a look or copy a standard layer like building to get started with your own layer. A layer consists out of a Layer definition written in YAML format.
There you specify the layer properties like id, buffer_size and possible Markdown documentation (description and fields).
You can also reference SQL files in schema for writing the necessary queries for your layer or create generalized tables.
We encourage you to have a function per layer which takes the bounding box and zoom level. This makes it easy
to test and reuse.
If your data is based of OSM you can also directly reference a imposm3 mapping file to choose the OSM data you need.
layer:
id: "building"
description: Buildings from OpenStreetMap
buffer_size: 4
datasource:
query: (SELECT geometry FROM layer_building(!bbox!, z(!scale_denominator!))) AS t
fields:
render_height: An approximated height from levels and height of building.
schema:
- ./building.sql
datasources:
- type: imposm3
mapping_file: ./mapping.yamlA Tileset defines which layer will be in your vector tile set (layers)
and metadata used for generating a TM2Source project to actually generate the vector tiles.
tileset:
layers:
- layers/building/building.yaml
- layers/housenumber/housenumber.yaml
- layers/poi/poi.yaml
name: Street Level
description: A tileset showing street level info like building, housenumbers and POIs.
attribution: "OpenStreetMap contributors"
maxzoom: 14
minzoom: 13
center: [-12.2168, 28.6135, 4]
bounds: [-180.0,-85.0511,180.0,85.0511]Uses tileset definition to create a PostgreSQL
prepared or
create function SQL code
to generate an entire vector tile in the Mapbox Vector Tile format with a single getTile(z,x,y) query
using PostGIS MVT support.
Use --help to get all parameters.
NOTE: Current openmaptiles/postgis image (v2.9 and before) has incorrect support for the ST_AsMVT(). Until Postgis is updated, please use sophox/postgis docker image (based on the latest mdillon/postgis:11 base image).
generate-sqltomvt <tileset>
Takes a tileset definition an generates an imposm3 mapping file for importing OSM data.
generate-imposm3 <tileset>
Takes a tileset definition and collects all SQL referenced in the layer definitions.
generate-sql <tileset>
Takes a tileset definition and generates Markdown documentation.
generate-doc <tileset>
dependency: graphviz
Takes a source code from the imposm3 mapping file and the SQL postprocessing code,
and parsing for the etldoc: graphviz based comments, and generate an svg file.
The .dot and the .svg filename prefix is etl_
generate-etlgraph <tileset> <target-directory>
generate-etlgraph layers/landcover/landcover.yaml ./build/devdoc
generate-etlgraph layers/railway/railway.yaml ./build/etlgraph
example:
input command: generate-etlgraph layers/landcover/landcover.yaml
output fies:
layers/landcover/etl_landcover.dotlayers/landcover/etl_landcover.svg
example:
generate-sqlquery layers/landcover/landcover.yaml 14
dependency: sqlite3
example:
generate_metadata ./data/tiles.mbtiles
Takes a tileset definition and generates a TM2Source YAML project file. You need to provide PostgreSQL database connection settings before generating the project.
generate-tm2source <tileset> --host="localhost" --port=5432 --database="osm" --user="osm" --password="osm"