Program Usage
=============
Program Usage
There are two programs that make up this software. The first one takes
the planet.osm datafile from OpenStreetMap and converts it into a local
database. The second program uses the database to determine an optimum
route between two points.
planetsplitter
Usage: planetsplitter
[--help]
[--dir=<name>] [--prefix=<name>]
[--max-iterations=<number>]
[--transport=<transport>]
[--not-highway=<highway> ...]
--help
Prints out the help information.
--dir=<name>
Sets the directory name in which to save the results. Defaults
to the current directory.
--prefix=<name>
Sets the filename prefix for the files that are created.
Defaults to no prefix.
--max-iterations=<number>
The maximum number of iterations to use when generating
super-nodes and super-segments. Defaults to 10 which is normally
enough.
--transport=<transport>
Allows selection of only the routes that are possible for a
particular type of transport. Defaults to all transport types
allowed.
--not-highway=<highway>
Allows particular types of highways to be ignored. Defaults to
all highway types allowed. This option may be repeated.
Example usage:
bunzip2 -c great_britain.osm.bz2 | ./planetsplitter --dir=data --prefix=gb
This will generate the output files 'data/gb-nodes.mem',
'data/gb-segments.mem' and 'data/gb-ways.mem'.
router
Usage: router [--lon1=]<start-lon> [--lat1=]<start-lat>
[--lon2=]<finish-lon> [--lon2=]<finish-lat>
[--help | --help-profile | --help-profile-js | --help-profile-pl]
[--dir=<name>] [--prefix=<name>]
[--shortest | --quickest]
[--all | --super]
[--no-output] [--quiet]
[--transport=<transport>]
[--highway-<highway>=[0|1] ...]
[--speed-<highway>=<speed> ...]
[--oneway=[0|1]]
[--weight=<weight>]
[--height=<height>] [--width=<width>] [--length=<length>]
--lon1=<start-lon>, --lat1=<start-lat>
The location of the starting point. If the --lon1 and --lat1
prefixes are not used then these must be the first and second
options.
--lon2=<finish-lon>, --lat2=<finish-lat>
The location of the finishing point. If the --lon2 and --lat2
prefixes are not used then these must be the third and fourth
options.
--help
Prints out the help information.
--help-profile
Prints out the selected transport profile (type, speed limits,
highway preferences etc.)
--help-profile-js
Prints out all the compiled-in profiles as a set of Javascript
arrays for use in the interactive webpage.
--help-profile-pl
Prints out all the compiled-in profiles as a set of Perl arrays
for use in the router CGI.
--dir=<name>
Sets the directory name in which to save the results. Defaults
to the current directory.
--prefix=<name>
Sets the filename prefix for the files that are created.
Defaults to no prefix.
--shortest
Find the shortest route.
--quickest
Find the quickest route.
--all
Find the route using all nodes and segments, not using
super-nodes and super-segments (useful for debugging only).
--super
Find the route using only super-nodes and super-segments, not
using normal nodes and segments (useful for debugging only).
--no-output
Don't generate any output files (useful for debugging).
--quiet
Don't generate any screen output while running (useful for
running in a script).
--transport=<transport>
Select the type of transport to use. Defaults to 'Motorcar',
this option also selects the default profile.
--highway-<highway>=[0|1]
Selects the preference for using each particular type of
highway. Default value depends on the profile selected by the
--transport option.
--speed-<highway>=<speed>
Selects the speed limit for each type of highway. Default value
depends on the profile selected by the --transport option.
--oneway=[0|1]
Selects if the direction of oneway streets are to be obeyed
(useful to not obey them when walking). Default value depends on
the profile selected by the --transport option.
--weight=<weight>
Specifies the weight of the mode of transport, ensures that the
weight limit on the highway is not exceeded. Default value
depends on the profile selected by the --transport option.
--height=<height>
Specifies the height of the mode of transport, ensures that the
height limit on the highway is not exceeded. Default value
depends on the profile selected by the --transport option.
--width=<width>
Specifies the width of the mode of transport, ensures that the
width limit on the highway is not exceeded. Default value
depends on the profile selected by the --transport option.
--length=<length>
Specifies the length of the mode of transport, ensures that the
length limit on the highway is not exceeded. Default value
depends on the profile selected by the --transport option.
Example usage (motorbike journey, scenic route, not very fast):
./router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
--highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest
This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
'data/gb-ways.mem' to find the quickest route by motorbike not using
motorways or trunk roads and not exceeding 80 km/hr.
Common Parameters
There are a number of parameters that are used by both programs or are used
to specify a quantity or choice. These are defined below.
<transport> can be set to:
* foot = Foot
* bicycle = Bicycle
* horse = Horse
* motorbike = Motorbike
* motorcar = Motorcar
* goods = Goods (Small lorry, van)
* hgv = HGV (Heavy Goods Vehicle - large lorry)
* psv = PSV (Public Service Vehicle - bus, coach)
<highway> can be selected from:
* motorway = Motorway
* trunk = Trunk
* primary = Primary
* secondary = Secondary
* tertiary = Tertiary
* unclassified = Unclassified
* residential = Residential
* service = Service
* track = Track
* path = Path
* bridleway = Bridleway
* cycleway = Cycleway
* footway = Footway
<speed> is a speed in km/hour.
<weight> is a weight in tonnes.
<height>, <width>, <length> are dimensions in metres.
Program Output
There are three possible formats of output from the router program: A
GPX track file, a text description with the junctions and a text file
with every node.
The output files are written to the current directory and are named
depending on the selection of shortest or quickest route. For the
shortest route the file names are "shortest.gpx", "shortest.txt" and
"shortest-all.txt", for the quickest route the names are
"quickest.gpx", "quickest.txt" and "quickest-all.txt".
GPX File
The GPX (GPS eXchange) XML format file contains a track with all of
the individual nodes that the route passes through.
An example GPX file output is below:
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.0" creator="Routino"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.topografix.com/GPX/1/0"
xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
<trk>
<trkseg>
<trkpt lat="51.524676" lon="-0.127896"/>
<trkpt lat="51.523829" lon="-0.126993"/>
...
<trkpt lat="51.478354" lon="-0.103561"/>
<trkpt lat="51.478244" lon="-0.103652"/>
</trkseg>
</trk>
</gpx>
There are several programs that can interpret GPX files and the format
is easy to interpret if just the latitude and longitude values are
required.
Text File
The text file format contains one entry for all of the junctions in the
route and is intended to be easy to interpret.
An example Text file output is below:
#Latitude Longitude Segment Segment Total Total Highway
# Distance Duration Distance Durat'n
51.5247 -0.1279 0.000 km 0.0 min 0.0 km 0 min
51.5238 -0.1270 0.113 km 0.1 min 0.1 km 0 min Woburn Place
51.5227 -0.1257 0.153 km 0.2 min 0.3 km 0 min Russell Square
51.5209 -0.1233 0.261 km 0.3 min 0.5 km 1 min Southampton Row
51.5171 -0.1201 0.482 km 0.6 min 1.0 km 1 min Kingsway
51.5133 -0.1167 0.525 km 0.7 min 1.5 km 2 min Aldwych
The text file output contains a header (indicated by the lines starting
with '#' and then one line for each junction. For each of the lines the
latitude and longitude are the first two items. The length of the
segment in km and the journey duration for the segment in minutes are
the next two items. The cumulative journey distance and duration are
the 6th and 7th items and the final item is the name of the highway.
The individual items are separated by tabs but some of the items
contain spaces as well.
All Nodes Text File
The all nodes text file format contains one entry for all of the nodes
on the route.
An example all nodes text file output is below:
#Latitude Longitude Node Segment Segment Total Total Speed Highway
# Dist Durat'n Dist Durat'n
51.5247 -0.1279 4830582* 0.000 0.00 0.00 0.0
51.5238 -0.1270 4830562* 0.113 0.14 0.11 0.1 96 Woburn Place
51.5228 -0.1259 4831566* 0.138 0.17 0.25 0.3 96 Woburn Place
51.5227 -0.1257 4836497* 0.015 0.02 0.27 0.3 96 Russell Square
51.5221 -0.1250 4830548* 0.081 0.10 0.35 0.4 96 Russell Square
The nodes text file output is similar to the text file output except
that a line is printed for each of the nodes rather than just the
junctions. The additional information on each line is the node number
(not the OpenStreetMap node number but an internal value) as well as an
indicator for the super-nodes and the speed for the segment.
--------
Copyright 2008,2009 Andrew M. Bishop.