Themepark User’s Manual
You need a config file to give to osm2pgsql. It first has to load the Themepark framework:
local themepark = require('themepark')
All configuration is then done through the themepark
variable.
After that a typical config file might set some global options and then add topics from one or more themes.
See the config
directory for some example config files.
Setting Global Options
Global options can be set with themepark:set_option(OPTION, VALUE)
. The
following options are currently used:
Option | Type | Default | Desciption |
---|---|---|---|
attribution | text | © OpenStreetMap contributors - https://openstreetmap.org/copyright |
Attribution. |
debug | bool | none (disabled) | Set name of debug column. See the Debug Mode section below for details. |
extent | array | none | Extent of your map as array table with (xmin, ymin, xmax, ymax). |
prefix | text | none | Prefix to be used on all table names. |
schema | text | public |
Schema to be used for all tables unless overwritten in add_table() . You must have created this schema in the database with CREATE SCHEMA . |
srid | int | 3857 | SRID to be used for all geometries in all tables. |
tags | text | none (disabled) | Set name of tags column. See the Debug Mode section below for details. |
tileset | text | osm |
Name of vector tiles tileset. |
unique_id | text | none (disabled) | Add column of this name for unique autogenerated ID and matching index to all tables. Needed for some software. |
The attribution
, extent
, and tileset
settings are used by the tileserver
plugins only.
Adding Topics
Add any topics you want to use in your map using the
themepark:add_topic('THEME/TOPIC', OPTIONS)
command. In most cases there
are no OPTIONS, but if the topic has some configuration options, you can set
them
Example: themepark:add_topic('shortbread_v1/water')
(Basically this will include the file themes/THEME/topics/TOPIC.lua
. If it
is the first time the THEME
is used, it will also initialize that theme.)
For most themes/topics, the order does not matter, but some topics need to come before others. Read the documentation for each used theme for the details.
Name Handling
There are special topics in the core
them which allow you to set the policy
used for names. In the simplest case you just want to have a name
column
in all tables based on the name
tag. This is done with:
themepark:add_topic('core/name-single', { column = 'name' })
Or you can have several names columns. In this case the name
, name:de
, and
name:en
tags will end up in the columns name
, name_de
, and name_en
.
Themepark will automatically relace the colons with underscores (_
) for
easier use in the database.
themepark:add_topic('core/name-list', { keys = {'name', 'name:de', 'name:en'} })
With the name-with-fallback
topic, you can configure this even further.
The columns will be filled based on the first tag in the list that’s not empty:
themepark:add_topic('core/name-with-fallback', {
keys = {
name = { 'name', 'name:en', 'name:de' },
name_de = { 'name:de', 'name', 'name:en' },
name_en = { 'name:en', 'name', 'name:de' },
}
})
Note that themes need to have support for the naming topics, because only they know which tables should get a name at all.
Using Plugins
Themepark has plugins which can be used to create config files for tileservers etc.
Call themepark:plugin(PLUGIN):write_config(...)
to create a config file. Note
that those autogenerated config files are probably not perfect. But they are a
good starting point for some tweaking.
Currently supported are the T-Rex and Tilekiln tile servers and you can generate Taginfo project files.
Plugin | For | Usage |
---|---|---|
t-rex | T-Rex tileserver | Call themepark:plugin('t-rex'):write_config(FILENAME.toml) . You need the Lua toml module installed. Usually this is done with luarocks install toml . |
tilekiln | Tilekiln tileserver | Call themepark:plugin('tilekiln'):write_config(DIR) . The directory must exist. For this to work you need the Lua lyaml module installed. Usually this is done with luarocks install lyaml . Or install the lua-yaml debian package. |
taginfo | Taginfo Projects | Call themepark:plugin('taginfo'):write_config(FILENAME.json) to generate a skeleton of a projects file for taginfo. |
Debug Mode
Set themepark.debug = true
to enable debug mode at the beginning of your
config file. When running osm2pgsql, you’ll get some more output telling you
what Themepark is doing. It will also enable extra debugging columns on your
database tables as follows:
Tags: If you set a tags column name with themepark:set_option('tags',
NAME)
and debug mode is enabled you’ll get an extra JSONB column on all your
tables with the name NAME
with all the tags of any object you are writing
into this table.
Debug: If you set a debug column name with themepark:set_option('debug',
NAME)
and debug mode is enabled you’ll get an extra JSONB column on all your
tables with the name NAME
. Themes can put any data they want into that
column, this could for instance be some data generated from the OSM tags.
Themes must have support for these debug columns and not all themes do!
Running osm2pgsql
To use any Themepark config you need to set the LUA_PATH
environment variable
so that osm2pgsql knows where to find the Themepark framework. Set it with
something like
export LUA_PATH="REPO_DIR/lua/?.lua;;"
(Replace REPO_DIR
with the directory where you checked out the
osm2pgsql-themepark repository).
After you have set up the config file, you can run osm2pgsql as usual with something like
osm2pgsql -d DATABASE -O flex -S CONFIG.lua OSM-DATA-FILE