trunk/doc/USAGE.txt

                                Program Usage
                                =============

Program Usage

   There are two programs that make up this software. The first one takes
   the planet.osm datafile from OpenStreetMap and converts it into a local
   database. The second program uses the database to determine an optimum
   route between two points.

planetsplitter

   Usage: planetsplitter
                         [--help]
                         [--dir=<name>] [--prefix=<name>]
                         [--max-iterations=<number>]
                         [--transport=<transport>]
                         [--not-highway=<highway> ...]

   --help
          Prints out the help information.

   --dir=<name>
          Sets the directory name in which to save the results. Defaults
          to the current directory.

   --prefix=<name>
          Sets the filename prefix for the files that are created.
          Defaults to no prefix.

   --max-iterations=<number>
          The maximum number of iterations to use when generating
          super-nodes and super-segments. Defaults to 10 which is normally
          enough.

   --transport=<transport>
          Allows selection of only the routes that are possible for a
          particular type of transport. Defaults to all transport types
          allowed.

   --not-highway=<highway>
          Allows particular types of highways to be ignored. Defaults to
          all highway types allowed. This option may be repeated.

   Example usage:
   bunzip2 -c great_britain.osm.bz2 | ./planetsplitter --dir=data --prefix=gb

   This will generate the output files 'data/gb-nodes.mem',
   'data/gb-segments.mem' and 'data/gb-ways.mem'.

router

   Usage: router [--lon1=]<start-lon>  [--lat1=]<start-lat>
                 [--lon2=]<finish-lon> [--lon2=]<finish-lat>
                 [--help | --help-profile | --help-profile-js | --help-profile-pl]
                 [--dir=<name>] [--prefix=<name>]
                 [--shortest | --quickest]
                 [--all | --super]
                 [--no-output] [--quiet]
                 [--transport=<transport>]
                 [--highway-<highway>=[0|1] ...]
                 [--speed-<highway>=<speed> ...]
                 [--oneway=[0|1]]
                 [--weight=<weight>]
                 [--height=<height>] [--width=<width>] [--length=<length>]

   --lon1=<start-lon>, --lat1=<start-lat>
          The location of the starting point. If the --lon1 and --lat1
          prefixes are not used then these must be the first and second
          options.

   --lon2=<finish-lon>, --lat2=<finish-lat>
          The location of the finishing point. If the --lon2 and --lat2
          prefixes are not used then these must be the third and fourth
          options.

   --help
          Prints out the help information.

   --help-profile
          Prints out the selected transport profile (type, speed limits,
          highway preferences etc.)

   --help-profile-js
          Prints out all the compiled-in profiles as a set of Javascript
          arrays for use in the interactive webpage.

   --help-profile-pl
          Prints out all the compiled-in profiles as a set of Perl arrays
          for use in the router CGI.

   --dir=<name>
          Sets the directory name in which to save the results. Defaults
          to the current directory.

   --prefix=<name>
          Sets the filename prefix for the files that are created.
          Defaults to no prefix.

   --shortest
          Find the shortest route.

   --quickest
          Find the quickest route.

   --all
          Find the route using all nodes and segments, not using
          super-nodes and super-segments (useful for debugging only).

   --super
          Find the route using only super-nodes and super-segments, not
          using normal nodes and segments (useful for debugging only).

   --no-output
          Don't generate any output files (useful for debugging).

   --quiet
          Don't generate any screen output while running (useful for
          running in a script).

   --transport=<transport>
          Select the type of transport to use. Defaults to 'Motorcar',
          this option also selects the default profile.

   --highway-<highway>=[0|1]
          Selects the preference for using each particular type of
          highway. Default value depends on the profile selected by the
          --transport option.

   --speed-<highway>=<speed>
          Selects the speed limit for each type of highway. Default value
          depends on the profile selected by the --transport option.

   --oneway=[0|1]
          Selects if the direction of oneway streets are to be obeyed
          (useful to not obey them when walking). Default value depends on
          the profile selected by the --transport option.

   --weight=<weight>
          Specifies the weight of the mode of transport, ensures that the
          weight limit on the highway is not exceeded. Default value
          depends on the profile selected by the --transport option.

   --height=<height>
          Specifies the height of the mode of transport, ensures that the
          height limit on the highway is not exceeded. Default value
          depends on the profile selected by the --transport option.

   --width=<width>
          Specifies the width of the mode of transport, ensures that the
          width limit on the highway is not exceeded. Default value
          depends on the profile selected by the --transport option.

   --length=<length>
          Specifies the length of the mode of transport, ensures that the
          length limit on the highway is not exceeded. Default value
          depends on the profile selected by the --transport option.

   Example usage (motorbike journey, scenic route, not very fast):
   ./router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
            --highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest

   This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
   'data/gb-ways.mem' to find the quickest route by motorbike not using
   motorways or trunk roads and not exceeding 80 km/hr.

