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