Routino SVN Repository Browser

Check out the latest version of Routino: svn co http://routino.org/svn/trunk routino

ViewVC logotype

Contents of /trunk/doc/USAGE.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1136 - (show annotations) (download)
Sat Nov 10 19:23:32 2012 UTC (12 years, 4 months ago) by amb
File MIME type: text/plain
File size: 22287 byte(s)
Added a --preserve option which keeps the raw data files after parsing, sorting
and de-duplication.

1 Routino : Usage
2 ===============
3
4
5 There are four programs that make up this software. The first one takes
6 the planet.osm datafile from OpenStreetMap (or other source of data
7 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. The fourth program is a test program for
11 the tag transformations.
12
13
14 planetsplitter
15 --------------
16
17 This program reads in the OSM format XML file and splits it up to
18 create the database that is used for routing.
19
20 Usage: planetsplitter [--help]
21 [--dir=<dirname>] [--prefix=<name>]
22 [--sort-ram-size=<size>] [--sort-threads=<number>]
23 [--tmpdir=<dirname>]
24 [--tagging=<filename>]
25 [--loggable] [--logtime]
26 [--errorlog[=<name>]]
27 [--parse-only | --process-only]
28 [--append] [--preserve]
29 [--max-iterations=<number>]
30 [--prune-none]
31 [--prune-isolated=<len>]
32 [--prune-short=<len>]
33 [--prune-straight=<len>]
34 [<filename.osm> ...]
35
36 --help
37 Prints out the help information.
38
39 --dir=<dirname>
40 Sets the directory name in which to save the results. Defaults
41 to the current directory.
42
43 --prefix=<name>
44 Sets the filename prefix for the files that are created.
45 Defaults to no prefix.
46
47 --sort-ram-size=<size>
48 Specifies the amount of RAM (in MB) to use for sorting the data.
49 If not specified then 64 MB will be used in slim mode or 256 MB
50 otherwise.
51
52 --sort-threads=<number>
53 The number of threads to use for data sorting (the sorting
54 memory is shared between the threads - too many threads and not
55 enough memory will reduce the performance).
56
57 --tmpdir=<dirname>
58 Specifies the name of the directory to store the temporary disk
59 files. If not specified then it defaults to either the value of
60 the --dir option or the current directory.
61
62 --tagging=<filename>
63 Sets the filename containing the list of tagging rules in XML
64 format for the parsing the input files. If the file doesn't
65 exist then dirname, prefix and "profiles.xml" will be combined
66 and used, if that doesn't exist then the file
67 '/usr/local/share/routino/profiles.xml' (or custom installation
68 location) will be used.
69
70 --loggable
71 Print progress messages that are suitable for logging to a file;
72 normally an incrementing counter is printed which is more
73 suitable for real-time display than logging.
74
75 --logtime
76 Print the elapsed time for each processing step.
77
78 --errorlog[=<name>]
79 Log OSM parsing and processing errors to 'error.log' or the
80 specified file name (the '--dir' and '--prefix' options are
81 applied). If the --append option is used then the existing log
82 file will be appended, otherwise a new one will be created.
83
84 --parse-only
85 Parse the input files and store the data in intermediate files
86 but don't process the data into a routing database. This option
87 must be used with the --append option for all except the first
88 file.
89
90 --process-only
91 Don't read in any files but process the existing intermediate
92 files created by using the --parse-only option.
93
94 --append
95 Parse the input file and append the result to the existing
96 intermediate files.
97
98 --preserve
99 Store a set of intermediate files after parsing the OSM files,
100 sorting and removing duplicates.
101
102 --max-iterations=<number>
103 The maximum number of iterations to use when generating
104 super-nodes and super-segments. Defaults to 5 which is normally
105 enough.
106
107 --prune-none
108 Disable the prune options below, they can be re-enabled by
109 adding them to the command line after this option.
110
111 --prune-isolated=<length>
112 Remove the access permissions for a transport type from small
113 disconnected groups of segments and remove the segments if they
114 nd up with no access permission (defaults to removing groups
115 under 500m).
116
117 --prune-short=<length>
118 Remove short segments (defaults to removing segments up to a
119 maximum length of 5m).
120
121 --prune-straight=<length>
122 Remove nodes in almost straight highways (defaults to removing
123 nodes up to 3m offset from a straight line).
124
125 <filename.osm> ...
126 Specifies the filename(s) to read data from, by default data is
127 read from the standard input.
128
129 Note: In version 1.4 of Routino the --transport, --not-highway and
130 --not-property options have been removed. The same functionality can be
131 achieved by editing the tagging rules file to not output unwanted data.
132
133 Note: In version 1.5 of Routino the --slim option has been removed but
134 at compilation time a separate program called planetsplitter-slim is
135 created that operates in slim mode. In slim mode the temporary files
136 and database files are read as needed rather than being mapped into
137 memory. This allows a database size greater than 2 GB on 32-bit
138 machines or usage with little or no virtual memory (e.g. some virtual
139 machines). The penalty for this is that the program takes about twice
140 as long to run.
141
142 Example usage 1:
143
144 planetsplitter --dir=data --prefix=gb great_britain.osm
145
146 This will generate the output files 'data/gb-nodes.mem',
147 'data/gb-segments.mem' and 'data/gb-ways.mem'. Multiple filenames can
148 be specified on the command line and they will all be read in, combined
149 and processed together.
150
151 Example usage 2:
152
153 planetsplitter --dir=data --prefix=gb --parse-only great_britain_part1.osm
154 planetsplitter --dir=data --prefix=gb --parse-only --append great_britain_part2.osm
155 planetsplitter --dir=data --prefix=gb --parse-only --append ...
156 planetsplitter --dir=data --prefix=gb --process-only
157
158 This will generate the same output files as the first example but
159 parsing the input files is performed separately from the data
160 processing. The first file read in must not use the --append option but
161 the later ones must.
162
163
164 router
165 ------
166
167 This program performs the calculation of the optimum routes using the
168 database generated by the planetsplitter program.
169
170 Usage: router [--help | --help-profile | --help-profile-xml |
171 --help-profile-json | --help-profile-perl ]
172 [--dir=<dirname>] [--prefix=<name>]
173 [--profiles=<filename>] [--translations=<filename>]
174 [--exact-nodes-only]
175 [--loggable | --quiet]
176 [--output-html]
177 [--output-gpx-track] [--output-gpx-route]
178 [--output-text] [--output-text-all]
179 [--output-none]
180 [--profile=<name>]
181 [--transport=<transport>]
182 [--shortest | --quickest]
183 --lon1=<longitude> --lat1=<latitude>
184 --lon2=<longitude> --lon2=<latitude>
185 [ ... --lon99=<longitude> --lon99=<latitude>]
186 [--heading=<bearing>]
187 [--highway-<highway>=<preference> ...]
188 [--speed-<highway>=<speed> ...]
189 [--property-<property>=<preference> ...]
190 [--oneway=(0|1)] [--turns=(0|1)]
191 [--weight=<weight>]
192 [--height=<height>] [--width=<width>] [--length=<length>]
193
194 --help
195 Prints out the help information.
196
197 --help-profile
198 Prints out the selected transport profile (type, speed limits,
199 highway preferences etc.)
200
201 --help-profile-xml
202 Prints out all the loaded profiles as an XML file in the same
203 format that can be loaded in.
204
205 --help-profile-json
206 Prints out all the loaded profiles in JavaScript Object Notation
207 (JSON) format for use in the interactive webpage.
208
209 --help-profile-perl
210 Prints out all the loaded profiles as a Perl object for use in
211 the router CGI.
212
213 --dir=<dirname>
214 Sets the directory name in which to read the local database.
215 Defaults to the current directory.
216
217 --prefix=<name>
218 Sets the filename prefix for the files in the local database.
219 Defaults to no prefix.
220
221 --profiles=<filename>
222 Sets the filename containing the list of routing profiles in XML
223 format. If the file doesn't exist then dirname, prefix and
224 "profiles.xml" will be combined and used, if that doesn't exist
225 then the file '/usr/local/share/routino/profiles.xml' (or custom
226 installation location) will be used.
227
228 --translations=<filename>
229 Sets the filename containing the list of translations in XML
230 format for the output files. If the file doesn't exist then
231 dirname, prefix and "translations.xml" will be combined and
232 used, if that doesn't exist then the file
233 '/usr/local/share/routino/translations.xml' (or custom
234 installation location) will be used.
235
236 --exact-nodes-only
237 When processing the specified latitude and longitude points only
238 select the nearest node instead of finding the nearest point
239 within a segment (quicker but less accurate unless the points
240 are already near nodes).
241
242 --loggable
243 Print progress messages that are suitable for logging to a file;
244 normally an incrementing counter is printed which is more
245 suitable for real-time display than logging.
246
247 --quiet
248 Don't generate any screen output while running (useful for
249 running in a script).
250
251 --language=<lang>
252 Select the language specified from the file of translations. If
253 this option is not given and the file exists then the first
254 language in the file will be used. If this option is not given
255 and no file exists the compiled-in default language (English)
256 will be used.
257
258 --output-html
259 --output-gpx-track
260 --output-gpx-route
261 --output-text
262 --output-text-all
263 Generate the selected output file formats (HTML, GPX track file,
264 GPX route file, plain text route and/or plain text with all
265 nodes). If no output is specified then all are generated,
266 specifying any automatically disables those not specified.
267
268 --output-none
269 Do not generate any output or read in any translations files.
270
271 --profile=<name>
272 Specifies the name of the profile to use.
273
274 --transport=<transport>
275 Select the type of transport to use, <transport> can be set to:
276
277 + foot = Foot
278 + horse = Horse
279 + wheelchair = Wheelchair
280 + bicycle = Bicycle
281 + moped = Moped (Small motorbike, limited speed)
282 + motorbike = Motorbike
283 + motorcar = Motorcar
284 + goods = Goods (Small lorry, van)
285 + hgv = HGV (Heavy Goods Vehicle - large lorry)
286 + psv = PSV (Public Service Vehicle - bus, coach)
287
288 Defaults to 'motorcar', this option also selects the default
289 profile information if the '--profile' option is not given and a
290 profile matching the transport name is found.
291
292 --shortest
293 Find the shortest route between the waypoints.
294
295 --quickest
296 Find the quickest route between the waypoints.
297
298 --lon1=<longitude>, --lat1=<latitude>
299 --lon2=<longitude>, --lat2=<latitude>
300 ... --lon99=<longitude>, --lat99=<latitude>
301 The location of the waypoints that make up the start, middle and
302 end points of the route. Up to 99 waypoints can be specified and
303 the route will pass through each of the specified ones in
304 sequence. The algorithm will use the closest node or point
305 within a segment that allows the specified traffic type.
306
307 --heading=<bearing>
308 Specifies the initial direction of travel at the start of the
309 route (from the lowest numbered waypoint) as a compass bearing
310 from 0 to 360 degrees.
311
312 --highway-<highway>=<preference>
313 Selects the percentage preference for using each particular type
314 of highway. The value of <highway> can be selected from:
315
316 + motorway = Motorway
317 + trunk = Trunk
318 + primary = Primary
319 + secondary = Secondary
320 + tertiary = Tertiary
321 + unclassified = Unclassified
322 + residential = Residential
323 + service = Service
324 + track = Track
325 + cycleway = Cycleway
326 + path = Path
327 + steps = Steps
328 + ferry = Ferry
329
330 Default value depends on the profile selected by the --transport
331 option.
332
333 --speed-<highway>=<speed>
334 Selects the speed limit in km/hour for each type of highway.
335 Default value depends on the profile selected by the --transport
336 option.
337
338 --property-<property>=<preference>
339 Selects the percentage preference for using each particular
340 highway property The value of <property> can be selected from:
341
342 + paved = Paved (suitable for normal wheels)
343 + multilane = Multiple lanes
344 + bridge = Bridge
345 + tunnel = Tunnel
346 + footroute = A route marked for foot travel
347 + bicycleroute = A route marked for bicycle travel
348
349 Default value depends on the profile selected by the --transport
350 option.
351
352 --oneway=[0|1]
353 Selects if the direction of oneway streets are to be obeyed
354 (useful to not obey them when walking). Default value depends on
355 the profile selected by the --transport option.
356
357 --turns=[0|1]
358 Selects if turn restrictions are to be obeyed (useful to not
359 obey them when walking). Default value depends on the profile
360 selected by the --transport option.
361
362 --weight=<weight>
363 Specifies the weight of the mode of transport in tonnes; ensures
364 that the weight limit on the highway is not exceeded. Default
365 value depends on the profile selected by the --transport option.
366
367 --height=<height>
368 Specifies the height of the mode of transport in metres; ensures
369 that the height limit on the highway is not exceeded. Default
370 value depends on the profile selected by the --transport option.
371
372 --width=<width>
373 Specifies the width of the mode of transport in metres; ensures
374 that the width limit on the highway is not exceeded. Default
375 value depends on the profile selected by the --transport option.
376
377 --length=<length>
378 Specifies the length of the mode of transport in metres; ensures
379 that the length limit on the highway is not exceeded. Default
380 value depends on the profile selected by the --transport option.
381
382 Note: In version 1.5 of Routino a slim option has been added and at
383 compilation time a separate program called router-slim is created that
384 operates in slim mode. In slim mode the database files are read as
385 needed rather than being mapped into memory.
386
387 The meaning of the <preference> parameter in the command line options
388 is slightly different for the highway preferences and the property
389 preferences. For the highway preference consider the choice between two
390 possible highways between the start and finish when looking for the
391 shortest route. If highway A has a preference of 100% and highway B has
392 a preference of 90% then highway A will be chosen even if it is up to
393 11% longer (100/90 = 111%). For the highway properties each highway
394 either has a particular property or not. If the preference for the
395 property is 60% then a highway with the property has a preference of
396 77% (sqrt(60%)) and one without has a preference of 63%
397 (sqrt(100-60%)). A highway with the property will be chosen even if it
398 is up to 22% longer than one without the property (77/63 = 122%). The
399 overall preference for each highway segment is the product of the
400 preference for the highway type and all of the preferences for the
401 highway properties.
402
403 Example usage (motorbike journey, scenic route, not very fast):
404
405 router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
406 --highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest
407
408 This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
409 'data/gb-ways.mem' to find the quickest route by motorbike not using
410 motorways or trunk roads and not exceeding 80 km/hr.
411
412
413 filedumper
414 ----------
415
416 This program is used to extract statistics from the database, extract
417 particular information for visualisation purposes or for dumping the
418 database contents.
419
420 Usage: filedumper [--help]
421 [--dir=<dirname>] [--prefix=<name>]
422 [--statistics]
423 [--visualiser --latmin=<latmin> --latmax=<latmax>
424 --lonmin=<lonmin> --lonmax=<lonmax>
425 --data=<data-type>]
426 [--dump [--node=<node> ...]
427 [--segment=<segment> ...]
428 [--way=<way> ...]
429 [--turn-relation=<relation> ...]]
430 [--dump-osm [--no-super]
431 [--latmin=<latmin> --latmax=<latmax>
432 --lonmin=<lonmin> --lonmax=<lonmax>]]
433
434 --help
435 Prints out the help information.
436
437 --dir=<dirname>
438 Sets the directory name in which to read the local database.
439 Defaults to the current directory.
440
441 --prefix=<name>
442 Sets the filename prefix for the files in the local database.
443
444 --statistics
445 Prints out statistics about the database files.
446
447 --visualiser
448 Selects a data visualiser mode which will output a set of data
449 according to the other parameters below.
450
451 --latmin=<latmin> --latmax=<latmax>
452 The range of latitudes to print the data for.
453
454 --lonmin=<lonmin> --lonmax=<lonmax>
455 The range of longitudes to print the data for.
456
457 --data=<data-type>
458 The type of data to output, <data-type> can be selected
459 from:
460
461 o junctions = segment count at each junction.
462 o super = super-node and super-segments.
463 o oneway = oneway segments.
464 o highway-* = segments of the specified highway type (e.g.
465 highway-primary to display segments ofprimary roads).
466 o transport-* = segments allowing the specified transport
467 type (e.g. transport-foot to display segments accessible
468 on foot).
469 o turns = turn restrictions.
470 o speed = speed limits.
471 o weight = weight limits.
472 o height = height limits.
473 o width = width limits.
474 o length = length limits.
475
476 --dump
477 Selects a data dumping mode which allows looking at individual
478 items in the databases (specifying 'all' instead of a number
479 dumps all of them). More than one of the following parameters
480 can be specified on the command line.
481
482 --node=<node>
483 Prints the information about the selected node number
484 (internal number, not the node id number in the original
485 source file).
486
487 --segment=<segment>
488 Prints the information about the selected segment number.
489
490 --way=<way>
491 Prints the information about the selected way number
492 (internal number, not the way id number in the original
493 source file).
494
495 --turn-relation=<relation>
496 Prints the information about the selected turn relation
497 number (internal number, not the relation id number in the
498 original source file).
499
500 --osm-dump
501 Dumps the contents of the database as an OSM format XML file,
502 the whole database will be dumped unless the latitude and
503 longitude ranges are specified.
504
505 --no-super
506 The super segments will not be output.
507
508 --latmin=<latmin> --latmax=<latmax>
509 The range of latitudes to dump the data for.
510
511 --lonmin=<lonmin> --lonmax=<lonmax>
512 The range of longitudes to dump the data for.
513
514 Note: In version 1.5 of Routino a slim option has been added and at
515 compilation time a separate program called filedumper-slim is created
516 that operates in slim mode. In slim mode the database files are read as
517 needed rather than being mapped into memory.
518
519
520 tagmodifier
521 -----------
522
523 This program is used to run the tag transformation process on an OSM
524 XML file for test purposes.
525
526 Usage: tagmodifier [--help]
527 [--loggable]
528 [--tagging=<filename>]
529 [<filename.osm>]
530
531 --help
532 Prints out the help information.
533
534 --loggable
535 Print progress messages that are suitable for logging to a file;
536 normally an incrementing counter is printed which is more
537 suitable for real-time display than logging.
538
539 --tagging=<filename>
540 The name of the XML file containing the tagging rules (defaults
541 to 'tagging.xml' in the current directory).
542
543 <filename.osm> ...
544 Specifies the filename to read data from, by default data is
545 read from the standard input.
546
547
548 --------
549
550 Copyright 2008-2012 Andrew M. Bishop.

Properties

Name Value
cvs:description Description of program usage.