Common Parameters

   There are a number of parameters that are used by both programs or are used
   to specify a quantity or choice.  These are defined below.

   <transport> can be set to:
     * foot = Foot
     * bicycle = Bicycle
     * horse = Horse
     * motorbike = Motorbike
     * motorcar = Motorcar
     * goods = Goods (Small lorry, van)
     * hgv = HGV (Heavy Goods Vehicle - large lorry)
     * psv = PSV (Public Service Vehicle - bus, coach)

   <highway> can be selected from:
     * motorway = Motorway
     * trunk = Trunk
     * primary = Primary
     * secondary = Secondary
     * tertiary = Tertiary
     * unclassified = Unclassified
     * residential = Residential
     * service = Service
     * track = Track
     * path = Path
     * bridleway = Bridleway
     * cycleway = Cycleway
     * footway = Footway

   <speed> is a speed in km/hour.

   <weight> is a weight in tonnes.

   <height>, <width>, <length> are dimensions in metres.


Program Output

   There are two formats of output from the router, plain text and [17]GPX
   (GPS eXchange) XML format. There are four outputs from the router
   program: a GPX track file, a GPX route file, a text description with
   the junctions and a text file with every node.

   The output files are written to the current directory and are named
   depending on the selection of shortest or quickest route. For the
   shortest route the file names are "shortest-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.0" creator="Routino"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="http://www.topografix.com/GPX/1/0"
           xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
   <trk>
   <trkseg>
   <trkpt lat="51.524676" lon="-0.127896"/>
   <trkpt lat="51.523829" lon="-0.126993"/>
   ...
   <trkpt lat="51.478354" lon="-0.103561"/>
   <trkpt lat="51.478244" lon="-0.103652"/>
   </trkseg>
   </trk>
   </gpx>

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.0" creator="Routino"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="http://www.topografix.com/GPX/1/0"
           xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
   <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:

   #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:

   #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.
