README

                              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