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 several tile servers and you can generate Taginfo project files.

Plugin	For	Usage
bbox	BBOX Server	Call `themepark:plugin('bbox'):write_config(FILENAME.toml)`.
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

To enable debug mode, set themepark.debug = true at the beginning of your config file or set the environment variable THEMEPARK_DEBUG.

In debug mode you’ll get some more output telling you what Themepark is doing when running osm2pgsql. 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

Using Themepark Functions without Theme

It is possible to use the Themepark functions for creating tables or adding processing functions directly in your config file, without a theme. This can be useful, for instance, to modify some tags before the processing functions of a theme are run. See the Author’s Manual for available functions.