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