ben/brouter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

added profiles and readmes

Browse source
This commit is contained in:
Arndt Brenschede 2014-01-19 13:33:43 +01:00
parent 5453c7b2f8
commit 2edac085d0
10 changed files with 1542 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

176
misc/readmes/profile_developers_guide.txt Normal file
View file

@ -0,0 +1,176 @@
Profile developers guide - Technical reference
for BRouter cost-function scripts
==============================================
The tag-value lookup table
--------------------------
Within the routing data files (rd5), tag information
is encoded in a binary bitfield of 64 bit length for
the way tags and the node tags each.
To encode and decode to/from this bitfield, a lookup
table is used that contains all the tags and values
that are considered for encoding.
For each tag there are 2 special values:
- <empty> if the tag is not set or the value is empty
- "unknown" if the value is not contained in the table
An exception are "boolean tags" with exactly one value
in the lookup table - these are encoded into a single
bit and do not have the "unknown" value - in this case
unknown values are treated as empty.
Each value can have optional "aliases", these alias
values are encoded into the same binary value as the
associated primary value.
For compact encoding, the number of values per
tag in the lookup table should be a power of 2,
including the default values (<empty>, "unknown"),
so typically, a tag has 1, 2, 6, 14 or 30 values.
The numbers in the lookup table are statistical
information on the frequency of the values in the
map of germany - these are just informational and
are not processed by BRouter.
Context-Separation
------------------
Way-tags and Node-Tags are treated independently,
so there are different sections in the lookup table
as well as in the profile scripts for each context.
The special tags: "---context:way" and "---context:node"
mark the beginning of each section.
In the profile scripts there is a third context "global"
which contains global configuration which is shared for
all contexts and is accessible by the routing engine.
The variables from the "global" section in the profile
scripts are read-only visible in the "way" and
"node" sections of the scripts.
Predefined variables in the profile scripts
-------------------------------------------
Some variable names are pre-defined and accessed by
the routing engine:
- for the global section these are:
- 4 elevation configuration parameters:
- downhillcost
- downhillcutoff
- uphillcost
- uphillcutoff
- 3 boolean mode-hint flags
- validForBikes
- validForFoot
- validForCars
- and 2 variables to change the heuristic
coefficients for the 2 routing passes
( <0 disables a routing pass )
- pass1coefficient
- pass2coefficient
- for the way section these are
- turncost
- initialcost
- costfactor
- for the node section this is just
- initialcost
The operators of the profile scripts
------------------------------------
The "assign" operator is special: it can be used
only on the top level of the expression hirarchy
and has 2 operands:
assign <variable-name> <expression>
It just assigns the expression value to this
variable (which can be a predined variable or
any other variable, which in this case is defined
implicitly). The expression can be a complex expression
using other operators.
All other operators can be used recursively to an unlimted
complexity, which means that each operand can be a composed
expression starting with an operator and so on.
All expressions have one of the following basic forms:
- <numeric>
- <lookup-match>
- <1-op-operator> <operand>
- <2-op-operator> <operand> <operand>
- <3-op-operator> <operand> <operand> <operand>
- A numeric value is just a number, floating point, with "." as
decimal separtor. Boolean values are treated as numbers as well,
with "0" = false and every nonzero value = true.
- A lookup match has the form <tag-name>=<value>, e.g. highway=primary
Only the primary values can be used in lookup-matches, not aliases.
The <empty> value is refered to as an empty string, e.g. access=
- 1 Operand operators are:
not <boolean expression>
- 2 Operand operators are:
or <boolean expression 1> <boolean expression 2>
and <boolean expression 1> <boolean expression 2>
multiply <numeric expression 1> <numeric expression 2>
add <numeric expression 1> <numeric expression 2>
max <numeric expression 1> <numeric expression 2>
- 3 Operand operators are:
switch <boolean-expression> <true-expression> <false-expression>
So the switch expression has a numeric value which is the
true-expression if the boolean expression is true, the
false-expression otherwise
Technical constraints
---------------------
- The costfactor is required to be >= 1, otherwise the cost-cutoff
logic of the routing algorithm does not work and you get wrong results.
- The profile should be able to find a route with an average costfactor
not very much larger than one, because otherwise the routing algorithm
will not find a reasonable cost-cutoff, leading to a very large
search area and thus to long processing times.
- Forbidden ways or nodes must be treated as very high cost, because
there is no "forbidden" value. Please use 100000 for a (way-)costfactor,
and 1000000 for a nodes "initalcost", as these are proven values with
no overflow issues.
Developing and debugging scripts
--------------------------------
For developing scripts, the "Upload profile" funcionality and the
"Export CSV" button of the online version are your friends.
The "Export CSV" gives a (tab-separated) list of all way segments
with all tag values and with the calulated cost (in "cost per km").
These CSV-Data can be imported in Excel using "paste content" function.

