trunk/doc/USAGE.txt

                                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>]
                         [--slim] [--tmpdir=<name>]
                         [--max-iterations=<number>]
                         [--transport=<transport> ...]
                         [--not-highway=<highway> ...]
                         [--not-property=<property> ...]

   --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.

   --slim
          Selects a mode of operation that uses less memory and will
          therefore work where virtual memory is very limited or
          unavailable. Selecting this option will cause raw data to be
          held in disk files with only indexes in RAM. Not using this
          option will still use disk files but only for sequential access
          and the files are memory mapped for random access.

   --tmpdir=<name>
          Specifies the name of the directory to store the temporary disk
          files. If not specified then it defaults to either the value of
          the --dir option or the current directory.

   --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
          particular types of transport. Defaults to all transport types
          allowed (see the router for the list of possible transport
          types), this option may be repeated for additional transport
          types.

   --not-highway=<highway>
          Allows particular types of highways to be ignored to produce a
          smaller database or one that is more specific to a particular
          application (e.g. motorcar routing does not need footpaths).
          Defaults to all highway types allowed (see the router for the
          list of possible highway types), this option may be repeated for
          additional highway types.

   --not-property=<property>
          Allows particular highway properties to be ignored to produce a
          smaller database or one that is more specific to a particular
          application. Defaults to all highway properties allowed (see the
          router for the list of possible highway properties), this option
          may be repeated for additional highway properties.

   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>
                 [ ... [--lon99=]<longitude> [--lon99=]<latitude> ]
                 [--help | --help-profile | --help-profile-js | --help-profile-pl]
                 [--dir=<name>] [--prefix=<name>]
                 [--shortest | --quickest]
                 [--exact-nodes-only]
                 [--quiet]
                 [--transport=<transport>]
                 [--highway-<highway>=<preference> ...]
                 [--speed-<highway>=<speed> ...]
                 [--property-<property>=<preference> ...]
                 [--oneway=[0|1]]
                 [--weight=<weight>]
                 [--height=<height>] [--width=<width>] [--length=<length>]

   --lon1=<longitude>, --lat1=<latitude>
   --lon2=<longitude>, --lat2=<latitude>
   ...
   --lon99=<longitude>, --lat99=<latitude>
          The location of the points that make up the start, middle and
          end points of the route. Up to 99 points can be specified and
          the route will pass through each of the specified ones in
          sequence. The algorithm will find the closest node or point
          within a segment that allows the specified traffic type.

   --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.

   --exact-nodes-only
          When processing the specified latitude and longitude points only
          select the nearest node instead of finding the nearest point
          within a segment.

   --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
          + horse = Horse
          + wheelchair = Wheelchair
          + bicycle = Bicycle
          + moped = Moped (Small motorbike, limited speed)
          + 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. The value of <highway> can be selected from:

          + motorway = Motorway
          + trunk = Trunk
          + primary = Primary
          + secondary = Secondary
          + tertiary = Tertiary
          + unclassified = Unclassified
          + residential = Residential
          + service = Service
          + track = Track
          + cycleway = Cycleway
          + path = Path
          + steps = Steps

          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.

   --property-<property>=<preference>
          Selects the percentage preference for using each particular
          highway property The value of <property> can be selected from:

          + paved = Paved (suitable for normal wheels)
          + multilane = Multiple lanes
          + bridge = Bridge
          + tunnel = Tunnel

          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.

   The meaning of the <preference> parameter in the command line options
   is slightly different for the highway preferences and the property
   preferences. For the highway preference consider the choice between two
   possible highways between the start and finish when looking for the
   shortest route. If highway A has a preference of 100% and highway B has
   a preference of 90% then highway A will be chosen even if it is up to
   11% longer (100/90 = 111%). For the highway properties each highway
   either has a particular property or not. If the preference for highways
   with the property is 60% then the preference for highways without the
   property is 40%. The overall preference for the highway is the product
   of the highway preference and the preference for highways with (or
   without) each property that the highway has (or doesn't have).

   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>]
                     [--dump --node=<node> ...
                             --segment=<segment> ...
                             --way=<way> ...]

   --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.

   --dump
          Selects a data dumping mode which allows looking at individual
          items in the databases.

        --node=<node>
                Prints the information about the selected node number
                (internal number, not the node id number in the original
                source file).

        --segment=<segment>
                Prints the information about the selected segment number.

        --way=<way>
                Prints the information about the selected way number
                (internal number, not the way id number in the original
                source file).


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  Section   Section   Total     Total   Point Turn Bearing Highway
#                      Distance  Duration  Distance  Durat'n Type

 51.524676  -0.127896  0.000 km   0.0 min  0.0 km    0 min   Waypt       +3
 51.523829  -0.126993  0.113 km   0.1 min  0.1 km    0 min   Junct  +0   +3     Woburn Place
