INSTALLATION

DEPENDENCIES

python >= 2.6, < 3.0
gpsd
zeromq
OpenGL
a GLUT library, such as freeglut3

then:
pip install -r requirements.txt

SETUP

in settings.py:
* create the databases specified in TILE_DB and GPS_LOG_DB


birdseye likes to have control over the gpsd process, so may be best to disable gpsd-autostart when the gps is plugged in. everything will still work if not, but birdseye will not be able to tell if/how things go weird. (see /etc/default/gpsd)

use device in /dev/serial if device name keeps changing (/dev/ttyUSB0 => /dev/ttyUSB1)


ABOUT

the birdseye distribution has four main parts:

1) a full-screen, moving-map navigation app (birdseye.py)
2) a GPS tracking subsystem and logger (gpsmgr.py)
3) a tool to locally cache data from mapservers for offline use (mapcache.py)
4) a web console to explore the tile cache, manage waypoints and regions for download (web/webconsole.py)



CONFIGURATION

sample tile url spec: 'http://{s:0-3}.mapserver.org/tile/{z}/{x}/{y}.{type}'

available directives:

{z} - zoom level
{x} - tile x coordinate, [0, 2^zoom)
{y} - tile y coordinate, [0, 2^zoom)
{-y} - tile y coordinate, but numbered starting in the south and increasing towards the north (i.e., for WMS layers)
{qt} - quadtree index to tile (i.e., for bing layers)
{qt:ABCD} - quadtree index, but with customized symbols to refer to each quadrant
{s:0-3} - server shard (0, 1, 2, 3, in this example)
{s:abc} - server shard (a, b, c, in this example)
{type} - the specified file type for the layer




mapcache.py download profiles. written in yaml (superset of json)

name: region-name
region: lat1,lon1 lat2,lon2 lat3,lon3 lat4,lon4 ...
update: true / false (default)
layers:
  # for each layer:
  <layername>:
    zoom: download depth
    # one or none of:
    refresh-mode: 'always' or 'never' (default)
    refresh-older-than: #days

name - save region under this name. if ommitted, don't save region and just use as one-off ('region' required)
region - polygon defining region boundary. if omitted, use saved region for 'name'
update - if true, update this named region with the new boundary (does NOT affect any tiles downloaded under old region)
<layername> - the name of a layer defined in settings
zoom - depth to download to
refresh-mode: 'always' - download all tiles, even if they already exist in the cache
              'never' - don't download a tile that already exists in the cache
refresh-older-than - re-download a cached tile if downloaded more than N days ago