1 glosm 0.0.2
2 =============
3
4 glosm is a framework for developing high-performance geospatial data
5 visualization applications of both interactive and batch nature
6 featuring OpenGL-based 3D first-person and tile renderers.
7
8Features
9========
10
11 * Basic OSM XML loader
12 * Basic geometry generator (renders buildings, barriers and roads
13 in 3D, other polygons as lines at ground level)
14 * Mercator and spherical projections
15 * First-person real-time 3D map viewer
16 * Command-line ortho tile renderer
17 * Extensible framework for building (other) 3D geodata
18 visualization applications
19
20Requirements
21============
22
23 Libraries:
24 * expat2
25 * OpenGL
26 * GLEW (only required on windows)
27 * SDL or GLUT (only required for viewer)
28 * SDL_gles (only required for viewer on OpenGL ES platforms)
29 * libpng (only required for tiler)
30 * X11 (only required for tiler)
31 Applications:
32 * CMake >= 2.6
33
34 since CMake builtin GLUT detection routine requires it for some
35 reason, you will also need libXmu and libXi installed.
36
37 Summarizing, for Debian-based systems, you'll need to run:
38
39 apt-get install cmake libexpat1-dev libglut3-dev libsdl1.2-dev \
40 libpng12-dev libxmu-dev libxi-dev
41
42Installation
43============
44
45 Compilation: cmake . && make
46 Installation: make install
47
48 Note that you don't need to install it to run programs, and in case
49 you really want to install it, you may need to tweak installation
50 prefix (either by providing -DCMAKE_INSTALL_PREFIX=... to cmake or
51 with ccmake as below). Also note that cmake doesn't provide
52 uninstall target.
53
54 You can use curses frontend for cmake (ccmake) to select optional
55 components interactively or specify -DBUILD_TILER=[YES|NO] and
56 -DBUILD_VIEWER=[YES|NO] in cmake arguments to enable/disable
57 building of specific applications. By default, viewer is always
58 built and tiler is only build on UNIX platforms.
59
60 If you plan to hack on glosm source, it's better idea to use
61 so-called out-of-source build to not pollute source tree with build
62 files. Here's how it's done:
63
64 mkdir build && cd build && cmake .. && make
65
66 On FreeBSD, glosm is also available from ports collection
67 (graphics/glosm).
68
69 Native build on Windows has not been tested yet, but
70 cross-compilation works (see [1]) and native compilation should work
71 similarily.
72
73 [1] https://github.com/AMDmi3/glosm/wiki/CrossCompilation
74
75Usage
76=====
77
78 This package contains two applications: interactive map viewer
79 (glosm-viewer) and .png tile generator (glosm-tiler).
80
81 glosm-viewer
82 ------------
83
84 glosm-viewer [-sf] <file.osm|->
85
86 runs interactive 3D map viewer for a specified map dump. Dumps can
87 be obtained from OpenStreetMap editing applications (jOSM,
88 Mercator), via OpenStreetMap API, from third parties and in many
89 other ways. Sample (fake) .osm file is provided in this package
90 under testdata/ subdirectory.
91
92 If `-' is provided as filename, osm data is read from stdin.
93
94 Please be careful with large dumps, as the application requires
95 amount of RAM comparable to the .osm file size. It also takes some
96 time (under a minute, however) to load a large dump.
97
98 Options:
99
100 -s - enable spherical Earth view (instead of mercator)
101 -f - disable GLEW OpenGL version check (for testing purposes)
102
103 Controls:
104
105 W or Up - move forward
106 S or Down - move backward
107 A or Left - move left
108 D or Right - move right
109 C - move down
110 Space - move up
111 L - toggle height lock (useful for fly-by's)
112 H - same as L, but locks you at human height
113 + - increase movement speed by 5x
114 - - decrease movement speed by 5x
115 Shift - increase movement speed by 5x when pressed (SDL only)
116 Ctrl - decrease movement speed by 5x when pressed (SDL only)
117 1 - toggle lowres (ground) layer
118 2 - toggle hires (buildings) layer
119 Q or Escape - close application
120
121 Right mouse button toggles mouse grab. When grab is off, view
122 may be dragged with left mouse button.
123
124 glosm-tiler
125 -----------
126
127 glosm-tiler [options] <file.osm|-> <outdir>
128
129 runs tile renderer for a specified dump, which are saved into outdir
130 in the same format as mapnik tiles (<outdir>/<zoom>/<x>/<y>.png).
131
132 If `-' is provided as filename, osm data is read from stdin.
133
134 Options:
135
136 -0..-9 - set png compression level (default 6)
137
138 -x minlon
139 -X maxlon
140 -y minlat
141 -Y maxlat - set bounding box for rendering. Units are floating
142 point degrees (e.g. 55.12345)
143
144 -z minzoom
145 -Z maxzoom - set zoom levels for rendering. Default 0 - 18
146
147 -s skew - set skew for pseudo-3D effect (default = 1.0, 0 =
148 no skew = map without 3D effect)
149
150 Note on optimizing tiles
151 ------------------------
152
153 For optimal rendering speed and minimal space taken by tiles, it's
154 usually better to render tiles with -1 (minimal compression level),
155 and compress them by optipng afterwards:
156
157 find <outdir> -name "*.png" -print0 |
158 xargs -0 -n 64 -P <jobs> optipng -quiet -o1
159
160 where outdir is directory containing tiles and jobs is desired
161 number of jobs (probably # of cpus + 1).
162
163OpenGL details
164==============
165
166 Application requires OpenGL version >= 1.5. Currently, only notable
167 required feature is buffer objects support (glGenBuffers et al.)
168
169 When GLEW is used, two checks for required OpenGL functionality
170 are done: GLEW check for GL_VERSION_1_5 and check for required
171 functions != NULL. The first is disabled with -f option to viewer,
172 if this options makes viewer work for you, please report.
173
174 Additionally, glosm-tiler requires pbuffer support and that is
175 currently only available through GLX, thus X11 installation is
176 required to use glosm-tiler.
177
178 Multisampling support is also highly recommended.
179
180OpenStreetMap tag support
181=========================
182
183 There are some notable tags this software supports:
184
185 * height
186 * min_height
187 * building:levels
188 * building:min_level
189 * building:ground_level
190 * building:skipped_levels (see [3])
191
192 to determine height of 3D objects (buildings, barriers). See [2].
193 Height of one level is taken as 3 meters, for some 1-level buildings
194 1 meter is added for basement.
195
196 [2] http://wiki.openstreetmap.org/wiki/User%3AJongleur/MultiLevel_Building_Shapes
197 [3] http://wiki.openstreetmap.org/wiki/User_talk:Jongleur/MultiLevel_Building_Shapes
198
199 * building:roof:shape
200 * building:roof:orientation
201 * building:roof:angle
202
203 for specific roof shapes support. See [4]. Supported roof shapes
204 are: flat, pitched, hipped, pyramidal, conical (currently same as
205 pyramidal), crosspitched.
206
207 [4] http://wiki.openstreetmap.org/wiki/Proposed_features/Building_attributes
208
209 * width
210 * lanes
211
212 for highway widths.
213
214API stability
215=============
216
217 As the project is on early stages of development, neither API not
218 ABI compatibility is guaranteed, so for now use library on your own
219 risk. Because of that, neither versioned library (.so.N) nor includes
220 are currently installed.
221
222 Primary candidates for API change are:
223
224 * OsmDatasource interface
225 * GeometryGenerator (due to above)
226 * Geometry (material support, optimizations like triangle
227 strip/fan support, serialization)
228
229Tests
230=====
231
232 There are some tests under tests/ subdirectory, you can run them by
233 running `ctest' from your buildtree.
234
235Documentation
236=============
237
238 Doxygen is supported, just run `doxygen' from this directory to
239 generate class descriptions under doc/html/. There's also some more
240 documentation under doc/.
241
242 There are some simple examples of working with glosm under examples/
243 subdirectory.
244
245License
246=======
247
248 This software is distributed under the GNU General Public License
249 version 3. Please read the COPYING file for more information.
250
251Credits
252=======
253
254 Author:
255 Dmitry Marakasov <amdmi3@amdmi3.ru>
256