Check out the latest version of Routino: svn co http://routino.org/svn/trunk routino
Contents of /trunk/doc/USAGE.txt
Parent Directory
|
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)
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. |