Program Usage
                                =============

Program Usage

   There are three programs that make up this software. The first one
   takes the planet.osm datafile from OpenStreetMap (or other source of
   data using the same formats) and converts it into a local database. The
   second program uses the database to determine an optimum route between
   two points. The third program allows visualisation of the data and
   statistics to be extracted.

planetsplitter

   Usage: planetsplitter
                         [--help]
                         [--slim] [--tmpdir=<name>]
                         [--dir=<name>] [--prefix=<name>]
                         [--max-iterations=<number>]
                         [--transport=<transport>]
                         [--not-highway=<highway> ...]

   --help
          Prints out the help information.

   --dir=<name>
          Sets the directory name in which to save the results. Defaults
          to the current directory.

   --prefix=<name>
          Sets the filename prefix for the files that are created.
          Defaults to no prefix.

   --max-iterations=<number>
          The maximum number of iterations to use when generating
          super-nodes and super-segments. Defaults to 10 which is normally
          enough.

   --transport=<transport>
          Allows selection of only the routes that are possible for a
          particular type of transport. Defaults to all transport types
          allowed (see the router for the list of possible transport
          types).

   --not-highway=<highway>
          Allows particular types of highways to be ignored, <highway> can
          be selected from:
             + motorway = Motorway
             + trunk = Trunk
             + primary = Primary
             + secondary = Secondary
             + tertiary = Tertiary
             + unclassified = Unclassified
             + residential = Residential
             + service = Service
             + track = Track
             + path = Path
             + bridleway = Bridleway
             + cycleway = Cycleway
             + footway = Footway
          Defaults to all highway types allowed. This option may be
          repeated.

   --slim
          Selects a mode of operation that uses less memory and will
          therefore work where virtual memory is very limited or
          unavailable. Selecting this option will cause raw data to be
          held in disk files with only indexes in RAM. Not using this
          option will still use disk files but only for sequential access
          and the files are memory mapped for random access.

   --tmpdir=<name>
          Specifies the name of the directory to store the temporary disk
          files. If not specified then it defaults to either the value of
          the --dir option or the current directory.

   Example usage:

   bunzip2 -c great_britain.osm.bz2 | ./planetsplitter --dir=data --prefix=gb

   This will generate the output files 'data/gb-nodes.mem',
   'data/gb-segments.mem' and 'data/gb-ways.mem'.

