From OpenStreetMap Wiki
Jump to: navigation, search

libosmscout ( offers applications simple, high-level interfaces to offline rendering and routing functionalities based on OpenStreetMap data, written by Tim Teulings. For details see a copy of one of his postings to the osm routing mailing list below.

It does so by preprocessing .osm /.pbf data files and generating binary data and index files for fast access.

To get an impression of the rendering quality and routing functionality have a look at the rather old screenshots and demo video or look at the blog of the main author for old acitivity and screenshots. Tim Teulings had also a talk at the State of the Map Europe 2014 that you can watch here.

The source code is licenced LGPL and is hosted at

and (in parallel?) on at

Note that libosmscout code is still in flux, this web page tries to be up to date. If you have the feeling, that the documentation does not match, please try to contact the author and even better the libosmscout mailinglist.

Software that uses libosmscout

  • OSMScout (see entry on and its github-repository) is an app for Ubuntu Touch devices that offers offline map display, navigation etc.
  • OSMScout for Sailfish OS (github project) - offline maps for Sailfish OS from Jolla.



This tool grabs some osm.osm/.pbf XML file and converts it to a special binary format containing the geometries.


Allows to dump objects with all their attributes from the database for debugging purposes.


This library can be used by application programmers to access the data in the aforementioned binary file, created by the importer.


This library holds the code to import *.osm and *.osm.pbf files. It is currently only used by the Import application.


libosmscout-map does all the map drawing using libosmscout as basis. libosmscout just defines an interface for the database that libosmscout-map uses, so in priciple even the local file database would be exchangeable. It does not contain any actual backend, the individual backends have their own libraries.


Cairo map drawing backend. This is the reference backend.


Qt map drawing backend. Feature complete.


Agg map drawing backend. Misses code for drawing external images, patterns, plate labels and symbols.


SVG map drawing backend. Misses code for drawing external images, patterns, plate labels and symbols. No text support.


Map drawing backend for iOS and OS X.


A simple map application using the Qt toolkit by Trolltech/Nokia


Some example code showcasing the usage of libosmscout. These are:

  • DrawMapCairo, DrawMapQt, DrawMapAgg, DrawMapSVG: Simple console applications to draw a map using the named backend.
  • LocationLookup: Demos to lookup of addresses.
  • Routing: Simple console application to show how to do routing.
  • Tiler: Shows how to render tiles (fast).
  • LookupPOI: Shows how to lookup POIs of certains types in the local region.


An example how to use Qt to render a small area to a .png image. Common usage:

DrawMapQt <map directory> <style-file> <width> <height> <lon> <lat> <zoom> <output>

Example usage:

src/DrawMapQt ../maps/nordrhein-westfalen ../stylesheets/standard.oss 640 480 7.13 50.69 10000 test.png

Prerequisites (incomplete)

To get a successful full build you have to meet the dependencies of all components. The following section lists the dependencies per component.

Component specific dependencies


  • Qt5


sudo apt-get install qtbase5-dev libqt5gui5


  • agg
  • freetype


sudo apt-get install pkg-config libagg-dev libfreetype6-dev


sudo apt-get install freeglut3 freeglut3-dev binutils-gold


  • pangoft2


This is a short manual describing how to get libosmscout, libillumination and TravelJinni running. Windows guide is available at User:Shrddr/libosmscout.

Building the library


Debian, Ubuntu:

# build dependencies:
sudo apt-get install autoconf automake autotools-dev build-essential cmake doxygen freeglut3 freeglut3-dev gcc git libagg-dev libcairo2-dev libfreetype6-dev libmarisa-dev libpangocairo-1.0-0 libpango1.0-dev libprotobuf-dev libqt5svg5-dev libtool libxml2-dev make pkg-config protobuf-compiler qtdeclarative5-dev qtlocation5-dev qt5-default subversion
# runtime dependencies for OSMScout2 and StyleEditor
sudo apt-get install qml-module-qtquick-dialogs qml-module-qtquick-controls  
qml-module-qtquick-layouts qml-module-qtquick-window2 qml-module-
qtgraphicaleffects qml-module-qtpositioning

Moblin, Fedora:

sudo yum install git subversion gcc-c++ make autoconf automake libtool libxml2-devel cairo-devel libXext-devel


libosmscout currently support two build toolchains:

  • Autogen + qmake for Qt libraries + make
  • cmake + make

Choose of build toolchain depends on target platform and user preferences.

git clone
cd libosmscout
mkdir -p build
cd build
cmake ..
make -j `nproc`

The current version has a global makefile that triggers all local make files. If you want to trigger a complete Unix-toolchain based build (make, autotools, libtool, pkg-config) assure that you have extended your pkg-config lookup directories pointing to all libosmscout* top level directories (extends environment variable PKG_CONFIG_PATH) and that you have extended your library search path to include src/.libs for all libosmscout* directories (extend environment variable LD_LIBRARY_PATH). There is now a script in the root directory, that can be sourced for setting LD_LIBRARY_PATH and PKG_CONFIG_PATH.

After that simply call

make full

in the main directory. This should build everything (that is buildable because dependencies are fulfilled). If parts cannot be build because dependencies are not available, these should be skipped.

As an alternative you can use below bash script as an example how to trigger a (partial) build.


# download libosmscout libraries, Import, OSMScout2
git clone
cd libosmscout

# compile libosmscout
# yes, once again:
cd libosmscout 
./ && ./configure && make
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/src/.libs
cd ..

# compile libosmscoutimport
cd libosmscout-import
./ && ./configure && make
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/src/.libs
cd ..

# compile libosmscoutmap
cd libosmscout-map
./ && ./configure && make
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/src/.libs
cd ..

# compile libosmscoutmap-cairo
cd libosmscout-map-cairo
./ && ./configure && make
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)/src/.libs
cd ..

