glosm 0.0.3
=============
glosm is a framework for developing high-performance geospatial data
visualization applications of both interactive and batch nature
featuring OpenGL-based 3D first-person and tile renderers.
Features
========
* Basic OSM XML loader
* Basic geometry generator (renders buildings, barriers and roads
in 3D, other polygons as lines at ground level)
* Mercator and spherical projections
* Support for tracks in GPX format
* SRTM elevation data support
* First-person real-time 3D map viewer
* Command-line ortho tile renderer
* Extensible framework for building (other) 3D geodata
visualization applications
Requirements
============
Libraries:
* expat2
* OpenGL
* GLEW (only required on windows)
* SDL or GLUT (only required for viewer)
* SDL_gles (only required for viewer on OpenGL ES platforms)
* libpng (only required for tiler)
* X11 (only required for tiler)
Applications:
* CMake >= 2.6
since CMake builtin GLUT detection routine requires it for some
reason, you will also need libXmu and libXi installed.
Summarizing, for Debian-based systems, you'll need to run:
apt-get install cmake libexpat1-dev libglut3-dev libsdl1.2-dev \
libpng12-dev libxmu-dev libxi-dev
Installation
============
Compilation: cmake . && make
Installation: make install
Note that you don't need to install it to run programs, and in case
you really want to install it, you may need to tweak installation
prefix (either by providing -DCMAKE_INSTALL_PREFIX=... to cmake or
with ccmake as below). Also note that cmake doesn't provide
uninstall target.
You can use curses frontend for cmake (ccmake) to select optional
components interactively or specify -DBUILD_TILER=[YES|NO] and
-DBUILD_VIEWER=[YES|NO] in cmake arguments to enable/disable
building of specific applications. By default, viewer is always
built and tiler is only build on UNIX platforms.
If you plan to hack on glosm source, it's better idea to use
so-called out-of-source build to not pollute source tree with build
files. Here's how it's done:
mkdir build && cd build && cmake .. && make
On FreeBSD, glosm is also available from ports collection
(graphics/glosm, [1]).
Native build on Windows has not been tested yet, but
cross-compilation works (see [2]) and native compilation should work
similarily.
[1] http://www.freshports.org/graphics/glosm
[2] https://github.com/AMDmi3/glosm/wiki/CrossCompilation
Usage
=====
This package contains two applications: interactive map viewer
(glosm-viewer) and .png tile generator (glosm-tiler).
glosm-viewer
------------
glosm-viewer [-sfh] [-t <path>] [-l location] <file.osm|->
[<file.gpx> ...]
runs interactive 3D map viewer for a specified map dump. Dumps can
be obtained from OpenStreetMap editing applications (jOSM,
Mercator), via OpenStreetMap API, from third parties and in many
other ways. Sample (fake) .osm file is provided in this package
under testdata/ subdirectory.
If `-' is provided as filename, osm data is read from stdin.
Please be careful with large dumps, as the application requires
amount of RAM comparable to the .osm file size. It also takes some
time (under a minute, however) to load a large dump.
Options:
-s - enable spherical Earth view (instead of mercator)
-f - disable GLEW OpenGL version check (for testing purposes)
-h - show help
-t - specify path to directory with SRTM (*.hgt) files and
enable 3D terrain layer
-l - specify initial position and direction of viewer.
Argument is comma-separated list of floating-point values:
longitude, latitude, elevation, yaw and pitch. Each value
may be empty and extra values in the end may be omitted, in
which case program defaults are used. Values are specified
in decimal angles and meters.
example: -l 57.33,34.11,100
(55.33E, 34.11N, height = 100 meters)
example: -l ,,100,180,0
(default location, height = 100 meters,
look straight to south)
Controls:
W or Up - move forward
S or Down - move backward
A or Left - move left
D or Right - move right
C - move down
Space - move up
L - toggle height lock (useful for fly-by's)
H - same as L, but locks you at human height
+ - increase movement speed by 5x
- - decrease movement speed by 5x
Shift - increase movement speed by 5x when pressed (SDL only)
Ctrl - decrease movement speed by 5x when pressed (SDL only)
1 - toggle lowres (ground) layer
2 - toggle hires (buildings) layer
3 - toggle GPX layer
4 - toggle terrain layer
Q or Escape - close application
Right mouse button toggles mouse grab. When grab is off, view
may be dragged with left mouse button.
glosm-tiler
-----------
glosm-tiler [options] <file.osm|-> <outdir>
runs tile renderer for a specified dump, which are saved into outdir
in the same format as mapnik tiles (<outdir>/<zoom>/<x>/<y>.png).
If `-' is provided as filename, osm data is read from stdin.
Options:
-0..-9 - set png compression level (default 6)
-x minlon
-X maxlon
-y minlat
-Y maxlat - set bounding box for rendering. Units are floating
point degrees (e.g. 55.12345)
-z minzoom
-Z maxzoom - set zoom levels for rendering. Default 0 - 18
-s skew - set skew for pseudo-3D effect (default = 1.0, 0 =
no skew = map without 3D effect)
-m samples - specify number of samples for multisample antialiasing
(default = 4, use 1 if your drivers doesn't support
multisampling)
Note on optimizing tiles
------------------------
For optimal rendering speed and minimal space taken by tiles, it's
usually better to render tiles with -1 (minimal compression level),
and compress them by optipng afterwards:
find <outdir> -name "*.png" -print0 |
xargs -0 -n 64 -P <jobs> optipng -quiet -o1
where outdir is directory containing tiles and jobs is desired
number of jobs (probably # of cpus + 1).
OpenGL details
==============
Application requires OpenGL version >= 1.5. Currently, only notable
required feature is buffer objects support (glGenBuffers et al.)
When GLEW is used, two checks for required OpenGL functionality
are done: GLEW check for GL_VERSION_1_5 and check for required
functions != NULL. The first is disabled with -f option to viewer,
if this options makes viewer work for you, please report.
Additionally, glosm-tiler requires pbuffer support and that is
currently only available through GLX, thus X11 installation is
required to use glosm-tiler.
Multisampling support is also highly recommended.
OpenStreetMap tag support
=========================
There are some notable tags this software supports:
* height
* min_height
* building:levels
* building:min_level
* building:ground_level
* building:skipped_levels (see [3])
to determine height of 3D objects (buildings, barriers). See [2].
Height of one level is taken as 3 meters, for some 1-level buildings
1 meter is added for basement.
[2] http://wiki.openstreetmap.org/wiki/User%3AJongleur/MultiLevel_Building_Shapes
[3] http://wiki.openstreetmap.org/wiki/User_talk:Jongleur/MultiLevel_Building_Shapes
* building:roof:shape
* building:roof:orientation
* building:roof:angle
for specific roof shapes support. See [4]. Supported roof shapes
are: flat, pitched, hipped, pyramidal, conical (currently same as
pyramidal), crosspitched.
[4] http://wiki.openstreetmap.org/wiki/Proposed_features/Building_attributes
* width
* lanes
for highway widths.
API stability
=============
As the project is on early stages of development, neither API not
ABI compatibility is guaranteed, so for now use library on your own
risk. Because of that, neither versioned library (.so.N) nor includes
are currently installed.
Primary candidates for API change are:
* OsmDatasource interface
* GeometryGenerator (due to above)
* Geometry (material support, serialization)
Tests
=====
There are some tests under tests/ subdirectory, you can run them by
running `ctest' from your buildtree.
Documentation
=============
Doxygen is supported, just run `doxygen' from this directory to
generate class descriptions under doc/html/. There's also some more
documentation under doc/.
There are some simple examples of working with glosm under examples/
subdirectory.
License
=======
This software is distributed under the GNU Affero General Public
License version 3. Please read the COPYING file for more information.
Credits
=======
Author:
Dmitry Marakasov <amdmi3@amdmi3.ru>
Contacts
========
Apart from emails above,
* Source code repository:
https://github.com/AMDmi3/glosm
* Wiki:
https://github.com/AMDmi3/glosm/wiki
* Demo of tiler-generated raster map:
http://glosm.amdmi3.ru
* Page on OSM wiki with some screenshots:
http://wiki.openstreetmap.org/wiki/Glosm