Skip to main content

Themepark Users 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 - 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