...
 51.480314  -0.108381  0.200 km   0.1 min  5.9 km    5 min   Junct  +0   +3     Camberwell New Road (A202)
 51.478244  -0.103652  0.411 km   0.3 min  6.3 km    5 min   Waypt              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 and the direction to go
   next. For each of the lines the individual fields contain the
   following:

   Latitude - Location of the point (degrees)

   Longitude - Location of the point (degrees)

   Section Distance - The distance travelled on the section of the journey
   that ends at this point (defined on this line).

   Section Duration - The duration of travel on the section of the journey
   that ends at this point (defined on this line).

   Total Distance - The total distance travelled up to this point.

   Total Duration - The total duration of travel up to this point.

   Point Type - The type of point; either a waypoint Waypt or junction
   Junct.

   Turn - The direction to turn at this point (missing for the first point
   since the journey has not started yet and the last point because it has
   finished). This can take one of nine values between -4 and +4 defined
   by: 0 = Straight, +2 = Right, -2 = Left and +/-4 = Reverse.

   Bearing - The direction to head at this point (missing for the last point
   since the journey has finished). This can take one of nine values
   between -4 and +4 defined by: 0 = North, +2 = East, -2 = West and +/-4
   = South.

   Highway - The name (or description) of the highway to follow (missing on
   the first line).

   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    Type  Segment Segment Total  Total   Speed Bearing Highway
#                                      Dist Durat'n Dist   Durat'n                

 51.524676 -0.127896  483058* Waypt 0.000    0.00    0.00    0.0
 51.523829 -0.126993  483056* Junct 0.113    0.14    0.11    0.1    96    135    Woburn Place
...
 51.478354 -0.103561  490481* Junct 0.104    0.07    6.30    5.1    96    180    Camberwell New Road (A202)
 51.478244 -0.103652  490848  Waypt 0.013    0.01    6.31    5.1    64    90     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. For each of the lines the individual fields contain the
   following:

   Latitude - Location of the point in degrees.

   Longitude - Location of the point in degrees.

   Node - The internal node number and an indicator "*" if the node is a
   super-node.

   Type - The type of point; a waypoint Waypt, junction Junct, change of
   highway Change or intermediate node Inter.

   Segment Distance - The distance travelled on the segment defined on this
   line.

   Segment Duration - The duration of travel on the segment defined on this
   line.

   Total Distance - The total distance travelled up to this point.

   Total Duration - The total duration of travel up to this point.

   Speed - The speed of travel on the segment defined on this line (missing
   on the first line).

   Bearing - The direction that the segment defined on this line travels in
   degrees (missing on the first line).

   Highway - The name (or description) of the highway segment (missing on
   the first line).


--------

