Commit 20283c6c authored by Thibaut GRIDEL's avatar Thibaut GRIDEL

Imported Upstream version 1.4.1

parents
This diff is collapsed.
doc/INSTALL.txt
\ No newline at end of file
# $Header: /home/amb/routino/RCS/Makefile,v 1.3 2010/05/31 12:44:43 amb Exp $
#
# Makefile
#
# Part of the Routino routing software.
#
# This file Copyright 2009-2010 Andrew M. Bishop
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
#
FILES=$(wildcard */Makefile)
DIRS=$(foreach f,$(FILES),$(dir $f))
########
all:
for dir in $(DIRS); do \
( cd $$dir && $(MAKE) $@ ); \
done
########
clean:
for dir in $(DIRS); do \
( cd $$dir && $(MAKE) $@ ); \
done
########
distclean: clean
for dir in $(DIRS); do \
( cd $$dir && $(MAKE) $@ ); \
done
doc/NEWS.txt
\ No newline at end of file
doc/README.txt
\ No newline at end of file
This diff is collapsed.
This diff is collapsed.
Routino : Configuration
=======================
New in version 1.4 of Routino is the use of configuration files to
allow more information to be provided to the programs at run-time. The
configuration files that are used are:
* Tagging transformation rules for the planetsplitter program.
* Routing profiles for the router program.
* Output translations for the router program.
In keeping with the nature of the input and output files the
configuration files are also XML files. Each of the files uses a custom
defined XML schema and an XSD file is provided for each of them.
Tag Transformation Rules
------------------------
The default name of the tagging transformation rules XML configuration
file is tagging.xml in the same directory as the generated database
files. Other filenames can be specified on the command line using the
--tagging option. When processing the input it is possible to have a
different set of tagging rules for each file; for example different
rules for different countries.
The tagging rules allow modifying the highway tags in the source file
so that the routing can be performed on a simpler set of tags. This
removes the special case tagging rules from the source code into the
configuration file where they can be easily modified. Part of the
provided tagging.xml file showing the rules for motorway_link and
motorway highway types.
<?xml version="1.0" encoding="utf-8"?>
<routino-tagging>
<way>
<if k="highway" v="motorway_link">
<set v="motorway"/>
</if>
<if k="highway" v="motorway">
<output k="highway"/>
<output k="motorbike" v="yes"/>
<output k="motorcar" v="yes"/>
<output k="goods" v="yes"/>
<output k="hgv" v="yes"/>
<output k="psv" v="yes"/>
<output k="paved" v="yes"/>
<output k="multilane" v="yes"/>
<output k="oneway" v="yes"/>
</if>
...
<way>
</routino-tagging>
The rules all have the same format; an if element for matching the
input and some set or output elements to either change the input tags
or create an output tag. The k and v attributes have the same meaning
as the attributes with the same names in the OSM XML file - the tag key
and tag value.
An if rule that has both k and v specified is only applied if a tag
exists in the input that matches both. An if rule that has only the k
attribute is applied if a tag with that key exists and an if rule that
has only the v attribute is applied to all tags with that value.
For the set and output elements the tag that is created in the input or
output tag set uses the k and v attributes specified. If one or both
are not specified then the original ones are used.
Routing Profiles
----------------
The default name of the routing profiles XML configuration file is
profiles.xml in the same directory as the database files. Other
filenames can be specified on the command line using the --tagging
option.
The purpose of this configuration file is to allow easy modification of
the routing parameters so that they do not all need to be specified on
the command line. In versions of Routino before version 1.4 the default
routing parameters (preferred highways, preferred speeds etc) were
contained in the source code, now they are in a configuration file.
When calculating a route the --profile option selects the named profile
from the configuration file.
Part of the provided profiles.xml file showing the parameters for
transport on foot is shown below:
<?xml version="1.0" encoding="UTF-8" ?>
<routino-profiles>
<profile name="foot" transport="foot">
<speeds>
...
<speed highway="cycleway" kph="4" />
<speed highway="path" kph="4" />
<speed highway="steps" kph="4" />
</speeds>
<preferences>
...
<preference highway="cycleway" percent="95" />
<preference highway="path" percent="100" />
<preference highway="steps" percent="80" />
</preferences>
<properties>
<property type="paved" percent="50" />
<property type="multilane" percent="25" />
<property type="bridge" percent="50" />
<property type="tunnel" percent="50" />
</properties>
<restrictions>
<oneway obey="0" />
<weight limit="0.0" />
<height limit="0.0" />
<width limit="0.0" />
<length limit="0.0" />
</restrictions>
</profile>
<profile name="horse" transport="horse">
...
</profile>
...
</routino-profiles>
Output Translations
-------------------
The default name of the output translations XML configuration file is
translations.xml in the same directory as the database files. Other
filenames can be specified on the command line using the --translations
option.
The generated HTML and GPX output files (described in the next section)
are created using the fragments of text that are defined in this file.
Additional languages can be added to the file and are selected using
the --language option to the router. If no language is specified the
first one in the file is used.
Part of the provided translations.xml file showing some of the English
language (en) translations is shown below:
<?xml version="1.0" encoding="utf-8"?>
<routino-translations>
<language lang="en">
...
<turn direction="-4" string="Very sharp left" />
<turn direction="-3" string="Sharp left" />
<turn direction="-2" string="Left" />
...
<heading direction="-4" string="South" />
<heading direction="-3" string="South-West" />
<heading direction="-2" string="West" />
...
<route type="shortest" string="Shortest" />
<route type="quickest" string="Quickest" />
<output-html>
...
</output-html>
<output-gpx>
...
</output-gpx>
</language>
</routino-translations>
--------
Copyright 2010 Andrew M. Bishop.
Routino : Data
==============
A router relies on data to be able to find a route.
OpenStreetMap Data
------------------
The data that is collected by the OpenStreetMap project consists of
nodes, ways and relations.
Node
A node is a point that has a latitude and longitude and
attributes that describe what type of point it is (part of a way
or a place of interest for example).
Way
A way is a collection of nodes that when joined together define
something (for example a road, a ralway, a boundary, a building,
a lake etc). The ways also have attributes that define them
(speed limits, type of road and restrictions for example).
Relation
A relation is a collection of items (usually ways) that are
related to each other for some reason (highways that make up a
route for example).
The OpenStreetMap Wiki explains the data much better than I can.
Router Data
-----------
The information that is needed by a routing algorithm is only a subset
of the information that is collected by the OpenStreetMap project. For
routing what is required is information about the location of roads (or
other highways), the connections between the highways and the
properties of those highways.
Location of highways (nodes)
The locations of things is provided by the nodes from the
OpenStreetMap data. The nodes are the only things that have
coordinates in OpenStreetMap and everything else is made up by
reference to them. Not all of the nodes are useful, only the
ones that are part of highways. The location of the nodes is
stored but none of the other attributes are currently used by
the router.
Location of highways (ways)
The location of the highways is defined in the OpenStreetMap
data by the ways. Only the highway ways are useful and the other
ways are discarded. What remains is lists of nodes that join
together to form a section of highway. This is further split
into segments which are individual parts of a way connected by
two nodes.
Properties of highways (tags)
The ways that belong to highways are extracted from the data in
the previous step and for each way the useful information for
routing is stored. For the router the useful information is the
type of highway, the speed limit, the allowed types of transport
and other restrictions (one-way, min height, max weight etc).
Connections between highways
The connections between highways are defined in the
OpenStreetMap data by ways that share nodes. Since the ways may
join in the middle and not just the ends it is the segments
defined above that are not part of the OpenStreetMap data that
are most important.
The information that is extracted from the OpenStreetMap data is stored
in an optimised way that allows the routing to be performed quickly.
Interpreting Data Tags
----------------------
The tags are the information that is attached to the nodes and ways in
OpenStreetMap. The router needs to interpret these tags and use them
when deciding what type of traffic can use a highway (for example).
There are no well defined rules in OpenStreetMap about tagging, but
there is guidance on the OpenStreetMap Wiki "Map_Features" page. This
describes a set of recommended tags but these are not universally used
so it is up to each application how to interpret them.
The tagging rules that the router uses are very important in
controlling how the router works. With Routino the data tags can be
modified when the data is imported to allow customisation of the
information used for routing.
Problems With OpenStreetMap Data
--------------------------------
The route that can be found is only as good as the data that is
available. This is not intended as a criticism of the OpenStreetMap
data; it is generally good.
There are some problems that are well known and which affect the
router. For example highways might be missing because nobody has mapped
them. A highway may be wrongly tagged with incorrect properties, or a
highway might be missing important tags for routing (e.g. speed
limits). There can also be problems with highways that should join but
don't because they do not share nodes.
A lot of these problems can be found using the interactive data
visualiser that uses the same Routino rouing database.
--------
Copyright 2008-2010 Andrew M. Bishop.
Routino : Installation
======================
Compilation
-----------
This program has been written to run on Linux, no cross-platform
compatibility has been specifically included but on the other hand
nothing platform specific has been knowingly included either.
Any information on improving the compilation process on anything other
than 32-bit x86 Linux is welcome.
No external libraries are required and the programs are written in
standard C language.
To compile the programs just type 'make'.
Installation
------------
After compilation the executable files are copied into the directory
web/bin and the default XML configuration files are copied into the
directory web/data. This is in preparation for using the supplied
example web pages but is also a useful location to copy the files from
for normal use.
The executable files are called 'planetsplitter', 'router' and 'filedumper'
(also 'tagmodifier' for debugging tag modifications). They can be copied
to any location and need no special installation environment.
The default configuration files are called 'profiles.xml', 'tagging.xml'
and 'translations.xml'. The names of the configuration files can be
specified on the command line but by default are also looked for in the
directory that contains the routing database.
Example Web Page
----------------
The directory 'web' contains a set of files that can be used to create a
working set of web pages with interfaces to the routing algorithm.
The files in the 'web' directory will require copying to a location that
is accessible by a web server. After copying the files some of them
need to be edited; search through the files for lines that contain the
words "EDIT THIS" and make appropriate edits. The files that need
editing are 'paths.pl' (to set the directory paths) and 'router.js' and
'visualiser.js' to limit the range of the visible map (latitude,
longitude and zoom).
Configuration of web files
--------------------------
The assumption in this description is that the whole of the directory
called web is copied into a directory that is accessible by an Apache
web server.
**************************************************************************
**** This is not a secure configuration but an easy one to configure. ****
**** Only the directory 'www' should be accessible by the web server. ****
**** Do not use this configuration unmodified in a public web server. ****
**************************************************************************
The directory structure is as follows:
web/
|
+ /bin/ <- The Routino executable files (when compiled).
|
+ /data/ <- The Routino database and default configuration
| files.
|
+ /results/ <- An empty directory to store the results.
|
+ /www/ <- The files that must be available to the web
| server are below this level.
|
+ /openlayers/ <- A directory to hold the OpenLayers scripts.
|
+ /routino/ <- The main HTML, Javascript, CSS and CGI files.
The directory 'bin' will be filled by running the compilation process.
For a secure installation the 'bin' directory should be outside of the
web server, the file 'www/routino/paths.pl' contains the path to the 'bin'
directory.
The directory 'data' must contain the Routino database and is also the
default location for the configuration files. The routing database is
created by downloading the OSM files for the region of interest and
running the 'planetsplitter' program. There is a script in the directory
that will download the OSM files and create the required database. The
script should be edited to set the names of the files to be downloaded.
For a secure installation the 'data' directory should be outside of the
web server, the file 'www/routino/paths.pl' contains the path to the 'data'
directory.
The directory 'results' is a temporary directory that it used to hold the
GPX and text files generated by the Routino router. The directory must
be writable by the web server process since it is the CGI scripts that
are run by the web server that writes the results here. For a secure
installation the results directory should be outside of the web server,
the file 'www/routino/paths.pl' contains the path to the results
directory.
The directory 'www' and its sub-directories are the only ones that need
to be within the web server accessible directory.
The directory 'www/openlayers' must be filled with the openlayers
Javascript library that can be downloaded from
http://www.openlayers.org/. (This version of Routino has been tested
with OpenLayers library version 2.8). The files must be installed so
that the file 'www/openlayers/OpenLayers.js' and the directories
'www/openlayers/img/', 'www/openlayers/theme/' all exist. There is a script
in the directory that will automatically download and organise the
files.
The directory 'www/routino' contains the main HTML, Javascript and CSS
files as well as the CGI scripts that perform the server-side
functions. The description below lists all of the files that contain
editable information.
paths.pl
This contains the names of the directories that contain the
executable files, router database and temporary results.
router.pl
This file contains the filename prefix for the routing database
files (only needed if planetsplitter is run with the --prefix
option).
router.js
The parameters in this file control the boundary of the visible
map (defaults to UK), the minimum and maximum zoom levels
(defaults to between 4 and 15 inclusive) and the source of map
tiles (defaults to the main OpenStreetMap tile server).
visualiser.js
The same parameters as in router.js are in this file.
Configuration of web server
---------------------------
The file 'www/routino/.htaccess' contains all of the Apache configuration
options that are required to get the example web pages running. The
only problem is that because of the way that the "AllowOverride" option
works one of the configuration options has been commented out. This
must be enabled in the main Apache server configuration file.
--------
Copyright 2008-2010 Andrew M. Bishop.
# $Header: /home/amb/routino/doc/RCS/Makefile,v 1.2 2010/07/07 17:27:03 amb Exp $
#
# Documentation directory Makefile
#
# Part of the Routino routing software.
#
# This file Copyright 2010 Andrew M. Bishop
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.