trunk/doc/USAGE.txt

                               Routino : 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=<dirname>] [--prefix=<name>]
                        [--slim] [--sort-ram-size=<size>]
                        [--tmpdir=<dirname>]
                        [--parse-only | --process-only]
                        [--max-iterations=<number>]
                        [--transport=<transport> ...]
                        [--not-highway=<highway> ...]
                        [--not-property=<property> ...]
                        [<filename.osm> ...]

   --help
          Prints out the help information.

   --dir=<dirname>
          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.

   --sort-ram-size=<size>
          Specifies the amount of RAM (in MB) to use for sorting the data.
          If not specified then 64 MB will be used if the '--slim' option
          is specified or 256 MB otherwise.

   --tmpdir=<dirname>
          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.

   --parse-only
          Parse the input files and store them in a temporary file but
          don't process the data into a routing database.

   --process-only
          Don't read in any files but process the existing temporary file
          into the routing database.

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

   <filename.osm> ...
          Specifies the filename(s) to read data from, by default data is
          read from the standard input.

   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 [--help | --help-profile | --help-profile-xml |
                          --help-profile-json | --help-profile-perl ]
                [--dir=<dirname>] [--prefix=<name>]
                [--profiles=<filename>] [--translations=<filename>]
                [--exact-nodes-only]
                [--quiet]
                [--output-html]
                [--output-gpx-track] [--output-gpx-route]
                [--output-text] [--output-text-all]
                [--output-none]
                [--profile=<name>]
                [--transport=<transport>]
                [--shortest | --quickest]
                --lon1=<longitude> --lat1=<latitude>
                --lon2=<longitude> --lon2=<latitude>
                [ ... --lon99=<longitude> --lon99=<latitude>]
                [--highway-<highway>=<preference> ...]
                [--speed-<highway>=<speed> ...]
                [--property-<property>=<preference> ...]
                [--oneway=(0|1)]
                [--weight=<weight>]
                [--height=<height>] [--width=<width>] [--length=<length>]

   --help
          Prints out the help information.

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

   --help-profile-xml
          Prints out all the loaded profiles as an XML file in the same
          format that can be loaded in.

   --help-profile-json
          Prints out all the loaded profiles in JavaScript Object Notation
          (JSON) format for use in the interactive webpage.

   --help-profile-perl
          Prints out all the loaded profiles as a Perl object for use in
          the router CGI.

   --dir=<dirname>
          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.

   --profiles=<filename>
          Sets the filename containing the list of profiles in XML format.
          If the file doesn't exist then dirname, prefix and
          "profiles.xml" will be combined and used, if that doesn't exist
          then the command line must contain all relevant profile
          information.

   --translations=<filename>
          Sets the filename containing the list of translations in XML
          format for the output files. If the file doesn't exist then
          dirname, prefix and "translations.xml" will be combined and
          used, if that doesn't exist then no file will be read and no
          language can be selected.

   --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 (quicker but less accurate unless the points
          are already near nodes).

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

   --language=<lang>
          Select the language specified from the file of translations. If
          this option is not given and the file exists then the first
          language in the file will be used. If this option is not given
          and no file exists the compiled-in default language (English)
          will be used.

   --output-html
   --output-gpx-track
   --output-gpx-route
   --output-text
   --output-text-all
          Generate the selected output file formats (HTML, GPX track file,
          GPX route file, plain text route and/or plain text with all
          nodes). If no output is specified then all are generated,
          specifying any automatically disables those not specified.

   --output-none
          Do not generate any output or read in any translations files.

   --profile=<name>
          Specifies the name of the profile to use.

   --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 if the '--profile' option is not given and a
          profile matching the transport name is found.

   --shortest
          Find the shortest route between the waypoints.

   --quickest
          Find the quickest route between the waypoints.

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

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