217
misc/readmes/readme.txt Normal file
View file

@ -0,0 +1,217 @@
BRouter - Beta Version 0.9.8 - Setting up the Android App
=========================================================
Choosing and Installing a Map-Tool
----------------------------------
BRouter just calculates tracks as GPX-Files, it
does not display any map or give any navigation
instuctions. Therefore you need a map-tool in
order for BRouter to be useful.
Currently, BRouter cooperates with three different
maptools, so you need to install, and get familiar with,
at least one of them:
- "OsmAnd": See http://www.osmand.net Get It from Google-Play
or get it as an APK from the release-build archive:
http://download.osmand.net/releases/
I tested versions up to 1.6
- "Locus": See http://www.locusmap.eu There's a "Pro"
Version which is ad-free and a free version with ads.
You can get it from Google-Play, but for the free-version
there's also an APK-Download.
- "Oruxmaps": See http://www.oruxmaps.com Oruxmaps is
Donation-Ware, which means it's free and you're supposed
to donate to the project if you want to support it.
Which one to use is a matter of taste. Maybe OsmAnd is
more plug&play and has a reasonable voice-guidig. Locus
and Oruxmaps are more powerful and better for outdoor
use. Locus for example has elevation profile diagrams
which OsmAnd has not.
Locus and Oruxmaps are best used with third-party vector
maps, check http://www.openandromaps.org if you consider
to go for Locus or OruxMaps.
Choosing an SD-Card Base Directory
----------------------------------
Some phones (namely those with Android 4.x) have 2 logical
"SD-Cards", where the first one is internal and not an actual
Card, and the second one is a an optional "external" micro-sd-card
that can be taken out of the device.
If you have such a setup, try to make sure your map-tool uses
the external sd-card to store the offline maps and other stuff.
In OsmAnd, this works by choosing an "SD-Card base directory". Typically,
the first card in mounted on "/mnt/sdcard", while the external
one maybe mounted at "/mnt/sdcard/external_sd", but depending
on your phone it can be some other path.
In OruxMaps, path configuration is only possible for the actual
map data, but the configuration database file that BRouter tries
to access is hardwired to the /mnt/sdcard/oruxmaps directory.
As a workaround for this specific setup, you can place a
redirection file in the directory where BRouter would normally
place the gpx-files (e.g. /mnt/sdcard/oruxmaps/tracklogs).
The first line of that redirection file called "brouter.redirect"
must contain the absolute path of the directory where you want
the gpx-files to go (e.g. /storage0/oruxmaps/tracklogs).
Make sure you understand the concept of the SD-Card base-directory,
because the communication between BRouter and the Map-Tools
requires that both are using either the same base-directory,
or the maptools are using the standard base directory (/mnt/sdcard).
Selecting Waypoints in your Maptool
-----------------------------------
In order to calculate a route, BRouter needs to know
at least a starting point and an endpoint. You specify
them by creating waypoints in your map-tool.
These are called "Favorites" in OsmAnd, "POI"s in Locus
or "Wayoints" in Oruxmaps and allow to store a location
on the map and give it a name.
Pleae specify at least a waypoint called "from" for
the starting-point and another called "to" for the
endpoint (lowercase! names are case-sensitive) You
can use any category, as only the name is read by BRouter.
Optionally, you can specify more waypoints:
"via1" ... "via9" to specify stop-overs
"nogo[radius] [name]" to specify a nogo-area,
where radius (in Meter) is optional and defaults to 20m,
and the name is also optional. So "nogo", "nogo1000",
"nogo roadblock", "nogo200 badferry" are all valid
nogo-waypoints.
Make sure to not create duplicates for the from, to and via-waypoints,
as BRouter would complain about duplicates. For nogo-areas,
duplicates are allowed.
Starting from version 0.97, instead of following the from/to/via
naming convention, you can choose any names and select them from
withing BRouter.
Installing the BRouter App
--------------------------
Download the file "brouter_0_8.zip" and unpack in a directory
"brouter" on the SD-Card of your Android Device. Most convenient
is to attach the device (or just the sd-card) to a desktop-computer
and do the unpacking there, but doing that on the device itself
is also possible, provided you know the appropriate tools.
Install the BRouter-App by installing the APK-File "BRouter.apk"
For instructions how to install from an APK (in contrast to
installing from Google Play), search the internet for tips.
You may need to change system configuration, some setting like
"Applications->Unknown sources" depending on Android version.
The BRouter App asks for permissions to access the SD-Card
and to de-activate the screen saver. Being an offline app,
it does NOT ask for internet access. The drawback is that
you have to install the additional resources manually.
BRouter's SD-Card Directory Structure
-------------------------------------
BRouter guesses a reasonable sd-card base directory and on
first start prompts you for a base directory with it's
guess as a default. You should choose the same base
directory that is used by your map-tool.
On first start, BRouter will create a "brouter" subdirectory
relative to that base-directory if it's not already there
(becaused you created it by unpacking the zip-file, see above)
If later on you want to change the base directory, you can delete
or rename the 'brouter' subfolder, so it will prompt again for
a base directory. You should choose the same base directory that
is used by your map-tool (OsmAnd or Locus).
So you may end up with e.g. the following directory structure
(depending on base dir and your map-tool choice):
/mnt/sdcard/brouter
/mnt/sdcard/brouter/segments2 <- put routing data files (*.rd5) here
/mnt/sdcard/brouter/profiles2 <- put lookup-table and routing profiles here
/mnt/sdcard/osmand <- OsmAnd's sd-card dir
/mnt/sdcard/osmand/track <- OsmAnd's track storage
/mnt/sdcard/Locus <- Locus's sd-card dir
/mnt/sdcard/Locus/mapitems <- Locus's track storage
/mnt/sdcard/oruxmaps <- Oruxmaps's sd-card dir
/mnt/sdcard/oruxmaps/tracklogs <- Oruxmaps's track storage
Starting with version 0.94, if a non-standard base directory
is choosen (e.g. /mnt/sdcard/external_sd) BRouter tries to
additionally to access the configuraion files relative
to the standard base directory ( /mnt/sdcard )
The minimum files BRouter needs to work are e.g.
/mnt/sdcard/brouter/segments2/E5_N45.rd5
/mnt/sdcard/brouter/profiles2/lookups.dat
/mnt/sdcard/brouter/profiles2/trekking.brf
But of course you can put as many routing data files
and routing profiles as you like.
Get the profiles (*.brf) and the lookup.dat from
the zip-file or from:
http://www.dr-brenschede.de/brouter/profiles2
And the routing data files from:
http://h2096617.stratoserver.net/brouter/segments2
Routing data files are organised as 5*5 degree files,
with the Filename containing the south-west corner
of the square, which means:
- You want to route near West48/North37 -> get W50_N35.rd5
- You want to route near East7/North47 -> get E5_N45.rd5
From the above link you find routing data for all
places in the world where OSM data is available.
Starting the BRouter Android-APP
--------------------------------
Make sure you selected "from" and "to" waypoints
in your maptool as decsribed above.
Then you can start BRouter. It will read the waypoints
from the map-tools database, calculate the route and
store the result as "brouter0.gpx" in the map-tools
track directory.
BRouter shows a graphical animation of the routing
algorithm, and shows some messages on distances
and ascends. The "filtered ascend" is a measure
for the real hill-climbing pain, with small
variations filtered out.
Then you can use your maptool to view or navigate the
route.
If started once more with identical input,
BRouter will store a second route broute1.gpx
for the first alternative and so on.

