git.maemo.org Git - routino/blob - doc/USAGE.txt

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