OCitySMap installation instructions
===================================

These instructions refer to software dependencies by using Ubuntu
Lucid (10.04) package names. Minor adaptations might be needed for
other distributions or for the precise Debian or Ubuntu release you
are using. They have been tested on several x86_64 hosts.

 1. Installation of PostgreSQL and PostGIS

    sudo aptitude install postgresql postgresql-contrib

 2. Creation of a new PostgreSQL user

    sudo -u postgres createuser -P -S -D -R maposmatic

    Enter the password twice (we use later 'ereiamjh' as example
    password).

 3. Creation of the database

    sudo -u postgres createdb -E UTF8 -O maposmatic maposmatic

    (see http://wiki.openstreetmap.org/wiki/Mapnik/PostGIS)

    You can now try to connect to the database, using:

    psql -h localhost -U maposmatic maposmatic

    If it doesn't work, fix your configuration.

 4. Enable PostGIS on the database

    PostGIS is in fact a set of functions and data types for
    PostgreSQL, and every PostgreSQL database needing these features
    must be initialized as follows. We do this initialization of the
    database with superuser privileges, and then later fix the table
    owners so that our normal user can use the database.

    a. Enable the plpgsql language on the maposmatic database

    sudo -u postgres createlang plpgsql maposmatic

    b. Download postgis 1.5.1

    sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable

    sudo aptitude update
    sudo aptitude dist-upgrade # Or safe-upgrade if you prefer

    sudo aptitude install postgresql-8.4-postgis

    If nothing happens, you may have to check the output of "apt-get
    policy postgresql-8.4-postgis" and adjust your apt preferences.  A
    sensible default preferences configuration file for this
    repository could be:

      Package: *
      Pin: release o=LP-PPA-ubuntugis-ubuntugis-unstable
      Pin-Priority: 700

    c. Install PostGIS support in Postgres

    sudo -u postgres \
         psql \
              -f /usr/share/postgresql/8.4/contrib/postgis-1.5/postgis.sql \
              -d maposmatic

    Provide comments (Optional):

    sudo -u postgres \
         psql \
              -f /usr/share/postgresql/8.4/contrib/postgis_comments.sql \
              -d maposmatic

    d. Add the list of spatial referential systems

    sudo -u postgres \
         psql \
              -f /usr/share/postgresql/8.4/contrib/postgis-1.5/spatial_ref_sys.sql \
              -d maposmatic

    e. Change the owner of the new tables to maposmatic

    echo "ALTER TABLE geometry_columns OWNER TO maposmatic;
          ALTER TABLE spatial_ref_sys OWNER TO maposmatic;" | \
    sudo -u postgres psql -d maposmatic

 5. Installation of osm2pgsql

    osm2pgsql is the tool that takes OSM data as input, and creates a
    PostGIS database from it. At the time of the writing of this
    document, the osm2pgsql packaged in Debian/Ubuntu is not recent
    enough, so we grab a fresh version from SVN.

    a. If needed, install SVN

    sudo aptitude install subversion

    b. Grab osm2pgsql code

    svn co http://svn.openstreetmap.org/applications/utils/export/osm2pgsql/
    # Tested revisions: r27862

    c. Install the build dependencies

    sudo apt-get build-dep osm2pgsql

    d. Compile

    cd osm2pgsql
    ./autogen.sh
    ./configure # with --prefix=.... as needed
    make

    e. Install

    Provided you supplied the correct --prefix=... option, just enter:

    make install

 6. Download the OSM data

    We give the example for Luxembourg.

    wget http://download.geofabrik.de/osm/europe/luxembourg.osm.bz2

 7. Import the OSM data

    osm2pgsql -s -c -d maposmatic -m -U maposmatic -W \
              -H localhost luxembourg.osm.bz2

    If you have a lot of RAM, remove '-s', it will make the import
    faster. If you miss RAM (and have a lot of time available) you can
    also use the '-C' option together with '-s'. (See osm2pgsql -h).

    If you want to add other OSM DB files, replace the '-c' option
    with a '-a' option in the subsequent files you are adding: if you
    keep the '-c' option, it will erase any previous GIS data you may
    have. For example:

    osm2pgsql -s -a -d maposmatic -m -U maposmatic -W \
              -H localhost ile-de-france.osm.bz2


 8. Install Mapnik

    We need Mapnik 2.0.0, which is not yet available in stable
    Debian/Ubuntu, so we need to compile it from source.

    a. Install the dependencies

    # Base dependencies (0.7.0 by default on lucid, a good start)
    sudo apt-get build-dep python-mapnik

    # Upgrade to libboost >= 1.41
    sudo add-apt-repository ppa:thomasjj/backports
    sudo aptitude update
    sudo aptitude dist-upgrade # Or safe-upgrade if you prefer

    sudo aptitude purge libboost1.40-dev

    sudo aptitude install libboost1.46-dev libboost-date-time1.46-dev \
        libboost-filesystem1.46-dev libboost-iostreams1.46-dev \
        libboost-program-options1.46-dev libboost-python1.46-dev \
        libboost-regex1.46-dev libboost-serialization1.46-dev \
        libboost-system1.46-dev libboost-thread1.46-dev

    b. Download Mapnik

    wget http://download.berlios.de/mapnik/mapnik-2.0.0.tar.bz2

    c. Compile and install Mapnik 2

    tar xvjf mapnik-2.0.0.tar.bz2
    cd mapnik-2.0.0

    (any version >= 2.0.0 should follow the same scheme)

    python scons/scons.py configure INPUT_PLUGINS=all \
      OPTIMIZATION=3 SYSTEM_FONTS=/usr/share/fonts/

    (You can also path PREFIX=... and PYTHON_PREFIX=.... if you don't
    want a system-wide installation)

    python scons/scons.py

    python scons/scons.py install

    d. Check the installation

    Run a Python interpreter, and run "import mapnik2". If it doesn't
    work and you didn't do a system-wide installation of Mapnik, don't
    forget to set the PYTHONPATH and LD_LIBRARY_PATH environment
    variables.

10. Install Mapnik-OSM

    Mapnik-OSM is the set of files that tell Mapnik how to render
    OpenStreetMap maps.

    a. Download

    svn co \
        http://svn.openstreetmap.org/applications/rendering/mapnik \
        mapnik2-osm
    # Tested revision: r27862

    b. Installation of static data

    In addition to the OpenStreetMap data, some other static data are
    used to render the maps (world boundaries, etc.)

    cd mapnik2-osm
    sh ./get-coastlines.sh

    c. Enabling unifont

    In order to get correct rendering for Korean, Chinese or Japanese
    character, the unifont font must be used. In order do enable it:

    sudo aptitude install ttf-unifont

    Then edit inc/fontset-settings.xml.inc.template and uncomment the
    following line :

    	  <Font face_name="unifont Medium" />

    in the book-fonts, bold-fonts and oblique-fonts sections.

    d. Configuration

    python ./generate_xml.py --dbname maposmatic --host 'localhost' \
                             --user maposmatic --port 5432 \
                             --password 'ereiamjh'

11. Installation of OCitySMap

    a. Install Git if needed

    sudo aptitude install git-core git-email

    b. Grab the sources

    git clone git://git.savannah.nongnu.org/maposmatic/ocitysmap.git

    c. Install dependencies

    sudo aptitude install python-psycopg2 python-gdal \
                          python-gtk2 python-cairo \
			  python-shapely

    Note that python-gtk2 is not needed for any graphical interface,
    but because it contains Pango and PangoCairo that we use to render
    text on the map.

    d. Configuration file

    Create a ~/.ocitysmap.conf configuration file, modeled after the
    provided ocitysmap2.conf-template file.

12. Run OCitySMap

    ./ocitysmap2-render -t "Ceci n'est pas Paris" --osmid=-411354  # Contern, LU
    ./ocitysmap2-render -t "Ceci n'est pas Paris" --osmid=-943886  # Chevreuse, FR

Appendix: installation of the MapQuest stylesheet
-------------------------------------------------

The above instructions, at step 10, describe how to set up ocitysmap
with the default Mapnik stylesheet for OpenStreetMap. It is possible
to install other stylesheets, such as the stylesheets made available
by MapQuest. The instructions below detail how to install those
additional stylesheets, making the assumption that ocitysmap is
properly configured and running with the default OSM stylesheet.

First, grab the MapQuest stylesheets:

 git clone git://github.com/MapQuest/MapQuest-Mapnik-Style.git

 (version tested: 9d6c5503194c58fc1f9f760b4e5af8a1602dfb30)

Go into the MapQuest-Mapnik-Style directory, in which we will do all
the configuration.

First, those stylesheets require the same "world boundaries"
information as the original OSM stylesheet, so we are going to share
these informations by creating a symbolic link:

 ln -s /path/to/original/osm/stylesheet/world_boundaries world_boundaries

In addition to those world boundaries, the MapQuest stylesheets need a
few other files. Download the corresponding tarball:

 wget http://developer.mapquest.com/content/static/geotiffs/mercator_tiffs.tar

Unpack this archive, and put the four mq_world_mercator_*.tiff files
directory into the world_boundaries/ directory (this directory is
shared with the original OSM stylesheet, but this is not a problem as
the mq_world_mercator_*.tiff files are not used by the original OSM
stylesheet).

Now, to the configuration of the stylesheet itself:

 cp mapquest_inc/datasource-settings.xml.inc.template mapquest_inc/datasource-settings.xml.inc
 vi mapquest_inc/datasource-settings.xml.inc

Adjust your database details appropriately. The "estimate_extent"
value should be "false", and the "extent" value should be
-20037508,-19929239,20037508,19929239.

Next configuration file:

 cp mapquest_inc/fontset-settings.xml.inc.template mapquest_inc/fontset-settings.xml.inc
 vi mapquest_inc/fontset-settings.xml.inc

Not much to change here, the default value is fine. If you want to use
the same font for the original OSM stylesheet and the MapQuest one,
replace "Arial" by "DejaVu".

Next (and final) configuration file:

 cp mapquest_inc/settings.xml.inc.template mapquest_inc/settings.xml.inc
 vi mapquest_inc/settings.xml.inc

And set the following values:

 * symbols to "mapquest_symbols" (the directory in the MapQuest
   stylesheet where the icons and other related elements are stored)

 * osm2pgsql_projection to "&srs900913;"

 * world_boundaries to "world_boundaries" (the directory in the
   MapQuest stylesheet where the world boundaries data can be found)

 * prefix to "planet_osm". This is the prefix of the OSM tables in the
   PostGIS database.

The final step is to integrate this new stylesheet in ocitysmap. To do
so, edit your ocitysmap.conf file, and add a new stylesheet section,
like:

[mapquest_eu]
name: MapQuestEu
description: MapQuest Europe stylesheet
path: /path/to/MapQuest-Mapnik-Style/mapquest-eu.xml

Don't forget to add "mapquest_eu" to the available_stylesheets
variable, which lists all available stylesheets.

Note that in addition to the MapQuest Europe stylesheet
(mapquest-eu.xml), the Git repository also contains the MapQuest US
and MapQuest UK stylesheets (mapquest-us.xml and mapquest-uk.xml),
that you can similarly add to your ocitysmap.conf file.