47
misc/readmes/readme_car_subset.txt Normal file
View file

@ -0,0 +1,47 @@
BRouter - Beta Version 0.9.5 - Using the car-subset datafiles
==========================================================
Starting with version 0.9.5, BRouter supports car-subset
datafiles as a workaround for the memory issue in car routing.
Car-routing, however, is still considered experimental,
mainly due to the fact that turn-restrictions are still
not handled.
The cause of the memory overflow in long-distance car-routing
is the fact that a large fraction of the ways is not allowed
for cars and that the node-cache-pipe of brouter is not designed
to handle that. So the car-subset datafiles (".cd5") are identical
to the full datafiles (".rd5"), but do not contain the nodes
and ways that are not accessible for cars.
Using the car-subset datafiles, car-routing over longer
distances is possible, and it it somewhat faster than using
the full datafiles.
The car subset datafiles must be stored in a subdirectory
"carsubset" of the "segments2" directory, so a possible
file-system structure looks like this:
brouter/segments2/E5_N45.rd5
brouter/segments2/carsubset/E5_N45.cd5
You can download the cd5's from the corresponding URL
just like the rd5's.
Access to the car-subset datafiles is enabled
by assigning the routing-profile variable:
assign validForCars 1
as it is done for the "car-test" profile. In that case,
the router first checks for the car-subset file, and,
if it does not exist, uses the full datafile. It is
o.k. to just install the car-subset file without
having the full datafile installed.
If you want to use the car-subset datafile for bike-routing
(because you don't have the full datafile or because you
are using streets only anyhow and want better performance),
just assign the "validForCars" variable in your biking
profile as indicated above.