# compile OSMScout2
cd OSMScout2/
qmake && make
cd ..

# compile the Import tool
cd Import/
./ && ./configure && make
cd ..

cd ..

Converting OSM Data

  • Grab the .osm/.pbf file of your preferred area. Avoid to use a full Planet file.
  • Use the Import tool (remembered the path?) to process the data

You can place you *.osm/.pbf file anywhere you like, but the standard installation would be to place the files into the maps sub directory.


# download a .pbf file
wget -c

mkdir niedersachsen
# run the Import tool. Pass reduced sizes to decrease memory requirements:
/path/to/libosmscout/Import/src/Import --typefile ../stylesheets/map.ost --destinationDirectory niedersachsen niedersachsen.osm.pbf

This will generate several binary data files (*.dat) and index files (*.idx). You may delete the niedersachsen.osm.pbf file now.

There is a shell script named in the maps sub directory that does simplify the import call:

./ niedersachsen.osm.pbf

It will automatically create a sub directory for the database, will automatically add the --typefile and --destinationDirectory arguments and will dump the import command line output to a niedersachsen.txt file, too.


You should run the binary file debug/OSMScout2. The command line for the using the map above would be:

debug/OSMScout ../maps/niedersachsen ../stylesheets/standard.oss ../libosmscout/data/icons/14x14/standard/

You may also want to copy the libraries to some library path or simply make the paths permanent:

echo "LD_LIBRARY_PATH=$LD_LIBRARY_PATH" >> ~/.bashrc
echo "export LD_LIBRARY_PATH" >> ~/.bashrc


There are the following configuration files:

  • map.ost (type definitions)
  • standard.oss (style definitions)

You find all configuration files in stylesheets sub directory.

Automatic builds

There are now automatic builds for Linux (Ubuntu) and OS X at Travis CI.


Blog posts

OSM routing, 2010-03-14


I'm still looking for people interested in helping me with further development libosmscout ( The library steadily improves, but more people could simply get more work done faster ;-)

libosmscout is a C++ library, that implements offline map drawing and routing based on OSM data. It does this by import an existing *.osm file and generating a binary, plattform independent file based database and offering an high level API on top of this database.

The main target group of the library are people that are interested in developing applications based on OSM and that do not want to directly access available data using existing online APIs. Such applications of course also include offline navigation software but of course other, more specialized applications are possible.

Recent discussions with interested people however have shown that libosmscout has a much broader target group. Since the library consists of separate components for import, dataaccess, routing and map drawing, other usage senarios are also possible and I'm also looking for people that want to improve libosmscout in that direction:

  • Generating stylable (paper) maps
  • Using it as a small desktop local caching tile server with very light infrastructure requirements.
  • Using it to tests and compare different routing alogrithm (that can share pre- and postprocessing and thus safe the developer the hassle to fiddle around with *.osm file format and generating a good textual routing description).
  • Use the internal data structures and map drawing for online-data API based map drawing
  • Statistical analysis and data test suite

libosmscout currently depends on libxml and libcairo (, but even that could be abstracted ;-)) and thus should work on various platforms.

If you are interested take a look at for further details (and a video) or simply contact me.