Copyright 2008,2009,2010 Andrew M. Bishop.
1	amb	152	Program Usage
2			=============
3
4	amb	155	Program Usage
5	amb	318	-------------
6	amb	152
7	amb	191	There are three programs that make up this software. The first one
8			takes the planet.osm datafile from OpenStreetMap (or other source of
9			data using the same formats) and converts it into a local database. The
10			second program uses the database to determine an optimum route between
11			two points. The third program allows visualisation of the data and
12			statistics to be extracted.
13	amb	152
14	amb	318
15	amb	152	planetsplitter
16	amb	318	--------------
17	amb	152
18			Usage: planetsplitter
19			[--help]
20	amb	318	[--dir=<name>] [--prefix=<name>]
21	amb	288	[--slim] [--tmpdir=<name>]
22	amb	152	[--max-iterations=<number>]
23	amb	318	[--transport=<transport> ...]
24	amb	152	[--not-highway=<highway> ...]
25	amb	318	[--not-property=<property> ...]
26	amb	152
27			--help
28			Prints out the help information.
29
30			--dir=<name>
31			Sets the directory name in which to save the results. Defaults
32			to the current directory.
33
34			--prefix=<name>
35			Sets the filename prefix for the files that are created.
36			Defaults to no prefix.
37
38	amb	288	--slim
39			Selects a mode of operation that uses less memory and will
40			therefore work where virtual memory is very limited or
41			unavailable. Selecting this option will cause raw data to be
42			held in disk files with only indexes in RAM. Not using this
43			option will still use disk files but only for sequential access
44			and the files are memory mapped for random access.
45
46			--tmpdir=<name>
47			Specifies the name of the directory to store the temporary disk
48			files. If not specified then it defaults to either the value of
49			the --dir option or the current directory.
50
51	amb	318	--max-iterations=<number>
52			The maximum number of iterations to use when generating
53			super-nodes and super-segments. Defaults to 10 which is normally
54			enough.
55
56			--transport=<transport>
57			Allows selection of only the routes that are possible for
58			particular types of transport. Defaults to all transport types
59			allowed (see the router for the list of possible transport
60			types), this option may be repeated for additional transport
61			types.
62
63			--not-highway=<highway>
64			Allows particular types of highways to be ignored to produce a
65			smaller database or one that is more specific to a particular
66			application (e.g. motorcar routing does not need footpaths).
67			Defaults to all highway types allowed (see the router for the
68			list of possible highway types), this option may be repeated for
69			additional highway types.
70
71			--not-property=<property>
72			Allows particular highway properties to be ignored to produce a
73			smaller database or one that is more specific to a particular
74			application. Defaults to all highway properties allowed (see the
75			router for the list of possible highway properties), this option
76			may be repeated for additional highway properties.
77
78	amb	152	Example usage:
79	amb	318	bunzip2 -c great_britain.osm.bz2 \| ./planetsplitter --dir=data --prefix=gb
80	amb	180
81	amb	152	This will generate the output files 'data/gb-nodes.mem',
82			'data/gb-segments.mem' and 'data/gb-ways.mem'.
83
84	amb	318
85	amb	152	router
86	amb	318	------
87	amb	152
88	amb	180	Usage: router [--lon1=]<longitude> [--lat1=]<latitude>
89			[--lon2=]<longitude> [--lon2=]<latitude>
90	amb	288	[ ... [--lon99=]<longitude> [--lon99=]<latitude> ]
91	amb	152	[--help \| --help-profile \| --help-profile-js \| --help-profile-pl]
92			[--dir=<name>] [--prefix=<name>]
93			[--shortest \| --quickest]
94	amb	318	[--exact-nodes-only]
95	amb	288	[--quiet]
96	amb	152	[--transport=<transport>]
97	amb	180	[--highway-<highway>=<preference> ...]
98	amb	152	[--speed-<highway>=<speed> ...]
99	amb	318	[--property-<property>=<preference> ...]
100	amb	152	[--oneway=[0\|1]]
101			[--weight=<weight>]
102			[--height=<height>] [--width=<width>] [--length=<length>]
103
104	amb	180	--lon1=<longitude>, --lat1=<latitude>
105			--lon2=<longitude>, --lat2=<latitude>
106			...
107	amb	288	--lon99=<longitude>, --lat99=<latitude>
108	amb	180	The location of the points that make up the start, middle and
109	amb	318	end points of the route. Up to 99 points can be specified and
110			the route will pass through each of the specified ones in
111			sequence. The algorithm will find the closest node or point
112			within a segment that allows the specified traffic type.
113	amb	152
114			--help
115			Prints out the help information.
116
117			--help-profile
118			Prints out the selected transport profile (type, speed limits,
119			highway preferences etc.)
120
121			--help-profile-js
122			Prints out all the compiled-in profiles as a set of Javascript
123			arrays for use in the interactive webpage.
124
125			--help-profile-pl
126			Prints out all the compiled-in profiles as a set of Perl arrays
127			for use in the router CGI.
128
129			--dir=<name>
130	amb	191	Sets the directory name in which to read the local database.
131			Defaults to the current directory.
132	amb	152
133			--prefix=<name>
134	amb	191	Sets the filename prefix for the files in the local database.
135	amb	152	Defaults to no prefix.
136
137			--shortest
138			Find the shortest route.
139
140			--quickest
141			Find the quickest route.
142
143	amb	318	--exact-nodes-only
144			When processing the specified latitude and longitude points only
145			select the nearest node instead of finding the nearest point
146			within a segment.
147
148	amb	152	--quiet
149			Don't generate any screen output while running (useful for
150			running in a script).
151
152			--transport=<transport>
153	amb	191	Select the type of transport to use, <transport> can be set to:
154	amb	318
155			+ foot = Foot
156			+ horse = Horse
157			+ wheelchair = Wheelchair
158			+ bicycle = Bicycle
159			+ moped = Moped (Small motorbike, limited speed)
160			+ motorbike = Motorbike
161			+ motorcar = Motorcar
162			+ goods = Goods (Small lorry, van)
163			+ hgv = HGV (Heavy Goods Vehicle - large lorry)
164			+ psv = PSV (Public Service Vehicle - bus, coach)
165
166			Defaults to 'motorcar', this option also selects the default
167	amb	191	profile information.
168	amb	152
169	amb	180	--highway-<highway>=<preference>
170			Selects the percentage preference for using each particular type
171	amb	318	of highway. The value of <highway> can be selected from:
172	amb	152
173	amb	318	+ motorway = Motorway
174			+ trunk = Trunk
175			+ primary = Primary
176			+ secondary = Secondary
177			+ tertiary = Tertiary
178			+ unclassified = Unclassified
179			+ residential = Residential
180			+ service = Service
181			+ track = Track
182			+ cycleway = Cycleway
183			+ path = Path
184			+ steps = Steps
185
186			Default value depends on the profile selected by the --transport
187			option.
188
189	amb	152	--speed-<highway>=<speed>
190	amb	191	Selects the speed limit in km/hour for each type of highway.
191			Default value depends on the profile selected by the --transport
192			option.
193	amb	152
194	amb	318	--property-<property>=<preference>
195			Selects the percentage preference for using each particular
196			highway property The value of <property> can be selected from:
197
198			+ paved = Paved (suitable for normal wheels)
199			+ multilane = Multiple lanes
200			+ bridge = Bridge
201			+ tunnel = Tunnel
202
203			Default value depends on the profile selected by the --transport
204			option.
205
206	amb	152	--oneway=[0\|1]
207			Selects if the direction of oneway streets are to be obeyed
208			(useful to not obey them when walking). Default value depends on
209			the profile selected by the --transport option.
210
211			--weight=<weight>
212	amb	318	Specifies the weight of the mode of transport in tonnes; ensures
213	amb	191	that the weight limit on the highway is not exceeded. Default
214			value depends on the profile selected by the --transport option.
215	amb	152
216			--height=<height>
217	amb	318	Specifies the height of the mode of transport in metres; ensures
218	amb	191	that the height limit on the highway is not exceeded. Default
219			value depends on the profile selected by the --transport option.
220	amb	152
221			--width=<width>
222	amb	318	Specifies the width of the mode of transport in metres; ensures
223	amb	191	that the width limit on the highway is not exceeded. Default
224			value depends on the profile selected by the --transport option.
225	amb	152
226			--length=<length>
227	amb	318	Specifies the length of the mode of transport in metres; ensures
228	amb	191	that the length limit on the highway is not exceeded. Default
229			value depends on the profile selected by the --transport option.
230	amb	152
231	amb	318	The meaning of the <preference> parameter in the command line options
232			is slightly different for the highway preferences and the property
233			preferences. For the highway preference consider the choice between two
234			possible highways between the start and finish when looking for the
235			shortest route. If highway A has a preference of 100% and highway B has
236			a preference of 90% then highway A will be chosen even if it is up to
237			11% longer (100/90 = 111%). For the highway properties each highway
238			either has a particular property or not. If the preference for highways
239			with the property is 60% then the preference for highways without the
240			property is 40%. The overall preference for the highway is the product
241			of the highway preference and the preference for highways with (or
242			without) each property that the highway has (or doesn't have).
243
244	amb	152	Example usage (motorbike journey, scenic route, not very fast):
245	amb	180
246	amb	152	./router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
247			--highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest
248
249			This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
250			'data/gb-ways.mem' to find the quickest route by motorbike not using
251			motorways or trunk roads and not exceeding 80 km/hr.
252
253	amb	180	If there is a file in the specified directory with the specified prefix
254			and a basename of "copyright.txt" (i.e. 'data/gb-copyright.txt' in the
255			example) this file will be read in and the contents used in the
256			generated files. The file is read in and the two lines starting with
257			'Source:' and 'License:' are extracted and used in the output files.
258
259			An appropriate file for use with data derived from OpenStreetMap data
260			would be the following:
261
262			Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
263			License: http://creativecommons.org/licenses/by-sa/2.0/
264
265	amb	318
266	amb	191	filedumper
267	amb	318	----------
268	amb	152
269	amb	191	Usage: filedumper
270			[--help]
271			[--dir=<name>] [--prefix=<name>]
272			[--statistics]
273			[--visualiser --latmin=<latmin> --latmax=<latmax>
274			--lonmin=<lonmin> --lonmax=<lonmax>
275			--data=<data-type>]
276	amb	288	[--dump --node=<node> ...
277			--segment=<segment> ...
278			--way=<way> ...]
279	amb	152
280	amb	191	--help
281			Prints out the help information.
282	amb	152
283	amb	191	--dir=<name>
284			Sets the directory name in which to read the local database.
285			Defaults to the current directory.
286	amb	152
287	amb	191	--prefix=<name>
288			Sets the filename prefix for the files in the local database.
289	amb	180
290	amb	191	--statistics
291			Prints out statistics about the database files.
292	amb	152
293	amb	191	--visualiser
294			Selects a data visualiser mode which will output a set of data
295			according to the other parameters below.
296	amb	152
297	amb	191	--latmin=<latmin> --latmax=<latmax>
298			The range of latitudes to print the data for.
299	amb	152
300	amb	191	--lonmin=<lonmin> --lonmax=<lonmax>
301			The range of longitudes to print the data for.
302	amb	155
303	amb	191	--data=<data-type>
304			The type of data to output, <data-type> can be selected
305			from:
306			o junctions = segment count at each junction.
307			o super = super-node and super-segments.
308			o oneway = oneway segments.
309			o speed = speed limits.
310			o weight = weight limits.
311			o height = height limits.
312			o width = width limits.
313			o length = length limits.
314	amb	155
315	amb	288	--dump
316			Selects a data dumping mode which allows looking at individual
317			items in the databases.
318	amb	191
319	amb	288	--node=<node>
320			Prints the information about the selected node number
321	amb	318	(internal number, not the node id number in the original
322	amb	288	source file).
323
324			--segment=<segment>
325			Prints the information about the selected segment number.
326
327			--way=<way>
328	amb	318	Prints the information about the selected way number
329			(internal number, not the way id number in the original
330			source file).
331	amb	288
332
333	amb	191	Router Output
334	amb	318	-------------
335	amb	191
336			There are two different formats of output from the router, plain text
337			and GPX (GPS eXchange) XML format. There are a total of four possible
338			outputs from the router program: a GPX track file, a GPX route file
339			with waypoints at junctions, a text description with the junctions and
340			a text file with every node.
341
342	amb	155	The output files are written to the current directory and are named
343			depending on the selection of shortest or quickest route. For the
344	amb	158	shortest route the file names are "shortest-track.gpx",
345			"shortest-route.gpx", "shortest.txt" and "shortest-all.txt", for the
346			quickest route the names are "quickest-track.gpx",
347			"quickest-route.gpx", "quickest.txt" and "quickest-all.txt".
348	amb	155
349	amb	318
350	amb	158	GPX Track File
351	amb	318	--------------
352	amb	155
353	amb	158	The GPX track file contains a track with all of the individual nodes
354			that the route passes through.
355	amb	155
356	amb	158	An example GPX track file output is below:
357	amb	155
358			<?xml version="1.0" encoding="UTF-8"?>
359	amb	180	<gpx version="1.1" creator="Routino"
360	amb	155	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
361	amb	180	xmlns="http://www.topografix.com/GPX/1/1"
362			xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
363			<metadata>
364			<desc><![CDATA[Shortest route between 'start' and 'finish' waypoints]]></desc>
365			<copyright author="Based on OpenStreetMap data from http://www.openstreetmap.org/">
366			<license>http://creativecommons.org/licenses/by-sa/2.0/</license>
367			</copyright>
368			</metadata>
369	amb	155	<trk>
370			<trkseg>
371			<trkpt lat="51.524676" lon="-0.127896"/>
372			<trkpt lat="51.523829" lon="-0.126993"/>
373			...
374			<trkpt lat="51.478354" lon="-0.103561"/>
375			<trkpt lat="51.478244" lon="-0.103652"/>
376			</trkseg>
377			</trk>
378			</gpx>
379
380	amb	318
381	amb	158	GPX Route File
382	amb	318	--------------
383	amb	155
384	amb	158	The GPX route file contains a route (ordered set of waypoints) with all
385			of the junctions that the route passes through.
386
387			An example GPX route file output is below:
388
389			<?xml version="1.0" encoding="UTF-8"?>
390	amb	180	<gpx version="1.1" creator="Routino"
391	amb	158	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
392	amb	180	xmlns="http://www.topografix.com/GPX/1/1"
393			xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
394			<metadata>
395			<desc><![CDATA[Shortest route between 'start' and 'finish' waypoints]]></desc>
396			<copyright author="Based on OpenStreetMap data from http://www.openstreetmap.org/">
397			<license>http://creativecommons.org/licenses/by-sa/2.0/</license>
398			</copyright>
399			</metadata>
400	amb	158	<rte>
401			<name>Shortest route</name>
402			<rtept lat="51.524676" lon="-0.127896"><name>START</name></rtept>
403			<rtept lat="51.523829" lon="-0.126993"><name>TRIP001</name></rtept>
404			...
405			<rtept lat="51.480314" lon="-0.108381"><name>TRIP015</name></rtept>
406			<rtept lat="51.478244" lon="-0.103652"><name>FINISH</name></rtept>
407			</rte>
408			</gpx>
409
410	amb	318
411	amb	155	Text File
412	amb	318	---------
413	amb	155
414			The text file format contains one entry for all of the junctions in the
415			route and is intended to be easy to interpret.
416
417	amb	318	An example text file output is below:
418	amb	155
419	amb	318	# Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
420			# License: http://creativecommons.org/licenses/by-sa/2.0/
421			#
422			#Latitude Longitude Section Section Total Total Point Turn Bearing Highway
423			# Distance Duration Distance Durat'n Type
424	amb	155
425	amb	318	51.524676 -0.127896 0.000 km 0.0 min 0.0 km 0 min Waypt +3
426			51.523829 -0.126993 0.113 km 0.1 min 0.1 km 0 min Junct +0 +3 Woburn Place
427			...
428			51.480314 -0.108381 0.200 km 0.1 min 5.9 km 5 min Junct +0 +3 Camberwell New Road (A202)
429			51.478244 -0.103652 0.411 km 0.3 min 6.3 km 5 min Waypt Vassall Road
430
431	amb	155	The text file output contains a header (indicated by the lines starting
432	amb	158	with '#') and then one line for each junction. Each line contains the
433	amb	318	information for the route up to that point and the direction to go
434			next. For each of the lines the individual fields contain the
435			following:
436
437			Latitude - Location of the point (degrees)
438
439			Longitude - Location of the point (degrees)
440
441			Section Distance - The distance travelled on the section of the journey
442			that ends at this point (defined on this line).
443
444			Section Duration - The duration of travel on the section of the journey
445			that ends at this point (defined on this line).
446
447			Total Distance - The total distance travelled up to this point.
448
449			Total Duration - The total duration of travel up to this point.
450
451			Point Type - The type of point; either a waypoint Waypt or junction
452			Junct.
453
454			Turn - The direction to turn at this point (missing for the first point
455			since the journey has not started yet and the last point because it has
456			finished). This can take one of nine values between -4 and +4 defined
457			by: 0 = Straight, +2 = Right, -2 = Left and +/-4 = Reverse.
458
459			Bearing - The direction to head at this point (missing for the last point
460			since the journey has finished). This can take one of nine values
461			between -4 and +4 defined by: 0 = North, +2 = East, -2 = West and +/-4
462			= South.
463
464			Highway - The name (or description) of the highway to follow (missing on
465			the first line).
466
467	amb	155	The individual items are separated by tabs but some of the items
468			contain spaces as well.
469
470	amb	318
471	amb	155	All Nodes Text File
472	amb	318	-------------------
473	amb	155
474	amb	158	The all nodes text file format contains one entry for each of the nodes
475	amb	155	on the route.
476
477			An example all nodes text file output is below:
478
479	amb	318	# Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
480			# License: http://creativecommons.org/licenses/by-sa/2.0/
481			#
482			#Latitude Longitude Node Type Segment Segment Total Total Speed Bearing Highway
483			# Dist Durat'n Dist Durat'n
484	amb	155
485	amb	318	51.524676 -0.127896 483058* Waypt 0.000 0.00 0.00 0.0
486			51.523829 -0.126993 483056* Junct 0.113 0.14 0.11 0.1 96 135 Woburn Place
487			...
488			51.478354 -0.103561 490481* Junct 0.104 0.07 6.30 5.1 96 180 Camberwell New Road (A202)
489			51.478244 -0.103652 490848 Waypt 0.013 0.01 6.31 5.1 64 90 Vassall Road
490	amb	155
491	amb	158	The all nodes text file output is similar to the text file output
492			except that a line is printed for each of the nodes rather than just
493	amb	318	the junctions. For each of the lines the individual fields contain the
494			following:
495	amb	155
496	amb	318	Latitude - Location of the point in degrees.
497	amb	158
498	amb	318	Longitude - Location of the point in degrees.
499
500			Node - The internal node number and an indicator "*" if the node is a
501			super-node.
502
503			Type - The type of point; a waypoint Waypt, junction Junct, change of
504			highway Change or intermediate node Inter.
505
506			Segment Distance - The distance travelled on the segment defined on this
507			line.
508
509			Segment Duration - The duration of travel on the segment defined on this
510			line.
511
512			Total Distance - The total distance travelled up to this point.
513
514			Total Duration - The total duration of travel up to this point.
515
516			Speed - The speed of travel on the segment defined on this line (missing
517			on the first line).
518
519			Bearing - The direction that the segment defined on this line travels in
520			degrees (missing on the first line).
521
522			Highway - The name (or description) of the highway segment (missing on
523			the first line).
524
525
526	amb	152	--------
527
528	amb	318	Copyright 2008,2009,2010 Andrew M. Bishop.