1	Program Usage
2	=============
3
4	Program Usage
5
6	There are two programs that make up this software. The first one takes
7	the planet.osm datafile from OpenStreetMap and converts it into a local
8	database. The second program uses the database to determine an optimum
9	route between two points.
10
11	planetsplitter
12
13	Usage: planetsplitter
14	[--help]
15	[--dir=<name>] [--prefix=<name>]
16	[--max-iterations=<number>]
17	[--transport=<transport>]
18	[--not-highway=<highway> ...]
19
20	--help
21	Prints out the help information.
22
23	--dir=<name>
24	Sets the directory name in which to save the results. Defaults
25	to the current directory.
26
27	--prefix=<name>
28	Sets the filename prefix for the files that are created.
29	Defaults to no prefix.
30
31	--max-iterations=<number>
32	The maximum number of iterations to use when generating
33	super-nodes and super-segments. Defaults to 10 which is normally
34	enough.
35
36	--transport=<transport>
37	Allows selection of only the routes that are possible for a
38	particular type of transport. Defaults to all transport types
39	allowed.
40
41	--not-highway=<highway>
42	Allows particular types of highways to be ignored. Defaults to
43	all highway types allowed. This option may be repeated.
44
45	Example usage:
46	bunzip2 -c great_britain.osm.bz2 \| ./planetsplitter --dir=data --prefix=gb
47
48	This will generate the output files 'data/gb-nodes.mem',
49	'data/gb-segments.mem' and 'data/gb-ways.mem'.
50
51	router
52
53	Usage: router [--lon1=]<start-lon> [--lat1=]<start-lat>
54	[--lon2=]<finish-lon> [--lon2=]<finish-lat>
55	[--help \| --help-profile \| --help-profile-js \| --help-profile-pl]
56	[--dir=<name>] [--prefix=<name>]
57	[--shortest \| --quickest]
58	[--all \| --super]
59	[--no-output] [--quiet]
60	[--transport=<transport>]
61	[--highway-<highway>=[0\|1] ...]
62	[--speed-<highway>=<speed> ...]
63	[--oneway=[0\|1]]
64	[--weight=<weight>]
65	[--height=<height>] [--width=<width>] [--length=<length>]
66
67	--lon1=<start-lon>, --lat1=<start-lat>
68	The location of the starting point. If the --lon1 and --lat1
69	prefixes are not used then these must be the first and second
70	options.
71
72	--lon2=<finish-lon>, --lat2=<finish-lat>
73	The location of the finishing point. If the --lon2 and --lat2
74	prefixes are not used then these must be the third and fourth
75	options.
76
77	--help
78	Prints out the help information.
79
80	--help-profile
81	Prints out the selected transport profile (type, speed limits,
82	highway preferences etc.)
83
84	--help-profile-js
85	Prints out all the compiled-in profiles as a set of Javascript
86	arrays for use in the interactive webpage.
87
88	--help-profile-pl
89	Prints out all the compiled-in profiles as a set of Perl arrays
90	for use in the router CGI.
91
92	--dir=<name>
93	Sets the directory name in which to save the results. Defaults
94	to the current directory.
95
96	--prefix=<name>
97	Sets the filename prefix for the files that are created.
98	Defaults to no prefix.
99
100	--shortest
101	Find the shortest route.
102
103	--quickest
104	Find the quickest route.
105
106	--all
107	Find the route using all nodes and segments, not using
108	super-nodes and super-segments (useful for debugging only).
109
110	--super
111	Find the route using only super-nodes and super-segments, not
112	using normal nodes and segments (useful for debugging only).
113
114	--no-output
115	Don't generate any output files (useful for debugging).
116
117	--quiet
118	Don't generate any screen output while running (useful for
119	running in a script).
120
121	--transport=<transport>
122	Select the type of transport to use. Defaults to 'Motorcar',
123	this option also selects the default profile.
124
125	--highway-<highway>=[0\|1]
126	Selects the preference for using each particular type of
127	highway. Default value depends on the profile selected by the
128	--transport option.
129
130	--speed-<highway>=<speed>
131	Selects the speed limit for each type of highway. Default value
132	depends on the profile selected by the --transport option.
133
134	--oneway=[0\|1]
135	Selects if the direction of oneway streets are to be obeyed
136	(useful to not obey them when walking). Default value depends on
137	the profile selected by the --transport option.
138
139	--weight=<weight>
140	Specifies the weight of the mode of transport, ensures that the
141	weight limit on the highway is not exceeded. Default value
142	depends on the profile selected by the --transport option.
143
144	--height=<height>
145	Specifies the height of the mode of transport, ensures that the
146	height limit on the highway is not exceeded. Default value
147	depends on the profile selected by the --transport option.
148
149	--width=<width>
150	Specifies the width of the mode of transport, ensures that the
151	width limit on the highway is not exceeded. Default value
152	depends on the profile selected by the --transport option.
153
154	--length=<length>
155	Specifies the length of the mode of transport, ensures that the
156	length limit on the highway is not exceeded. Default value
157	depends on the profile selected by the --transport option.
158
159	Example usage (motorbike journey, scenic route, not very fast):
160	./router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
161	--highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest
162
163	This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
164	'data/gb-ways.mem' to find the quickest route by motorbike not using
165	motorways or trunk roads and not exceeding 80 km/hr.
166
167	Common Parameters
168
169	There are a number of parameters that are used by both programs or are used
170	to specify a quantity or choice. These are defined below.
171
172	<transport> can be set to:
173	* foot = Foot
174	* bicycle = Bicycle
175	* horse = Horse
176	* motorbike = Motorbike
177	* motorcar = Motorcar
178	* goods = Goods (Small lorry, van)
179	* hgv = HGV (Heavy Goods Vehicle - large lorry)
180	* psv = PSV (Public Service Vehicle - bus, coach)
181
182	<highway> can be selected from:
183	* motorway = Motorway
184	* trunk = Trunk
185	* primary = Primary
186	* secondary = Secondary
187	* tertiary = Tertiary
188	* unclassified = Unclassified
189	* residential = Residential
190	* service = Service
191	* track = Track
192	* path = Path
193	* bridleway = Bridleway
194	* cycleway = Cycleway
195	* footway = Footway
196
197	<speed> is a speed in km/hour.
198
199	<weight> is a weight in tonnes.
200
201	<height>, <width>, <length> are dimensions in metres.
202
203
204	Program Output
205
206	There are two formats of output from the router, plain text and [17]GPX
207	(GPS eXchange) XML format. There are four outputs from the router
208	program: a GPX track file, a GPX route file, a text description with
209	the junctions and a text file with every node.
210
211	The output files are written to the current directory and are named
212	depending on the selection of shortest or quickest route. For the
213	shortest route the file names are "shortest-track.gpx",
214	"shortest-route.gpx", "shortest.txt" and "shortest-all.txt", for the
215	quickest route the names are "quickest-track.gpx",
216	"quickest-route.gpx", "quickest.txt" and "quickest-all.txt".
217
218	GPX Track File
219
220	The GPX track file contains a track with all of the individual nodes
221	that the route passes through.
222
223	An example GPX track file output is below:
224
225	<?xml version="1.0" encoding="UTF-8"?>
226	<gpx version="1.0" creator="Routino"
227	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
228	xmlns="http://www.topografix.com/GPX/1/0"
229	xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
230	<trk>
231	<trkseg>
232	<trkpt lat="51.524676" lon="-0.127896"/>
233	<trkpt lat="51.523829" lon="-0.126993"/>
234	...
235	<trkpt lat="51.478354" lon="-0.103561"/>
236	<trkpt lat="51.478244" lon="-0.103652"/>
237	</trkseg>
238	</trk>
239	</gpx>
240
241	GPX Route File
242
243	The GPX route file contains a route (ordered set of waypoints) with all
244	of the junctions that the route passes through.
245
246	An example GPX route file output is below:
247
248	<?xml version="1.0" encoding="UTF-8"?>
249	<gpx version="1.0" creator="Routino"
250	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
251	xmlns="http://www.topografix.com/GPX/1/0"
252	xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
253	<rte>
254	<name>Shortest route</name>
255	<rtept lat="51.524676" lon="-0.127896"><name>START</name></rtept>
256	<rtept lat="51.523829" lon="-0.126993"><name>TRIP001</name></rtept>
257	...
258	<rtept lat="51.480314" lon="-0.108381"><name>TRIP015</name></rtept>
259	<rtept lat="51.478244" lon="-0.103652"><name>FINISH</name></rtept>
260	</rte>
261	</gpx>
262
263	Text File
264
265	The text file format contains one entry for all of the junctions in the
266	route and is intended to be easy to interpret.
267
268	An example Text file output is below:
269
270	#Latitude Longitude Segment Segment Total Total Highway
271	# Distance Duration Distance Durat'n
272	51.524676 -0.127896 0.000 km 0.0 min 0.0 km 0 min
273	51.523829 -0.126993 0.113 km 0.1 min 0.1 km 0 min Woburn Place
274	...
275	51.480314 -0.108381 0.200 km 0.1 min 5.9 km 5 min Camberwell New Road (A202)
276	51.478244 -0.103652 0.411 km 0.3 min 6.3 km 5 min Vassall Road
277
278	The text file output contains a header (indicated by the lines starting
279	with '#') and then one line for each junction. Each line contains the
280	information for the route up to that point. For each of the lines the
281	latitude and longitude are the first two items. The length of the
282	segment in km and the journey duration for the segment in minutes are
283	the next two items. The cumulative journey distance and duration are
284	the 6th and 7th items and the final item is the name of the highway.
285	The individual items are separated by tabs but some of the items
286	contain spaces as well.
287
288	All Nodes Text File
289
290	The all nodes text file format contains one entry for each of the nodes
291	on the route.
292
293	An example all nodes text file output is below:
294
295	#Latitude Longitude Node Segment Segment Total Total Speed Highway
296	# Dist Durat'n Dist Durat'n
297
298	51.524676 -0.127896 4830582* 0.000 0.00 0.00 0.0
299	51.523829 -0.126993 4830562* 0.113 0.14 0.11 0.1 96 Woburn Place
300	...
301	51.478354 -0.103561 4904816* 0.104 0.07 6.30 5.1 96 Camberwell New Road (A202)
302	51.478244 -0.103652 4908481 0.013 0.01 6.31 5.1 64 Vassall Road
303
304	The all nodes text file output is similar to the text file output
305	except that a line is printed for each of the nodes rather than just
306	the junctions. The additional information on each line is the node
307	number (not the OpenStreetMap node number but an internal value) as
308	well as an indicator for the super-nodes and the speed for the segment.
309
310
311	--------
312
313	Copyright 2008,2009 Andrew M. Bishop.