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