Program Usage
=============
Program Usage
There are three programs that make up this software. The first one
takes the planet.osm datafile from OpenStreetMap (or other source of
data using the same formats) and converts it into a local database. The
second program uses the database to determine an optimum route between
two points. The third program allows visualisation of the data and
statistics to be extracted.
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 (see the router for the list of possible transport
types).
--not-highway=<highway>
Allows particular types of highways to be ignored, <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
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=]<longitude> [--lat1=]<latitude>
[--lon2=]<longitude> [--lon2=]<latitude>
[ ... [--lon9=]<longitude> [--lon9=]<latitude> ]
[--help | --help-profile | --help-profile-js | --help-profile-pl]
[--dir=<name>] [--prefix=<name>]
[--shortest | --quickest]
[--all | --super]
[--no-output] [--quiet]
[--transport=<transport>]
[--highway-<highway>=<preference> ...]
[--speed-<highway>=<speed> ...]
[--oneway=[0|1]]
[--weight=<weight>]
[--height=<height>] [--width=<width>] [--length=<length>]
--lon1=<longitude>, --lat1=<latitude>
--lon2=<longitude>, --lat2=<latitude>
...
--lon9=<longitude>, --lat9=<latitude>
The location of the points that make up the start, middle and
end points of the route. Up to 9 points can be specified and the
route will pass through each of the specified ones in sequence.
--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 read the local database.
Defaults to the current directory.
--prefix=<name>
Sets the filename prefix for the files in the local database.
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, <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)
Defaults to 'Motorcar', this option also selects the default
profile information.
--highway-<highway>=<preference>
Selects the percentage preference for using each particular type
of highway (see the planetsplitter for the list of highway
types). Default value depends on the profile selected by the
--transport option.
--speed-<highway>=<speed>
Selects the speed limit in km/hour 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 in tonnes, 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 in metres, 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 in metres, 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 in metres, 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.
If there is a file in the specified directory with the specified prefix
and a basename of "copyright.txt" (i.e. 'data/gb-copyright.txt' in the
example) this file will be read in and the contents used in the
generated files. The file is read in and the two lines starting with
'Source:' and 'License:' are extracted and used in the output files.
An appropriate file for use with data derived from OpenStreetMap data
would be the following:
Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
License: http://creativecommons.org/licenses/by-sa/2.0/
filedumper
Usage: filedumper
[--help]
[--dir=<name>] [--prefix=<name>]
[--statistics]
[--visualiser --latmin=<latmin> --latmax=<latmax>
--lonmin=<lonmin> --lonmax=<lonmax>
--data=<data-type>]
--help
Prints out the help information.
--dir=<name>
Sets the directory name in which to read the local database.
Defaults to the current directory.
--prefix=<name>
Sets the filename prefix for the files in the local database.
--statistics
Prints out statistics about the database files.
--visualiser
Selects a data visualiser mode which will output a set of data
according to the other parameters below.
--latmin=<latmin> --latmax=<latmax>
The range of latitudes to print the data for.
--lonmin=<lonmin> --lonmax=<lonmax>
The range of longitudes to print the data for.
--data=<data-type>
The type of data to output, <data-type> can be selected
from:
o junctions = segment count at each junction.
o super = super-node and super-segments.
o oneway = oneway segments.
o speed = speed limits.
o weight = weight limits.
o height = height limits.
o width = width limits.
o length = length limits.
Router Output
There are two different formats of output from the router, plain text
and GPX (GPS eXchange) XML format. There are a total of four possible
outputs from the router program: a GPX track file, a GPX route file
with waypoints at junctions, 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-track.gpx",
"shortest-route.gpx", "shortest.txt" and "shortest-all.txt", for the
quickest route the names are "quickest-track.gpx",
"quickest-route.gpx", "quickest.txt" and "quickest-all.txt".
GPX Track File
The GPX track file contains a track with all of the individual nodes
that the route passes through.
An example GPX track file output is below:
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="Routino"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.topografix.com/GPX/1/1"
xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
<metadata>
<desc><![CDATA[Shortest route between 'start' and 'finish' waypoints]]></desc>
<copyright author="Based on OpenStreetMap data from http://www.openstreetmap.org/">
<license>http://creativecommons.org/licenses/by-sa/2.0/</license>
</copyright>
</metadata>
<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>
GPX Route File
The GPX route file contains a route (ordered set of waypoints) with all
of the junctions that the route passes through.
An example GPX route file output is below:
<?xml version="1.0" encoding="UTF-8"?>
<gpx version="1.1" creator="Routino"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.topografix.com/GPX/1/1"
xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
<metadata>
<desc><![CDATA[Shortest route between 'start' and 'finish' waypoints]]></desc>
<copyright author="Based on OpenStreetMap data from http://www.openstreetmap.org/">
<license>http://creativecommons.org/licenses/by-sa/2.0/</license>
</copyright>
</metadata>
<rte>
<name>Shortest route</name>
<rtept lat="51.524676" lon="-0.127896"><name>START</name></rtept>
<rtept lat="51.523829" lon="-0.126993"><name>TRIP001</name></rtept>
...
<rtept lat="51.480314" lon="-0.108381"><name>TRIP015</name></rtept>
<rtept lat="51.478244" lon="-0.103652"><name>FINISH</name></rtept>
</rte>
</gpx>
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:
# Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
# License: http://creativecommons.org/licenses/by-sa/2.0/
#
#Latitude Longitude Segment Segment Total Total Highway
# Distance Duration Distance Durat'n
51.524676 -0.127896 0.000 km 0.0 min 0.0 km 0 min
51.523829 -0.126993 0.113 km 0.1 min 0.1 km 0 min Woburn Place
...
51.480314 -0.108381 0.200 km 0.1 min 5.9 km 5 min Camberwell New Road (A202)
51.478244 -0.103652 0.411 km 0.3 min 6.3 km 5 min Vassall Road
The text file output contains a header (indicated by the lines starting
with '#') and then one line for each junction. Each line contains the
information for the route up to that point. 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 each of the nodes
on the route.
An example all nodes text file output is below:
# Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
# License: http://creativecommons.org/licenses/by-sa/2.0/
#
#Latitude Longitude Node Segment Segment Total Total Speed Highway
# Dist Durat'n Dist Durat'n
51.524676 -0.127896 4830582* 0.000 0.00 0.00 0.0
51.523829 -0.126993 4830562* 0.113 0.14 0.11 0.1 96 Woburn Place
...
51.478354 -0.103561 4904816* 0.104 0.07 6.30 5.1 96 Camberwell New Road (A202)
51.478244 -0.103652 4908481 0.013 0.01 6.31 5.1 64 Vassall Road
The all 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.