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	Program Usage
2	=============
3
4	Program Usage
5	-------------
6
7	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
14
15	planetsplitter
16	--------------
17
18	Usage: planetsplitter
19	[--help]
20	[--dir=<name>] [--prefix=<name>]
21	[--slim] [--tmpdir=<name>]
22	[--max-iterations=<number>]
23	[--transport=<transport> ...]
24	[--not-highway=<highway> ...]
25	[--not-property=<property> ...]
26
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	--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	--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	Example usage:
79	bunzip2 -c great_britain.osm.bz2 \| ./planetsplitter --dir=data --prefix=gb
80
81	This will generate the output files 'data/gb-nodes.mem',
82	'data/gb-segments.mem' and 'data/gb-ways.mem'.
83
84
85	router
86	------
87
88	Usage: router [--lon1=]<longitude> [--lat1=]<latitude>
89	[--lon2=]<longitude> [--lon2=]<latitude>
90	[ ... [--lon99=]<longitude> [--lon99=]<latitude> ]
91	[--help \| --help-profile \| --help-profile-js \| --help-profile-pl]
92	[--dir=<name>] [--prefix=<name>]
93	[--shortest \| --quickest]
94	[--exact-nodes-only]
95	[--quiet]
96	[--transport=<transport>]
97	[--highway-<highway>=<preference> ...]
98	[--speed-<highway>=<speed> ...]
99	[--property-<property>=<preference> ...]
100	[--oneway=[0\|1]]
101	[--weight=<weight>]
102	[--height=<height>] [--width=<width>] [--length=<length>]
103
104	--lon1=<longitude>, --lat1=<latitude>
105	--lon2=<longitude>, --lat2=<latitude>
106	...
107	--lon99=<longitude>, --lat99=<latitude>
108	The location of the points that make up the start, middle and
109	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
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	Sets the directory name in which to read the local database.
131	Defaults to the current directory.
132
133	--prefix=<name>
134	Sets the filename prefix for the files in the local database.
135	Defaults to no prefix.
136
137	--shortest
138	Find the shortest route.
139
140	--quickest
141	Find the quickest route.
142
143	--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	--quiet
149	Don't generate any screen output while running (useful for
150	running in a script).
151
152	--transport=<transport>
153	Select the type of transport to use, <transport> can be set to:
154
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	profile information.
168
169	--highway-<highway>=<preference>
170	Selects the percentage preference for using each particular type
171	of highway. The value of <highway> can be selected from:
172
173	+ 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	--speed-<highway>=<speed>
190	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
194	--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	--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	Specifies the weight of the mode of transport in tonnes; ensures
213	that the weight limit on the highway is not exceeded. Default
214	value depends on the profile selected by the --transport option.
215
216	--height=<height>
217	Specifies the height of the mode of transport in metres; ensures
218	that the height limit on the highway is not exceeded. Default
219	value depends on the profile selected by the --transport option.
220
221	--width=<width>
222	Specifies the width of the mode of transport in metres; ensures
223	that the width limit on the highway is not exceeded. Default
224	value depends on the profile selected by the --transport option.
225
226	--length=<length>
227	Specifies the length of the mode of transport in metres; ensures
228	that the length limit on the highway is not exceeded. Default
229	value depends on the profile selected by the --transport option.
230
231	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	Example usage (motorbike journey, scenic route, not very fast):
245
246	./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	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
266	filedumper
267	----------
268
269	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	[--dump --node=<node> ...
277	--segment=<segment> ...
278	--way=<way> ...]
279
280	--help
281	Prints out the help information.
282
283	--dir=<name>
284	Sets the directory name in which to read the local database.
285	Defaults to the current directory.
286
287	--prefix=<name>
288	Sets the filename prefix for the files in the local database.
289
290	--statistics
291	Prints out statistics about the database files.
292
293	--visualiser
294	Selects a data visualiser mode which will output a set of data
295	according to the other parameters below.
296
297	--latmin=<latmin> --latmax=<latmax>
298	The range of latitudes to print the data for.
299
300	--lonmin=<lonmin> --lonmax=<lonmax>
301	The range of longitudes to print the data for.
302
303	--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
315	--dump
316	Selects a data dumping mode which allows looking at individual
317	items in the databases.
318
319	--node=<node>
320	Prints the information about the selected node number
321	(internal number, not the node id number in the original
322	source file).
323
324	--segment=<segment>
325	Prints the information about the selected segment number.
326
327	--way=<way>
328	Prints the information about the selected way number
329	(internal number, not the way id number in the original
330	source file).
331
332
333	Router Output
334	-------------
335
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	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	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
349
350	GPX Track File
351	--------------
352
353	The GPX track file contains a track with all of the individual nodes
354	that the route passes through.
355
356	An example GPX track file output is below:
357
358	<?xml version="1.0" encoding="UTF-8"?>
359	<gpx version="1.1" creator="Routino"
360	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
361	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	<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
381	GPX Route File
382	--------------
383
384	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	<gpx version="1.1" creator="Routino"
391	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
392	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	<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
411	Text File
412	---------
413
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	An example text file output is below:
418
419	# 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
425	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	The text file output contains a header (indicated by the lines starting
432	with '#') and then one line for each junction. Each line contains the
433	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	The individual items are separated by tabs but some of the items
468	contain spaces as well.
469
470
471	All Nodes Text File
472	-------------------
473
474	The all nodes text file format contains one entry for each of the nodes
475	on the route.
476
477	An example all nodes text file output is below:
478
479	# 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
485	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
491	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	the junctions. For each of the lines the individual fields contain the
494	following:
495
496	Latitude - Location of the point in degrees.
497
498	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	--------
527
528	Copyright 2008,2009,2010 Andrew M. Bishop.