Osmium
======

http://wiki.openstreetmap.org/wiki/Osmium

Osmium is a C++ framework for working with OSM data files. Osmium can read OSM
data in XML or binary format (PBF) and can call different handlers for each OSM
object.

Available handlers include:
* Javascript handler (calls Javascript callbacks you provide)
* Multipolygon handler (assembles areas(multipolygons) from relations and ways)
* NodeLocationStore handler (stores node locations and builds way geometries from them)
* ...

Of course, you can also write your own handlers.

There are a few applications that use Osmium in the examples directory.

The osmjs directory contains the osmjs application that calls your Javascript code
which can then work with the OSM data. It can, for instance, be used to convert
OSM data into Shapefiles.

Note that OSM input files must contain objects in the right order for Osmium to
work properly: first nodes, then ways, then relations. Normally OSM files are
sorted this way, but if yours aren't, you can use Osmosis with the --sort
option to do this.

PREREQUISITES
-------------

Different parts of Osmium (and the applications built on top of it) need
different libraries:

boost (several libraries)
    http://www.boost.org/
    Debian/Ubuntu: libboost-dev
    openSUSE: boost-devel

zlib (for PBF support)
    http://www.zlib.net/
    Debian/Ubuntu: zlib1g-dev
    openSUSE: zlib-devel

shapelib (for shapefile support in osmjs)
    http://shapelib.maptools.org/
    Debian/Ubuntu: libshp-dev
    openSUSE: libshp-devel

libgd (for nodedensity example only)
    http://www.libgd.org/
    Debian/Ubuntu: libgd2-xpm-dev
    openSUSE: gd-devel

GDAL (for OGR support)
    http://gdal.org/
    Debian/Ubuntu: libgdal1-dev
    openSUSE: libgdal-devel

Expat (for parsing XML files)
    http://expat.sourceforge.net/
    Debian/Ubuntu: libexpat1-dev
    openSUSE: libexpat-devel

GEOS (for assembling multipolygons etc.)
    http://trac.osgeo.org/geos/
    Debian/Ubuntu: libgeos++-dev
    openSUSE: libgeos-devel

Google sparsehash
    http://code.google.com/p/google-sparsehash/
    Debian/Ubuntu: libsparsehash-dev
    openSUSE: sparsehash

Google V8 Javascript engine (for Javascript support)
    http://code.google.com/apis/v8/
    Debian/Ubuntu: libv8-dev
    openSUSE: v8-devel

LibICU (for UTF-8/UTF-16 conversion, only for Javascript support)
    http://site.icu-project.org/
    Debian/Ubuntu: libicu-dev
    openSUSE: libicu-devel

Google protocol buffers (for PBF support)
    http://code.google.com/p/protobuf/ (at least version 2.3.0 needed)
    Debian/Ubuntu: libprotobuf-dev protobuf-compiler
    openSUSE: protobuf-devel
    Also see http://wiki.openstreetmap.org/wiki/PBF_Format

Doxygen (to build API documentation)
    http://www.stack.nl/~dimitri/doxygen/
    Debian/Ubuntu: doxygen

libboost-test (for tests)
    http://www.boost.org/doc/libs/1_47_0/libs/test/doc/html/index.html
    Debian/Ubuntu: libboost-test-dev

OSMPBF (for PBF support)
    https://github.com/scrosby/OSM-binary
    Debian/Ubuntu: libosmpbf-dev

You need to either install the packages for your distribution or install those
libraries from source. Most libraries should be available in all distributions.


FILES
-----

Doxyfile    - Needed for building the Osmium C++ docs, call "make doc" to build.
include     - C/C++ include files. All of Osmium is in those header files which
              are needed for building Osmium applications.
osmjs       - Osmium application "osmjs".
osmjs/js    - Example Javascript handlers.
examples    - Osmium example applications.
test        - Tests (see below).
debian      - Needed to build Debian/Ubuntu packages.


BUILDING
--------

First you need to (build and) install all the prerequisites.

Osmium is a header-only library, so there is nothing to build for the
library itself.

Call "make doc" in the top-level directory to build the Osmium C++ docs.

Call "make install" to install the include files and documentation.

See "examples/README" for build instructions of the example applications.

See "osmjs/README" for build instructions of osmjs.

Call "make clean" in any of those places to clean up.


USING OSMIUM IN YOUR C++ CODE
-----------------------------

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 include
<osmium/osm/way.hpp>. If you need the Debug handler, you include
<osmium/handler/debug.hpp>.

If you need any OSM file input, then first define one or both of these macros
and then include <osmium.hpp>:

  #define OSMIUM_WITH_PBF_INPUT
  #define OSMIUM_WITH_XML_INPUT
  #include <osmium.hpp>

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.


TESTING
-------

There are a few tests using the Boost Unit Test Framework in the "test"
directory. Many more tests are needed, any help appreciated.

Run "make test" from the main directory or go to the "test" directory and type
"./run_tests.sh" to compile and run the tests. You can run a single test by
calling "./run_test.sh TESTFILE", for instance:
  ./run_test.sh t/osm/test_node.cpp

There are some other tests that are not neatly integrated. Go to the "test"
directory and run
  broken_way_geometries/test.sh
or
  utf8_clipping/test.sh


LICENSE
-------

Osmium is available under the GNU LGPL version 3 or later, or - at your option -
the GNU GPL version 3 or later.

See http://eigen.tuxfamily.org/index.php?title=Licensing_FAQ&oldid=1116 for a
good description of what that means.


AUTHORS
-------

Osmium was mainly written and is maintained by Jochen Topf <jochen@topf.org>.

Other authors:
* Frederik Ramm <frederik@remote.org> (Multipolygon code, ...)
* Christian Vetter <veaac.fdirct@gmail.com> (PBF parser)
* Scott A. Crosby <scott@sacrosby.com> (PBF format)
* Peter Körner <github@mazdermind.de> (XML and PBF writer, ...)