72
misc/readmes/readme_service.txt Normal file
View file

@ -0,0 +1,72 @@
BRouter - Beta Version 0.9.5 - Using the service interface
==========================================================
Starting with version 0.9.3, BRouter contains a *NEW* service interface.
The HTTP-Interface introduced in 0.9.1-0.9.2 was dropped
The new service interface is an Android service that can be called
from other apps. See the file IBRouterService.aidl for the
interface definition.
Following map-tools implement this interface:
- OruxMaps starting with version 5.5.3
- Locus in the current version
- (for OsmAnd, pull-request is pending: https://github.com/osmandapp/Osmand/pull/537 )
The service interface defines a default timeout of 60 seconds
(if not modified by the caller), so you can only calculate
medium distance routes via the service interface. For long
distance calculations, you would run into the timeout, so
you have to use BRouter's classical operation mode at least
for an initial calculation. But read below on how timeout-free
recalculations work even for long-distance applications.
The configuration concept in the service interface
--------------------------------------------------
BRouter is fully configurable via the use of profile
definition files and a list of nogo-areas, while
the service interface is usually accessed by just
choosing one o the 6 "standard routing modes" made
of a combination of the car/bike/foot and the
shortest/fastest selection.
Therefore, you need a mapping between the standard routing mode
and BRouter's configuration. There is no default mapping
deployed with the BRouter distribution file, so you have
to configure this yourself. You can do that by starting
BRouter is the "normal" way and at the end of the routing
process, press the "Server Mode" button. Then you get
a list of standard routing mode with a preselection,
where you can choose for which of the 6 standard modes
you want to store the configuration just used.
(profile + nogo-list). Please note that the profile
is stored by reference (so modifications at the profile
file afterwards will have effect), while the nogo-areas
are stored by value (so modifying the nogo-waypoints
afterwards will have no effect)
Timeout-free recalculations
---------------------------
A new feature in zje service-interface of version 0.95 is that
you can follow a long-distance route and have (nearly) correct
recalculations when getting of the track, without running
into the 60-seconds timeout.
For that, a valid route to the destination must be known
for the current routing-mode. This can be achieved either
by calculating the route via the brouter-app and storing
it by pressing the "server-mode" button when done.
Or it is done implicitly by the service-mode itself once
it was able to do the calcultion within the timeout -
in that case, subsequent recalcs for the same destination
also make use of the known valid track for faster
processing.
The destination must be identical in a digital sense
(+- 20 microdegrees), so make sure to use the same waypoint,
do not re-enter it as a map-location.