From OpenStreetMap Wiki
Jump to: navigation, search

Osmium uses standard C++ and should compile everywhere. It compiles cleanly (without any warnings) with g++ and with LVM/clang.

Osmium is being developed on Ubuntu Linux. It should work without problems on any Linux system. Some libraries might only be available on newer systems. Osmium also works on Mac OSX. Osmium has not been tested on Windows systems, there will probably be problems with some libraries and POSIX functions that are not available on Windows.

Osmium can do a lot of different things and you will not need all those features in all of your programs. Thats why Osmium knows about several compilation options that make sure only the stuff you need is included or linked into your program.

Note that the Osmium API documentation shows all functions regardless of whether they are only available if any of the options described below is set.

Also see Osmium/Quick Start.

Large Files

When working with OSM data you often have very large files with several gigabytes. This can lead to problems on 32bit systems. Use the options -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 for the compiler to make sure that large files work.

Include What You Need

To use Osmium in your code you just have to include the headers you are interested in. So, if you need the Way class for instance you do

 #include <osmium/osm/way.hpp>

Or, if you need the Debug handler, you

 #include <osmium/handler/debug.hpp>

and so on.

There are some parts of Osmium that are a bit more difficult to use. You'll find some examples in the example and osmjs directories.

OSM File Input

If you want to read PBF and/or XML OSM files have to add one or both of the following lines to your program:


And then

 #include <osmium.hpp>

PBF support

For PBF input link with: -lz -lpthread -lprotobuf-lite -losmpbf

XML support

For XML input:

Link with: -lexpat

For XML output:

Compile with: `xml2-config --cflags`
Link with: `xml2-config --libs`


GEOS support is added by compiling with -DOSMIUM_WITH_GEOS $(shell geos-config --cflags) and linking with $(shell geos-config --libs). This gives you functions for creating GEOS geometries from Osmium geometries. Multipolygon/area support needs GEOS.


OGR support is added by including the following header file:

 #include <osmium/geometry/ogr.hpp>

Compile with: `gdal-config --cflags`

Link with: `gdal-config --libs`

This gives you functions for creating OGR geometries from Osmium geometries.


Support for Shapelib is added by including the following header file:

 #include <osmium/geometry/shplib.hpp>

Link with: -lshp

This gives you functions for creating Shplib geometries from Osmium geometries which can written to Shapefiles.


To compile with Javascript support include the following header file:

 #include <osmium/javascript.hpp>

Link with: -lv8 -licuuc

If you define OSMIUM_WITH_SHPLIB you'll get access from Javascript to the shplib support.

You can add -DOSMIUM_V8_FORCE_GC to force V8 garbage collection after each node/way/relation/area callback. Use it only to find memory leaks. It will make Osmium really slow.