router

   Usage: router [--lon1=]<longitude> [--lat1=]<latitude>
                 [--lon2=]<longitude> [--lon2=]<latitude>
                 [ ... [--lon99=]<longitude> [--lon99=]<latitude> ]
                 [--help | --help-profile | --help-profile-js | --help-profile-pl]
                 [--dir=<name>] [--prefix=<name>]
                 [--shortest | --quickest]
                 [--quiet]
                 [--transport=<transport>]
                 [--highway-<highway>=<preference> ...]
                 [--speed-<highway>=<speed> ...]
                 [--oneway=[0|1]]
                 [--weight=<weight>]
                 [--height=<height>] [--width=<width>] [--length=<length>]

   --lon1=<longitude>, --lat1=<latitude>
   --lon2=<longitude>, --lat2=<latitude>
   ...
   --lon99=<longitude>, --lat99=<latitude>
          The location of the points that make up the start, middle and
          end points of the route. Up to 99 points can be specified and the
          route will pass through each of the specified ones in sequence.

   --help
          Prints out the help information.

   --help-profile
          Prints out the selected transport profile (type, speed limits,
          highway preferences etc.)

   --help-profile-js
          Prints out all the compiled-in profiles as a set of Javascript
          arrays for use in the interactive webpage.

   --help-profile-pl
          Prints out all the compiled-in profiles as a set of Perl arrays
          for use in the router CGI.

   --dir=<name>
          Sets the directory name in which to read the local database.
          Defaults to the current directory.

   --prefix=<name>
          Sets the filename prefix for the files in the local database.
          Defaults to no prefix.

   --shortest
          Find the shortest route.

   --quickest
          Find the quickest route.

   --quiet
          Don't generate any screen output while running (useful for
          running in a script).

   --transport=<transport>
          Select the type of transport to use, <transport> can be set to:
             + foot = Foot
             + bicycle = Bicycle
             + horse = Horse
             + motorbike = Motorbike
             + motorcar = Motorcar
             + goods = Goods (Small lorry, van)
             + hgv = HGV (Heavy Goods Vehicle - large lorry)
             + psv = PSV (Public Service Vehicle - bus, coach)
          Defaults to 'Motorcar', this option also selects the default
          profile information.

   --highway-<highway>=<preference>
          Selects the percentage preference for using each particular type
          of highway (see the planetsplitter for the list of highway
          types). Default value depends on the profile selected by the
          --transport option.

   --speed-<highway>=<speed>
          Selects the speed limit in km/hour for each type of highway.
          Default value depends on the profile selected by the --transport
          option.

   --oneway=[0|1]
          Selects if the direction of oneway streets are to be obeyed
          (useful to not obey them when walking). Default value depends on
          the profile selected by the --transport option.

   --weight=<weight>
          Specifies the weight of the mode of transport in tonnes, ensures
          that the weight limit on the highway is not exceeded. Default
          value depends on the profile selected by the --transport option.

   --height=<height>
          Specifies the height of the mode of transport in metres, ensures
          that the height limit on the highway is not exceeded. Default
          value depends on the profile selected by the --transport option.

   --width=<width>
          Specifies the width of the mode of transport in metres, ensures
          that the width limit on the highway is not exceeded. Default
          value depends on the profile selected by the --transport option.

   --length=<length>
          Specifies the length of the mode of transport in metres, ensures
          that the length limit on the highway is not exceeded. Default
          value depends on the profile selected by the --transport option.

   Example usage (motorbike journey, scenic route, not very fast):

   ./router --dir=data --prefix=gb --transport=motorbike --highway-motorway=0 \
            --highway-trunk=0 --speed-primary=80 --speed-secondary=80 --quickest

   This will use the files 'data/gb-nodes.mem', 'data/gb-segments.mem' and
   'data/gb-ways.mem' to find the quickest route by motorbike not using
   motorways or trunk roads and not exceeding 80 km/hr.

   If there is a file in the specified directory with the specified prefix
   and a basename of "copyright.txt" (i.e. 'data/gb-copyright.txt' in the
   example) this file will be read in and the contents used in the
   generated files. The file is read in and the two lines starting with
   'Source:' and 'License:' are extracted and used in the output files.

   An appropriate file for use with data derived from OpenStreetMap data
   would be the following:

   Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
   License: http://creativecommons.org/licenses/by-sa/2.0/

filedumper

   Usage: filedumper
                     [--help]
                     [--dir=<name>] [--prefix=<name>]
                     [--statistics]
                     [--visualiser --latmin=<latmin> --latmax=<latmax>
                                   --lonmin=<lonmin> --lonmax=<lonmax>
                                   --data=<data-type>]
                     [--dump --node=<node> ...
                             --segment=<segment> ...
                             --way=<way> ...]

   --help
          Prints out the help information.

   --dir=<name>
          Sets the directory name in which to read the local database.
          Defaults to the current directory.

   --prefix=<name>
          Sets the filename prefix for the files in the local database.

   --statistics
          Prints out statistics about the database files.

   --visualiser
          Selects a data visualiser mode which will output a set of data
          according to the other parameters below.

        --latmin=<latmin> --latmax=<latmax>
                The range of latitudes to print the data for.

        --lonmin=<lonmin> --lonmax=<lonmax>
                The range of longitudes to print the data for.

        --data=<data-type>
                The type of data to output, <data-type> can be selected
                from:
               o junctions = segment count at each junction.
               o super = super-node and super-segments.
               o oneway = oneway segments.
               o speed = speed limits.
               o weight = weight limits.
               o height = height limits.
               o width = width limits.
               o length = length limits.

   --dump
          Selects a data dumping mode which allows looking at individual
          items in the databases.

        --node=<node>
                Prints the information about the selected node number
                (internal number, not the node number in the original
                source file).

        --segment=<segment>
                Prints the information about the selected segment number.

        --way=<way>
                Prints the information about the selected way number.


Router Output

   There are two different formats of output from the router, plain text
   and GPX (GPS eXchange) XML format. There are a total of four possible
   outputs from the router program: a GPX track file, a GPX route file
   with waypoints at junctions, a text description with the junctions and
   a text file with every node.

   The output files are written to the current directory and are named
   depending on the selection of shortest or quickest route. For the
   shortest route the file names are "shortest-track.gpx",
   "shortest-route.gpx", "shortest.txt" and "shortest-all.txt", for the
   quickest route the names are "quickest-track.gpx",
   "quickest-route.gpx", "quickest.txt" and "quickest-all.txt".

