===================
pysmap Installation
===================

pysmap is based on EasyInstall, so a basic::

	sudo python setup.py install

should do.  If you do not have sudo privileges on the target machine, you 
probably do not want to bother with this package, even though EasyInstall
could cope -- dependency installation is just too messy.

Dependencies
------------

The easy dependencies are Tkinter (usually packaged with python), psycopg2
(Debian package python-psycopg2) for database access, PIL (Debian:
python-imaging), processing (Debian: python-processing; this will go away when
I target python 2.6) and ElementTree (packaged with python in recent versions,
otherwise Debian package python-celementtree); the latter is only required if
you want to save GPX files.

mapnik is in Debian stable, so installing it is easy. The hard part is setting
up the backend database and importing the data.  The `descriptions on the
mapnik <http://wiki.openstreetmap.org/index.php/Mapnik>`_ page apply.  Note
that if you call the database you will create during this procedure gis and
arrange for ident-based access to that data for your own user, you won't have
to configure the [db]dsn item.

That is, on Debian, you should create your postgres db like this (assuming
it's on your local host)::

	git pull https://github.com/gravitystorm/openstreetmap-carto
	sudo aptitude install postgresql postgresql-client python-mapnik
	sudo aptitude install postgresql-9.4-postgis-2.1  # or whatever
	sudo -u postgres createdb -T template0 -E utf8 gis
	sudo -u postgres createuser -SDR $USER
	sudo -u postgres psql gis -c "GRANT ALL PRIVILEGES ON DATABASE gis TO $USER"
	psql gis -c "CREATE EXTENSION postgis"

Then, get some osm dump (osm.org, export shows what to do).  Save as, say,
map.osm.  Then::
	
	osm2pgsql -d gis map.osm


Configuration
-------------

Once you have mapnik set up. create a file ~/.pysmap, containing at
least something like the following::

	[general]
	mapnikdefs = /path/to/your/osm/osm.xml

(replacing the path with whatever you chose during the mapnik install).

If you did not call your osm database gis or you need special authentiation
to access the database, you will need to set the dsn item in the db
section, like::

	[db]
	dsn: dbname=mygis,user=fiddle,password=josua,host=remote,port=5454

You should be all set.

For reference, here's a list of everything that can be configured in ~/.pysmap;
This is actually the output of pysmap -H.


Section [general]
.................

Everything that doesn't fit anywhere else.

* mapnikDefs: string; 
  defaults to '' --
  Path to the mapnik render definition.

Section [db]
............

Settings defining database access

* dsn: string; 
  defaults to 'dbname=gis' --
  String defining the connection to the GIS database for search
  operations.  The format is <key>=<value>{,<key>=<value>}, where keys
  include dbname, host, port, user, password and more. See psycopg
  documentation for details.

Section [export]
................

Settings related to exporting tracks

* pointInterval: floating point value; 
  defaults to '10' --
  Number of seconds to track/waypoints will be separated by in time-
  cloaked export
* startjitter: integer; 
  defaults to '30' --
  Width in days of the interval in which the start point of a track will
  be shifted on time-cloaked gpx export.

Section [state]
...............

Application state (these will be overwritten on exit)

* geometry: string; 
  defaults to '900x550' --
  Window geometry
* initalScale: integer; 
  defaults to '5' --
  Initial scale of map
* initialPos: coordinates (long,lat); 
  defaults to '10.0000,50.0000' --
  Initial coordinates (long, lat)
* saveCloaked: boolean; 
  defaults to 'True' --
  Save GPX files with 'normalized' timestamps?