v1.0, 2010-1-31
Contact:
Jay Farrimond
jay@sabikerides.com
http://www.sabikerides.com/
The sabx10 package provides the tools to generate HTML and PDF maps from SABX files. The pieces of sabx10 expect to live in a directory structure they understand. Since these packages are generated and debugged under Ubuntu, the directories mentioned here will follow the Debian filesystem hierarchy standards (more or less). Ubuntu 9.04 is what's being used currently.
Here are some instructions to help you get the sabx10 map generation software up and running. This has been developed and tested on Ubuntu 9.04 with python 2.6.2.
All the pieces of the sabx10 package expect to live in a directory structure similar to the following. ride_data contains the SABX files. site contains everything necessary to support the HTML maps. temp is used for storing temporary bi-products of the build process. The finished HTML and PDF maps are placed into the site/rides directory. Once the maps are generated, the entire contents of site make up the site.
Create this directory structure in your home directory. Don't worry about the makefile and sample.sabx files yet. They will be addressed in a later step.
Everything under the temp directory is created by the make file and is re-created if not found, so you only need to create temp. By the way, you should never count on the contents of the temp directory to exist before make is run.
sabx/
makefile
ride_data/
sample_ride/
sample.sabx
site/
css/
images/
js/
markers/
rides/
staging/
temp/
sample_ride/
osm/
print/
profile/
The sabx10 package is at the heart of map generation. It provides all the map generation utilities and all the related data files. The package can be downloaded from here:
The installation instructions are here:
The markers are used by the HTML maps to show parking, turns, stops, and pois. They need to be available in the site used to show the HTML maps. They are included in the sabx10 download in the markers directory. Copy the markers into the sabx/site/markers directory.
The HTML maps all use standard css and javascript. The files are included in the sabx10 package in the web directory. Copy the files in there into the sabx/site/css and sabx/site/js directories.
The HTML maps require a favicon, and the PDF map generator requires a logo and an arrowhead image. The images for these are included in the sabx10 download in the images directory. Copy them to the site/images directory.
The HTML maps use Google Maps to display the map. The Google Maps API requires a developer key to function properly. The sample files contain the SABikeRides key, and will only work for files served from sabikerides.com. In order to make them work for your site, you will need to use your own key.
The Google Maps key is located in the ride and staging templates that are installed as part of the sabx10 package. In Ubuntu they are located in these locations:
The HTML map pages make heavy use of Jquery and Jquery widgets in their javascript. The Jquery libraries should be installed in the site/js directory.
For the main jquery library, we are using v1.3.2 currently. You can download this from the Jquery web site on its downloads page.
We currently use the tabs and dialog widgets from v1.7.2 of the Jquery UI widgets. You can download a customized version of the widget library from the Jquery UI site on its downloads page.
We are also using the smoothness look and feel from Jquery UI, so copy the smoothness directory from the css directory in the Jquery UI download into the site/css directory.
The HTML maps make use of the reset.css and text.css files from the 960gs package. The package can be downloaded from the 960gs web site via the download link. Unzip the package and copy reset.css and text.css to the site/css directory.
All of the Python programs make use of the Jinja2 templating engine to render their output. It's packaged for Ubuntu, so install it using apt.
$ sudo apt-get install python-jinja2
The PDF version of the turn-by-turn instructions is rendered using the Reportlab python library. It's packaged for Ubuntu, so install it using apt.
$ sudo apt-get install python-reportlab
The ride profiles use the python library Matplotlib to render the profile PNGs. It's packaged for Ubuntu, so install it using apt.
$ sudo apt-get install python-matplotlib
The overall ride PDF files use the python library Pypdf to combine all the seperate PDF pages into one PDF file. It's packaged for Ubuntu, so install it using apt.
$ sudo apt-get install python-pypdf
Mapnik is used to generate the PNG images used by the PDF maps. Currently v0.7.0 is being used. The version in Ubuntu 9.04 is out of date, so you will have to download it from the Mapnik web site. There is an INSTALL document included in the package that tells how to install Mapnik. Be sure to use the INPUT_PLUGINS= option for the scons configure step of the process to make sure that the OSM plugin is installed. Even though I don't use them all, I just have it install all the availabe plugins since I have plenty of disk space. I use it like this:
$ python scons/scons.py configure INPUT_PLUGINS=all
By the way, the installation page in their wiki is much more useful than the INSTALL file included in the distribution.
I'm using PostgreSQL with the PostGIS extensions to store the generic map data, meaning the non-SABX data. I just use the default PostgreSQL and PostGIS installs from Ubuntu. This page gives some information on setting it all up properly.
I use data from the OpenStreetMap project to render the PDF maps. You can find out how to get OSM data from this page and this page. I've used the CloudMade extracts for the Texas maps because they're much smaller than the entire planet extract.
Once I get the data dumps for the area of interest, I use the osm2pgsql program to load it into PostgreSQL. Be sure to use the option to set the projection to 4326. Here's an example:
$ osm2psql -l -U gisuser texas.osm.bz2
The style sheet templates used by Mapnik to create the PDF maps contain database user names and passwords. These need to be changed from 'jay' and a blank password to the values used in your system. Just do a search on 'user' and 'password' and you'll find them. There are multiple instances of each in both files. They live in the following files:
Now that all the software is installed and ready to go, it's time to make the sample map to make sure everything is working. The sample makefile and SABX file are included in the sabx10 download under the sample directory.
Copy makefile into the main sabx directory. Copy sample.sabx into the sabx/ride_data/sample_ride directory. Then, from the command-line, change to the sabx directory and run make.
$ cd ~/sabx
$ make