GPX Track File

   The GPX track file contains a track with all of the individual nodes
   that the route passes through.

   An example GPX track file output is below:

   <?xml version="1.0" encoding="UTF-8"?>
   <gpx version="1.1" creator="Routino"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="http://www.topografix.com/GPX/1/1"
           xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
   <metadata>
   <desc><![CDATA[Shortest route between 'start' and 'finish' waypoints]]></desc>
   <copyright author="Based on OpenStreetMap data from http://www.openstreetmap.org/">
   <license>http://creativecommons.org/licenses/by-sa/2.0/</license>
   </copyright>
   </metadata>
   <trk>
   <trkseg>
   <trkpt lat="51.524676" lon="-0.127896"/>
   <trkpt lat="51.523829" lon="-0.126993"/>
   ...
   <trkpt lat="51.478354" lon="-0.103561"/>
   <trkpt lat="51.478244" lon="-0.103652"/>
   </trkseg>
   </trk>
   </gpx>

GPX Route File

   The GPX route file contains a route (ordered set of waypoints) with all
   of the junctions that the route passes through.

   An example GPX route file output is below:

   <?xml version="1.0" encoding="UTF-8"?>
   <gpx version="1.1" creator="Routino"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="http://www.topografix.com/GPX/1/1"
           xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
   <metadata>
   <desc><![CDATA[Shortest route between 'start' and 'finish' waypoints]]></desc>
   <copyright author="Based on OpenStreetMap data from http://www.openstreetmap.org/">
   <license>http://creativecommons.org/licenses/by-sa/2.0/</license>
   </copyright>
   </metadata>
   <rte>
   <name>Shortest route</name>
   <rtept lat="51.524676" lon="-0.127896"><name>START</name></rtept>
   <rtept lat="51.523829" lon="-0.126993"><name>TRIP001</name></rtept>
   ...
   <rtept lat="51.480314" lon="-0.108381"><name>TRIP015</name></rtept>
   <rtept lat="51.478244" lon="-0.103652"><name>FINISH</name></rtept>
   </rte>
   </gpx>

Text File

   The text file format contains one entry for all of the junctions in the
   route and is intended to be easy to interpret.

   An example Text file output is below:

   # Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
   # License: http://creativecommons.org/licenses/by-sa/2.0/
   #
   #Latitude   Longitude    Segment   Segment    Total     Total   Highway
   #                        Distance  Duration   Distance  Durat'n
    51.524676    -0.127896  0.000 km    0.0 min    0.0 km    0 min
    51.523829    -0.126993  0.113 km    0.1 min    0.1 km    0 min Woburn Place
   ...
    51.480314    -0.108381  0.200 km    0.1 min    5.9 km    5 min Camberwell New Road (A202)
    51.478244    -0.103652  0.411 km    0.3 min    6.3 km    5 min Vassall Road

   The text file output contains a header (indicated by the lines starting
   with '#') and then one line for each junction. Each line contains the
   information for the route up to that point. For each of the lines the
   latitude and longitude are the first two items. The length of the
   segment in km and the journey duration for the segment in minutes are
   the next two items. The cumulative journey distance and duration are
   the 6th and 7th items and the final item is the name of the highway.
   The individual items are separated by tabs but some of the items
   contain spaces as well.

All Nodes Text File

   The all nodes text file format contains one entry for each of the nodes
   on the route.

   An example all nodes text file output is below:

   # Source: Based on OpenStreetMap data from http://www.openstreetmap.org/
   # License: http://creativecommons.org/licenses/by-sa/2.0/
   #
   #Latitude   Longitude       Node   Segment Segment Total  Total   Speed  Highway
   #                                  Dist    Durat'n Dist   Durat'n

    51.524676    -0.127896  4830582*  0.000    0.00    0.00    0.0
    51.523829    -0.126993  4830562*  0.113    0.14    0.11    0.1    96    Woburn Place
   ...
    51.478354    -0.103561  4904816*  0.104    0.07    6.30    5.1    96    Camberwell New Road (A202)
    51.478244    -0.103652  4908481   0.013    0.01    6.31    5.1    64    Vassall Road

   The all nodes text file output is similar to the text file output
   except that a line is printed for each of the nodes rather than just
   the junctions. The additional information on each line is the node
   number (not the OpenStreetMap node number but an internal value) as
   well as an indicator for the super-nodes and the speed for the segment.


--------

Copyright 2008,2009 Andrew M. Bishop.