filedumper
----------

  Usage: filedumper [--help]
                    [--dir=<dirname>] [--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=<dirname>
          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 (specifying 'all' instead of a number
          dumps all of them).

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


--------

Copyright 2008-2010 Andrew M. Bishop.
1	Routino : Usage
2	===============
3
4
5	There are three programs that make up this software. The first one
6	takes the planet.osm datafile from OpenStreetMap (or other source of
7	data using the same formats) and converts it into a local database. The
8	second program uses the database to determine an optimum route between
9	two points. The third program allows visualisation of the data and
10	statistics to be extracted.
11
12
13	planetsplitter
14	--------------
15
16	Usage: planetsplitter [--help]
17	[--dir=<dirname>] [--prefix=<name>]
18	[--slim] [--sort-ram-size=<size>]
19	[--tmpdir=<dirname>]
20	[--parse-only \| --process-only]
21	[--max-iterations=<number>]
22	[--transport=<transport> ...]
23	[--not-highway=<highway> ...]
24	[--not-property=<property> ...]
25	[<filename.osm> ...]
26
27	--help
28	Prints out the help information.
29
30	--dir=<dirname>
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	--sort-ram-size=<size>
47	Specifies the amount of RAM (in MB) to use for sorting the data.
48	If not specified then 64 MB will be used if the '--slim' option
49	is specified or 256 MB otherwise.
50
51	--tmpdir=<dirname>
52	Specifies the name of the directory to store the temporary disk
53	files. If not specified then it defaults to either the value of
54	the --dir option or the current directory.
55
56	--parse-only
57	Parse the input files and store them in a temporary file but
58	don't process the data into a routing database.
59
60	--process-only
61	Don't read in any files but process the existing temporary file
62	into the routing database.
63
64	--max-iterations=<number>
65	The maximum number of iterations to use when generating
66	super-nodes and super-segments. Defaults to 10 which is normally
67	enough.
68
69	--transport=<transport> ...
70	Allows selection of only the routes that are possible for
71	particular types of transport. Defaults to all transport types
72	allowed (see the router for the list of possible transport
73	types), this option may be repeated for additional transport
74	types.
75
76	--not-highway=<highway> ...
77	Allows particular types of highways to be ignored to produce a
78	smaller database or one that is more specific to a particular
79	application (e.g. motorcar routing does not need footpaths).
80	Defaults to all highway types allowed (see the router for the
81	list of possible highway types), this option may be repeated for
82	additional highway types.
83
84	--not-property=<property> ...
85	Allows particular highway properties to be ignored to produce a
86	smaller database or one that is more specific to a particular
87	application. Defaults to all highway properties allowed (see the
88	router for the list of possible highway properties), this option
89	may be repeated for additional highway properties.
90
91	<filename.osm> ...
92	Specifies the filename(s) to read data from, by default data is
93	read from the standard input.
94
95	Example usage:
96
97	bunzip2 -c great_britain.osm.bz2 \| ./planetsplitter --dir=data --prefix=gb
98
99	This will generate the output files 'data/gb-nodes.mem',
100	'data/gb-segments.mem' and 'data/gb-ways.mem'.
101
102
103	router
104	------
105
106	Usage: router [--help \| --help-profile \| --help-profile-xml \|
107	--help-profile-json \| --help-profile-perl ]
108	[--dir=<dirname>] [--prefix=<name>]
109	[--profiles=<filename>] [--translations=<filename>]
110	[--exact-nodes-only]
111	[--quiet]
112	[--output-html]
113	[--output-gpx-track] [--output-gpx-route]
114	[--output-text] [--output-text-all]
115	[--output-none]
116	[--profile=<name>]
117	[--transport=<transport>]
118	[--shortest \| --quickest]
119	--lon1=<longitude> --lat1=<latitude>
120	--lon2=<longitude> --lon2=<latitude>
121	[ ... --lon99=<longitude> --lon99=<latitude>]
122	[--highway-<highway>=<preference> ...]
123	[--speed-<highway>=<speed> ...]
124	[--property-<property>=<preference> ...]
125	[--oneway=(0\|1)]
126	[--weight=<weight>]
127	[--height=<height>] [--width=<width>] [--length=<length>]
128
129	--help
130	Prints out the help information.
131
132	--help-profile
133	Prints out the selected transport profile (type, speed limits,
134	highway preferences etc.)
135
136	--help-profile-xml
137	Prints out all the loaded profiles as an XML file in the same
138	format that can be loaded in.
139
140	--help-profile-json
141	Prints out all the loaded profiles in JavaScript Object Notation
142	(JSON) format for use in the interactive webpage.
143
144	--help-profile-perl
145	Prints out all the loaded profiles as a Perl object for use in
146	the router CGI.
147
148	--dir=<dirname>
149	Sets the directory name in which to read the local database.
150	Defaults to the current directory.
151
152	--prefix=<name>
153	Sets the filename prefix for the files in the local database.
154	Defaults to no prefix.
155
156	--profiles=<filename>
157	Sets the filename containing the list of profiles in XML format.
158	If the file doesn't exist then dirname, prefix and
159	"profiles.xml" will be combined and used, if that doesn't exist
160	then the command line must contain all relevant profile
161	information.
162
163	--translations=<filename>
164	Sets the filename containing the list of translations in XML
165	format for the output files. If the file doesn't exist then
166	dirname, prefix and "translations.xml" will be combined and
167	used, if that doesn't exist then no file will be read and no
168	language can be selected.
169
170	--exact-nodes-only
171	When processing the specified latitude and longitude points only
172	select the nearest node instead of finding the nearest point
173	within a segment (quicker but less accurate unless the points
174	are already near nodes).
175
176	--quiet
177	Don't generate any screen output while running (useful for
178	running in a script).
179
180	--language=<lang>
181	Select the language specified from the file of translations. If
182	this option is not given and the file exists then the first
183	language in the file will be used. If this option is not given
184	and no file exists the compiled-in default language (English)
185	will be used.
186
187	--output-html
188	--output-gpx-track
189	--output-gpx-route
190	--output-text
191	--output-text-all
192	Generate the selected output file formats (HTML, GPX track file,
193	GPX route file, plain text route and/or plain text with all
194	nodes). If no output is specified then all are generated,
195	specifying any automatically disables those not specified.
196
197	--output-none
198	Do not generate any output or read in any translations files.
199
200	--profile=<name>
201	Specifies the name of the profile to use.
202
203	--transport=<transport>
204	Select the type of transport to use, <transport> can be set to:
205
206	+ foot = Foot
207	+ horse = Horse
208	+ wheelchair = Wheelchair
209	+ bicycle = Bicycle
210	+ moped = Moped (Small motorbike, limited speed)
211	+ motorbike = Motorbike
212	+ motorcar = Motorcar
213	+ goods = Goods (Small lorry, van)
214	+ hgv = HGV (Heavy Goods Vehicle - large lorry)
215	+ psv = PSV (Public Service Vehicle - bus, coach)
216
217	Defaults to 'motorcar', this option also selects the default
218	profile information if the '--profile' option is not given and a
219	profile matching the transport name is found.
220
221	--shortest
222	Find the shortest route between the waypoints.
223
224	--quickest
225	Find the quickest route between the waypoints.
226
227	--lon1=<longitude>, --lat1=<latitude>
228	--lon2=<longitude>, --lat2=<latitude>
229	... --lon99=<longitude>, --lat99=<latitude>
230	The location of the waypoints that make up the start, middle and
231	end points of the route. Up to 99 waypoints can be specified and
232	the route will pass through each of the specified ones in
233	sequence. The algorithm will use the closest node or point
234	within a segment that allows the specified traffic type.
235
236	--highway-<highway>=<preference>
237	Selects the percentage preference for using each particular type
238	of highway. The value of <highway> can be selected from:
239
240	+ motorway = Motorway
241	+ trunk = Trunk
242	+ primary = Primary
243	+ secondary = Secondary
244	+ tertiary = Tertiary
245	+ unclassified = Unclassified
246	+ residential = Residential
247	+ service = Service
248	+ track = Track
249	+ cycleway = Cycleway
250	+ path = Path
251	+ steps = Steps
252
253	Default value depends on the profile selected by the --transport
254	option.
255
256	--speed-<highway>=<speed>
257	Selects the speed limit in km/hour for each type of highway.
258	Default value depends on the profile selected by the --transport
259	option.
260
261	--property-<property>=<preference>
262	Selects the percentage preference for using each particular
263	highway property The value of <property> can be selected from:
264
265	+ paved = Paved (suitable for normal wheels)
266	+ multilane = Multiple lanes
267	+ bridge = Bridge
268	+ tunnel = Tunnel
269
270	Default value depends on the profile selected by the --transport
271	option.
272
273	--oneway=[0\|1]
274	Selects if the direction of oneway streets are to be obeyed
275	(useful to not obey them when walking). Default value depends on
276	the profile selected by the --transport option.
277
278	--weight=<weight>
279	Specifies the weight of the mode of transport in tonnes; ensures
280	that the weight limit on the highway is not exceeded. Default
281	value depends on the profile selected by the --transport option.
282
283	--height=<height>
284	Specifies the height of the mode of transport in metres; ensures
285	that the height limit on the highway is not exceeded. Default
286	value depends on the profile selected by the --transport option.
287
288	--width=<width>
289	Specifies the width of the mode of transport in metres; ensures
290	that the width limit on the highway is not exceeded. Default
291	value depends on the profile selected by the --transport option.
292
293	--length=<length>
294	Specifies the length of the mode of transport in metres; ensures
295	that the length limit on the highway is not exceeded. Default
296	value depends on the profile selected by the --transport option.
297
298	The meaning of the <preference> parameter in the command line options
299	is slightly different for the highway preferences and the property
300	preferences. For the highway preference consider the choice between two
301	possible highways between the start and finish when looking for the
302	shortest route. If highway A has a preference of 100% and highway B has
303	a preference of 90% then highway A will be chosen even if it is up to
304	11% longer (100/90 = 111%). For the highway properties each highway
305	either has a particular property or not. If the preference for highways
306	with the property is 60% then the preference for highways without the
307	property is 40%. The overall preference for the highway is the product
308	of the highway preference and the preference for highways with (or
309	without) each property that the highway has (or doesn't have).
310
311	Example usage (motorbike journey, scenic route, not very fast):
312
313	./router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
314	--highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest
315
316	This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
317	'data/gb-ways.mem' to find the quickest route by motorbike not using
318	motorways or trunk roads and not exceeding 80 km/hr.
319
320
321	filedumper
322	----------
323
324	Usage: filedumper [--help]
325	[--dir=<dirname>] [--prefix=<name>]
326	[--statistics]
327	[--visualiser --latmin=<latmin> --latmax=<latmax>
328	--lonmin=<lonmin> --lonmax=<lonmax>
329	--data=<data-type>]
330	[--dump [--node=<node> ...]
331	[--segment=<segment> ...]
332	[--way=<way> ...]]
333
334	--help
335	Prints out the help information.
336
337	--dir=<dirname>
338	Sets the directory name in which to read the local database.
339	Defaults to the current directory.
340
341	--prefix=<name>
342	Sets the filename prefix for the files in the local database.
343
344	--statistics
345	Prints out statistics about the database files.
346
347	--visualiser
348	Selects a data visualiser mode which will output a set of data
349	according to the other parameters below.
350
351	--latmin=<latmin> --latmax=<latmax>
352	The range of latitudes to print the data for.
353
354	--lonmin=<lonmin> --lonmax=<lonmax>
355	The range of longitudes to print the data for.
356
357	--data=<data-type>
358	The type of data to output, <data-type> can be selected
359	from:
360
361	o junctions = segment count at each junction.
362	o super = super-node and super-segments.
363	o oneway = oneway segments.
364	o speed = speed limits.
365	o weight = weight limits.
366	o height = height limits.
367	o width = width limits.
368	o length = length limits.
369
370	--dump
371	Selects a data dumping mode which allows looking at individual
372	items in the databases (specifying 'all' instead of a number
373	dumps all of them).
374
375	--node=<node>
376	Prints the information about the selected node number
377	(internal number, not the node id number in the original
378	source file).
379
380	--segment=<segment>
381	Prints the information about the selected segment number.
382
383	--way=<way>
384	Prints the information about the selected way number
385	(internal number, not the way id number in the original
386	source file).
387
388
389	--------
390
391	Copyright 2008-2010 Andrew M. Bishop.