-
Notifications
You must be signed in to change notification settings - Fork 31
/
README
208 lines (146 loc) · 6.2 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
Osmium
======
============================================================================
THIS IS THE "OLD" OSMIUM WHICH IS NOT BEING DEVELOPED ANY MORE!
You almost certainly want the "new" Osmium at http://osmcode.org/
============================================================================
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/
Osmium works with V8 version 3.14 and 3.15, but not with 3.21.
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 <[email protected]>.
Other authors:
* Frederik Ramm <[email protected]> (Multipolygon code, ...)
* Christian Vetter <[email protected]> (PBF parser)
* Scott A. Crosby <[email protected]> (PBF format)
* Peter Körner <[email protected]> (XML and PBF writer, ...)
* Johannes Kolb <[email protected]> (Tests, ...)