diff --git a/README.md b/README.md index f6bf6a9..b1fcbc2 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ You can install the BRouter app on your Android device from Store](https://play.google.com/store/apps/details?id=btools.routingapp). You can also [build BRouter](#build-and-install) yourself. You can find detailed documentation of the BRouter Android app in -[`misc/readmes/readme.txt`](misc/readmes/readme.txt). +[`docs/users/android_quickstart.md`](docs/users/android_quickstart.md). Get it on F-Droid @@ -39,7 +39,7 @@ Alternatively, you can also use BRouter as the offline routing engine for [OSMAnd](https://osmand.net/) on your Android device. A full documentation on how to set this up is available at -[`misc/readmes/osmand/README.md`](misc/readmes/osmand/README.md). +[`docs/users/osmand.md`](docs/users/osmand.md). ## BRouter on Windows/Linux/Mac OS @@ -106,7 +106,7 @@ You can also generate the segments files you need directly from a planet dump of OpenStreetMap data (or a [GeoFabrik extract](https://download.geofabrik.de/)). More documentation of this is available in the -[`misc/readmes/mapcreation.md`](misc/readmes/mapcreation.md) file. +[`docs/developers/build_segments.md`](docs/developers/build_segments.md) file. ### (Optional) Generate profile variants @@ -120,7 +120,7 @@ to help you quickly generate variants based on the default profiles, to create a default set of profiles covering most of the basic use cases. Have a look at the -[`misc/readmes/profile_developers_guide.txt`](misc/readmes/profile_developers_guide.txt) +[`docs/developers/profile_developers_guide.md`](docs/developers/profile_developers_guide.md) for an in-depth guide on profiles edition and customization. @@ -140,7 +140,7 @@ file. ## Documentation -More documentation is available in the [`misc/readmes`](misc/readmes) folder. +More documentation is available in the [`docs`](docs) folder. ## Related Projects diff --git a/brouter-routing-app/build.gradle b/brouter-routing-app/build.gradle index d254021..aa4c375 100644 --- a/brouter-routing-app/build.gradle +++ b/brouter-routing-app/build.gradle @@ -89,7 +89,11 @@ android { } applicationVariants.all { - variant -> tasks["merge${variant.name.capitalize()}Assets"].dependsOn(generateProfilesZip) + variant -> + { + tasks["merge${variant.name.capitalize()}Assets"].dependsOn(generateProfilesZip) + tasks["merge${variant.name.capitalize()}Assets"].dependsOn(generateReadmesZip) + } } } @@ -122,10 +126,22 @@ task generateProfilesZip(type: Zip) { dependsOn generateProfiles } archiveFileName = "profiles2.zip" - from "../misc/profiles2" - exclude "all.brf" - exclude "car-traffic_analysis.brf" - exclude "car-vario.brf" - exclude "softaccess.brf" - destinationDirectory = layout.buildDirectory.dir('assets') + from("../misc/profiles2") { + exclude "all.brf" + exclude "car-traffic_analysis.brf" + exclude "car-vario.brf" + exclude "softaccess.brf" + } + destinationDirectory = layout.buildDirectory.dir("assets") +} + +task generateReadmesZip(type: Zip) { + archiveFileName = "readmes.zip" + from("../docs") { + include("users/android_quickstart.md") + include("users/android_advanced.md") + include("developers/profile_developers_guide.md") + include("developers/build_segments.md") + } + destinationDirectory = layout.buildDirectory.dir("assets") } diff --git a/brouter-routing-app/src/main/assets/readmes.zip b/brouter-routing-app/src/main/assets/readmes.zip deleted file mode 100644 index 0f24abd..0000000 Binary files a/brouter-routing-app/src/main/assets/readmes.zip and /dev/null differ diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..d3382e0 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,6 @@ +_site +.bundle +.sass-cache +.jekyll-cache +.jekyll-metadata +vendor diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 0000000..5e1bb16 --- /dev/null +++ b/docs/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..7bfae82 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,29 @@ +source "https://rubygems.org" +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! + +# Use the github-pages bundle by default +# gem "jekyll", "~> 4.2.1" +gem "github-pages", group: :jekyll_plugins + +# If you have any plugins, put them here! +group :jekyll_plugins do + # gem "jekyll-feed", "~> 0.12" +end + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", "~> 1.2" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin] + diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..c561ddf --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,280 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (6.0.4.1) + concurrent-ruby (~> 1.0, >= 1.0.2) + i18n (>= 0.7, < 2) + minitest (~> 5.1) + tzinfo (~> 1.1) + zeitwerk (~> 2.2, >= 2.2.2) + addressable (2.8.0) + public_suffix (>= 2.0.2, < 5.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.17.13) + ruby-enum (~> 0.5) + concurrent-ruby (1.1.9) + dnsruby (1.61.7) + simpleidn (~> 0.1) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + ethon (0.15.0) + ffi (>= 1.15.0) + eventmachine (1.2.7) + execjs (2.8.1) + faraday (1.8.0) + faraday-em_http (~> 1.0) + faraday-em_synchrony (~> 1.0) + faraday-excon (~> 1.1) + faraday-httpclient (~> 1.0.1) + faraday-net_http (~> 1.0) + faraday-net_http_persistent (~> 1.1) + faraday-patron (~> 1.0) + faraday-rack (~> 1.0) + multipart-post (>= 1.2, < 3) + ruby2_keywords (>= 0.0.4) + faraday-em_http (1.0.0) + faraday-em_synchrony (1.0.0) + faraday-excon (1.1.0) + faraday-httpclient (1.0.1) + faraday-net_http (1.0.1) + faraday-net_http_persistent (1.2.0) + faraday-patron (1.0.0) + faraday-rack (1.0.0) + ffi (1.15.4) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (222) + github-pages-health-check (= 1.17.9) + jekyll (= 3.9.0) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.1.6) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.15.1) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.13.0) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.7.1) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.12.0) + kramdown (= 2.3.1) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.3) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.12.5, < 2.0) + rouge (= 3.26.0) + terminal-table (~> 1.4) + github-pages-health-check (1.17.9) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (>= 3.0, < 5.0) + typhoeus (~> 1.3) + html-pipeline (2.14.0) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.8.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.9.0) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.7.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.3.1) + commonmarker (~> 0.14) + jekyll (>= 3.7, < 5.0) + jekyll-commonmark-ghpages (0.1.6) + commonmarker (~> 0.17.6) + jekyll-commonmark (~> 1.2) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.15.1) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.13.0) + jekyll (>= 3.4, < 5.0) + octokit (~> 4.0, != 4.4.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.7.1) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.12.0) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + kramdown (2.3.1) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.3) + listen (3.7.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.14.4) + multipart-post (2.1.1) + nokogiri (1.12.5-x86_64-linux) + racc (~> 1.4) + octokit (4.21.0) + faraday (>= 0.9) + sawyer (~> 0.8.0, >= 0.5.3) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (4.0.6) + racc (1.6.0) + rb-fsevent (0.11.0) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.5) + rouge (3.26.0) + ruby-enum (0.9.0) + i18n + ruby2_keywords (0.0.5) + rubyzip (2.3.2) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.8.2) + addressable (>= 2.3.5) + faraday (> 0.8, < 2.0) + simpleidn (0.2.1) + unf (~> 0.1.4) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.4.0) + ethon (>= 0.9.0) + tzinfo (1.2.9) + thread_safe (~> 0.1) + unf (0.1.4) + unf_ext + unf_ext (0.0.8) + unicode-display_width (1.8.0) + zeitwerk (2.5.1) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + github-pages + tzinfo (~> 1.2) + tzinfo-data + wdm (~> 0.1.1) + +BUNDLED WITH + 2.2.32 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..a367695 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,65 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. +# +# If you need help with YAML syntax, here are some quick references for you: +# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml +# https://learnxinyminutes.com/docs/yaml/ +# +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. + +title: BRouter +description: >- # this means to ignore newlines until "baseurl:" + BRouter is a configurable OSM offline router with elevation awareness, Java + + Android. Designed to be multi-modal with a particular emphasis on bicycle and + energy-based car routing. +baseurl: "/brouter" # the subpath of your site, e.g. /blog +# url: "" # the base hostname & protocol for your site, e.g. http://example.com + +# Build settings +remote_theme: pmarsceill/just-the-docs +color_scheme: brouter + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/zod/brouter" +gh_edit_branch: docs +gh_edit_source: docs +gh_edit_view_mode: tree + +aux_links: + "GitHub": + - "//github.com/abrensch/brouter" + "Discussion Foum": + - "https://groups.google.com/group/osm-android-bikerouting" + +# Exclude from processing. +# The following items will not be processed, by default. +# Any item listed under the `exclude:` key here will be automatically added to +# the internal "default list". +# +# Excluded items can be processed by explicitly listing the directories or +# their entries' file path in the `include:` list. +# +# exclude: +# - .sass-cache/ +# - .jekyll-cache/ +# - gemfiles/ +# - Gemfile +# - Gemfile.lock +# - node_modules/ +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/docs/_sass/color_schemes/brouter.scss b/docs/_sass/color_schemes/brouter.scss new file mode 100644 index 0000000..e37cb45 --- /dev/null +++ b/docs/_sass/color_schemes/brouter.scss @@ -0,0 +1 @@ +$link-color: $blue-000; diff --git a/docs/developers/algorithm.md b/docs/developers/algorithm.md new file mode 100644 index 0000000..fc123e8 --- /dev/null +++ b/docs/developers/algorithm.md @@ -0,0 +1,98 @@ +--- +title: "Routing algorithm" +parent: Developers +--- + +# Routing algorithm: 2-pass routing with adaptive cost-cutoff + +There's not so much to say about the routing algorithm, because the basic ideas +like [Dijkstra's algorithm](http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) +or the [A-Star algorithm](http://en.wikipedia.org/wiki/A*_search_algorithm) are +well documented. + +Since Dijkstra uses only the path-cost-function `g(x)`, while A-Star add's the +remaining air-distance to the destination as a *future-cost-function* `h(x)`, +you can consider both algorithms to be equivalent if you introduce a *heuristic +coefficient* `c`: + +``` +cost-function = g(x) + c*h(x) +``` + +It is known that you get a correct result if `c` is in the range 0..1, and if +`g(x)` and `h(x)` satisfy some conditions. + +For `c>1` you do not get a correct result. However, if c is larger than the +average ratio of the path cost-function g(x) and the air-distance, you get a +quick heuristic search which is heading towards the destination with a +processing time that scales linear with distance, not quadratic as for a correct +(`c<1`) search. + +BRouter uses a 2-pass algorithm as a mixed approach with e.g. `c=1.5` for the +first pass and `c=0` for the second pass. The trick here is that the second pass +can use a cost-cutoff from the maximum-cost-estimate that the first pass +delivers to limit the search area, because any path with a remaining +air-distance larger than the difference of the current cost and the maximum cost +estimate can be dropped. And this cost-cutoff is adaptive: if during the second +pass a match is found with the first pass result, the maximum cost estimate is +lowered on-the-fly if this match gives a combined path with a lower cost. + +For recalculations, where you still know the result from the last calculation +for the same destination, the first pass can be skipped, by looking for a match +with the last calculations result. You can expect to find such a match and thus +a maximum cost estimate soon enough, so you get an effective limit on the search +area. If a recalculation does not finish within a given timeout, it's usually +o.k. to publish a merged track from the best match between the new and the old +calculation, because the far-end of a route usually does not change by an +immediate recalculation in case you get off the track. + +The reason that `c=0` (=Dijkstra) is used in the second pass and not `c=1` +(=A-Star) is simply that for `c=0` the open-set is smaller, because many paths +run into the cutoff at an early time and do not have to be managed in the +open-set anymore. And because the size of the open-set has an impact on +performance and memory consumption, c=0 is choosen for the second pass. The +open-set is what's displayed in the graphical app-animation of the brouter-app. + +However, you can change the coefficients of both passes in the routing-profile +via the variables `pass1coefficient` and `pass2coefficient`, as you can see in +the car-test profile. A negative coefficient disables a pass, so you can e.g. +force BRouter to use plain A-Star with: + +``` +assign pass1coefficient=1 +assign pass2coefficient=-1 +``` + +or do some super-fast dirty trick with *non-optimal* results (there are routers +out there doing that!!): + +``` +assign pass1coefficient=2 +assign pass2coefficient=-1 +``` + +Some more words on the conditions that the path-cost-funtion g(x) has to +fullfill. Mathematically it reads that you need *non-negative edge costs*, but +the meaning is that at the time you reach a node you must be sure that no other +path reaching this node at a later time can lead to a better result over all. + +If you have *turn-costs* in your cost function, this is obviously not the case, +because the overall result depends and the angle at which the next edge is +leaving this node.... However, there's a straight forward solution for that +problem by redefining edges and nodes: in BRouter, *nodes* in the Dijkstra-sense +are not OSM-Nodes, but the links between them, and the edges in the Dijkstra +sense are the transitions between the links at the OSM-Nodes. With that +redefinition, *turn-cost* and also *initial-costs* become valid terms in the +path-cost-function. + +However, there's still a problem with the elevation term in the cost-function, +because this includes a low-pass-filter applied on the SRTM-altitudes that +internally is implemented as an *elevation-hysteresis-buffer* that is managed +parallel to the path's cost. So the path's cost is no longer the *true cost* of +a path, because the hysteresis-buffer contains potential costs that maybe +realized later, or maybe not. + +Strictly speaking, neither Dijkstra nor A-Star can handle that. And in BRouter, +there's no real solution. There's a mechanism to delay the node-decision one +step further and so to reduce the probablity of glitches from that dirtyness, +but mainly the solution is *don't care*. diff --git a/docs/developers/android_service.md b/docs/developers/android_service.md new file mode 100644 index 0000000..f9165a5 --- /dev/null +++ b/docs/developers/android_service.md @@ -0,0 +1,10 @@ +--- +parent: Developers +--- + +# Android Service + +BRouter exposes an [Android +Service](https://developer.android.com/guide/components/services) which can be +used by other applications to calculate routes. See `IBRouterService.aidl` for +the interface definition. diff --git a/misc/readmes/mapcreation.md b/docs/developers/build_segments.md similarity index 93% rename from misc/readmes/mapcreation.md rename to docs/developers/build_segments.md index 1a5bee4..604d8eb 100644 --- a/misc/readmes/mapcreation.md +++ b/docs/developers/build_segments.md @@ -1,10 +1,16 @@ -Build your own BRouter segments files -===================================== +--- +parent: Developers +title: Build segment files +--- + +Build your own segments files +============================= BRouter uses its own data format (`.rd5` files), split in tiles of 5 x 5 in latitude and longitude. You can download the official segment files (weekly built) from [brouter.de](http://brouter.de/brouter/segments4/) but you can -also build them yourself from an OSM dump. +also build them yourself from an OSM dump (e.g. planet or [GeoFabrik +extract](https://download.geofabrik.de/)) ## Build the pbfparser diff --git a/docs/developers/http_server.md b/docs/developers/http_server.md new file mode 100644 index 0000000..d00e454 --- /dev/null +++ b/docs/developers/http_server.md @@ -0,0 +1,16 @@ +--- +parent: Developers +title: HTTP server +--- + +# Run the BRouter HTTP server + +Helpers scripts are provided in `misc/scripts/standalone` to quickly spawn a +BRouter HTTP server for various platforms. + +* Linux/Mac OS: `./misc/scripts/standalone/server.sh` +* Windows (using Bash): `./misc/scripts/standalone/server.sh` +* Windows (using CMD): `misc\scripts\standalone\server.cmd` + +The API endpoints exposed by this HTTP server are documented in the +`ServerHandler.java` diff --git a/docs/developers/index.md b/docs/developers/index.md new file mode 100644 index 0000000..495760f --- /dev/null +++ b/docs/developers/index.md @@ -0,0 +1,24 @@ +--- +title: Developers +has_children: true +nav_order: 4 +--- + +# Developer Information + +## Profile Development + +BRouter offers [freely configurable routing profiles](../features/costfunctions.md). +To extend existing profiles or develop +you own profile see [Profile Developers Guide](profile_developers_guide.md) for +a technical reference. + +### (Optional) Generate profile variants + +This repository holds examples of BRouter profiles for many different +transportation modes. Most of these can be easily customized by setting +variables in the first `global` context of the profiles files. + +An helper script is available in `misc/scripts/generate_profile_variants.sh` +to help you quickly generate variants based on the default profiles, to create +a default set of profiles covering most of the basic use cases. diff --git a/docs/developers/profile_developers_guide.md b/docs/developers/profile_developers_guide.md new file mode 100644 index 0000000..666620e --- /dev/null +++ b/docs/developers/profile_developers_guide.md @@ -0,0 +1,408 @@ +--- +parent: Developers +--- + +Profile developers guide +======================== +{: .no_toc} + +Technical reference for BRouter profile scripts + +1. TOC +{:toc} + +The tag-value lookup table +-------------------------- + +Within the routing data files (rd5), tag information is encoded in a binary +bitstream for the way tags and the node tags each. + +To encode and decode to/from this bitstream, 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: + +- `` if the tag is not set or the value is empty +- `unknown` if the value is not contained in the table + +Each value can have optional *aliases*, these alias values are encoded into the +same binary value as the associated primary value. + +A profile must use the primary value in expressions, as aliases trigger a parse +error. E.g. if there is a line in `lookups.dat` file: + +`bicycle;0001245560 yes allowed` + +then a profile must use `bicycle=yes`, as `bicycle=allowed` gives an error. + +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. + +An exception from context separation is the node-context, where variables from +the way-context of the originating way can be accessed using the `way:` prefix. +For the variable nodeaccessgranted there's an additional legacy-hack to access +it as a lookup value without prefix: + +`if nodeaccessgranted=yes then ...` + +while in the general case the prefixed expressions are variables: + +`if greater way:costfactor 5 then ...` + +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: + + - 7 elevation configuration parameters: + + - `downhillcost` + - `downhillcutoff` + - `uphillcost` + - `uphillcutoff` + - `elevationpenaltybuffer` + - `elevationmaxbuffer` + - `elevationbufferreduce` + + - 3 boolean mode-hint flags + + - `validForBikes` + - `validForFoot` + - `validForCars` + + - 2 variables to change the heuristic coefficients for the 2 routing passes ( + <0 disables a routing pass ) + + - `pass1coefficient` + - `pass2coefficient` + + - 3 variables to influence the generation of turn-instructions + + - `turnInstructionMode` 0=none, 1=auto-choose, 2=locus-style, + 3=osmand-style + - `turnInstructionCatchingRange` default=40m + - `turnInstructionRoundabouts` default=true generate explicit roundabout + hints + + - variables to modify BRouter behaviour + + - `processUnusedTags` default=false + + If an OSM tag is unused within the profile, BRouter totally ignores the + tag existence. Skipping unused tags improves BRouter speed. As a side + effect, the tag is not even listed in the route segment table nor the + table exported as CSV. Setting it to true/1, Brouter-web Data page will + list all tags present in the RD5 file. + +- for the way section these are + + - `turncost` + - `initialcost` + - `costfactor` + - `uphillcostfactor` + - `downhillcostfactor` + - `nodeaccessgranted` + - `initialclassifier` + - `priorityclassifier` + +- for the node section this is just + + - `initialcost` + +Operators of the profile scripts +-------------------------------- + +The profile scripts use polish notation (operator first). + +The `assign` operator is special: it can be used only on the top level of the +expression hierarchy and has 2 operands: + +`assign ` + +It just assigns the expression value to this variable (which can be a predefined +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 unlimited 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: + +- `` +- `` +- `` +- `<1-op-operator> ` +- `<2-op-operator> ` +- `<3-op-operator> ` + +- A numeric value is just a number, floating point, with `.` as decimal + separator. Boolean values are treated as numbers as well, with `0` = `false` + and every nonzero value = `true`. + +- A lookup match has the form `=`, e.g. `highway=primary` Only + the primary values can be used in lookup-matches, not aliases. The `` + value is referred to as an empty string, e.g. `access=` + +- 1 Operand operators are: + + - `not ` + +- 2 Operand operators are: + + - `or ` + - `and ` + - `xor ` + - `multiply ` + - `add ` + - `sub ` + - `max ` + - `min ` + - `equal ` + - `greater ` + - `lesser ` + +- 3 Operand operators are: + + - `switch ` + + So the switch expression has a numeric value which is the true-expression if + the boolean expression is true, the false-expression otherwise. + +Syntactic Sugar +--------------- + +To improve the readablity of the profile scripts, some syntactic variations are +possible: + +- if then else: `if` can be used instead of the `switch` operator, if the + additional keywords `then` and `else` are placed between the operators: + + `if then else ` + +- Parentheses: each expression can be surrounded by parentheses: + `()` + + Please note that the profile syntax, due to the polish notation, does not need + parentheses, they are always optional. However, if there are parentheses, the + parser checks if they really match the expression boundaries. + +- or-ing lookup-matches: the pipe-symbol can be used as a short syntax for + lookup matches where more than one value is accepted for a key: + `highway=primary|secondary|tertiary` + +- additional `=` symbol for `assign` operations: + + `assign = ` + +- boolean constants: `true` and `false` can be used instead of 1 and 0 + +Please note that the tokenizer always expects blank space to separate symbols +and expressions so it is not allowed to place parentheses or the `=` symbol +without separating blank space! + +The initial cost classifier +--------------------------- + +To trigger the addition of the `initialcost`, another variable is used: +`initialclassifier` - any change in the value of that variable leads to adding +the value of `initialcost`. + +Initial cost is used typically for a ferry, where you want to apply a penalty +independent of the length of the ferry line. + +Another useful case may be an initial cost for bicycle mounting/dismounting, +having set an initialclassifier for ways without bicycle access, with high +initialcost. For backward compatibility, if `initialclassifier` = 0, it is +replaced by the costfactor. + +The priority classifier +----------------------- + +`priorityclassifier` is a BRouter numerical parameter calculated for ways and +used for generation of pictogram/voice navigation instructions. + +Higher values means the more significant (noticeable) way, as far as it can be +predicted from OSM data. + +To avoid a navigation instruction flood, it was decided that the instructions +are provided only if: + +1. You are supposed to turn at a crossroad/junction and some other ways having + the same or higher `priorityclassifier` value. + +2. You are supposed to go straight ahead and some other ways having the higher + `priorityclassifier` value. + +The elevation buffer ( From Poutnik's glossary ) +------------------------------------------------ + +With related 3 internal BRouter variables: + +- `elevationpenaltybuffer` +- `elevationmaxbuffer` +- `elevationbufferreduce` + +the Elevation Buffer is BRouter feature to filter elevation noise along the +route. It may be real, or caused by the artefacts of used SRTM elevation data. + +From every elevation change is at the first place cut out amount +`10*up/downhillcutoff` per every km of the way length. What remains, starts to +accumulate in the buffer. IF cutoff demand of elevation per length is not +saturated from incoming elevation, it is applied on elevation remaining in the +buffer as well. + +E.g. if the way climbs 20 m along 500 m, and `uphillcutoff=3.0`, then +`10*3.0*0.5 km = 15 m` is taken away and only remaining 5 m accumulates. But if +it climbed only 10 m on those 500 m, all 10 m would be *swallowed* by cutoff, +together with up to 5 m from the buffer, if there were any. + +When elevation does not fit the buffer of size `elevationmaxbuffer`, it is +converted by up/downhillcost ratio to Elevationcost portion of Equivalentlength. +Up/downhillcostfactors are used, if defined, otherwise costfactor is used. + +- `elevationpenaltybuffer` - default 5(m). + + The variable value is used for 2 purposes + + - with `buffer content > elevationpenaltybuffer`, it starts partially convert + the buffered elevation to ElevationCost by Up/downhillcost + + - with `elevation taken = MIN (buffer content - elevationpenaltybuffer, WayLength[km] * elevationbufferreduce*10` + Up/downhillcost factor takes place instead of costfactor at the percentage + of how much is `WayLength[km] * elevationbufferreduce*10` is saturated by + the buffer content above elevationpenaltybuffer. + +- `elevationmaxbuffer` - default 10(m) + + is the size of the buffer, above which all elevation is converted to + Elevationcost by Up/Downhillcost ratio, and - if defined - + Up/downhillcostfactor fully replaces costfactor in way cost calculation. + +- `elevationbufferreduce` - default 0(slope%) + + is rate of conversion of the buffer content above elevationpenaltybuffer to + ElevationCost. For a way of length L, the amount of converted elevation is + L[km] * elevationbufferreduce[%] * 10. The elevation to Elevationcost + conversion ratio is given by Up/downhillcost. + +Example: Let's examine steady slopes with `elevationmaxbuffer=10`, +`elevationpenaltybuffer=5`, `elevationbufferreduce=0.5`, `cutoffs=1.5`, +`up/downhillcosts=60`. + +All slopes within 0 .. 1.5% are swallowed by the cutoff. + +- For slope 1.75%, there will remain 0.25%. + + That saturates the elevationbufferreduce 0.5% by 50%. That gives Way cost to + be calculated 50% from costfactor and 50% from Up/downhillcostfactor. + Additionally, 0.25% gives 2.5m per 1km, converted to 2.5*60 = 150m of + Elevationcost. + +- For slope 2.0%, there will remain 0.5%. + + That saturates the elevationbufferreduce 0.5% by 100%. That gives Way cost to + be calculated fully from `up/downhillcostfactor`. Additionally, 0.5% gives 5m + per 1km, converted to 5*60 = 300m of Elevationcost. Up to slope 2.0% the + buffer value stays at 5m = `elevationpenaltybuffer`. + +- For slope 2.5%, there will remain 1.0% after cutoff subtract, and 0.5% after + the buffer reduce subtract. + + The remaining 0.5% accumulates in the buffer by rate 5 m/km. When the buffer + is full (elevationmaxbuffer), the elevation transforms to elevationcost by + full rate of 1.0%, i.e. 10 m/km, giving elevationcost 10*60=600 m/km. + + +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. Technically, values >= 10000 for a (way-)costfactor, and >= + 1000000 for a nodes `initalcost` are treated as infinity, so please use these + as the *forbidden* values. + +- Ways with costfactor >= 10000 are considered as if they did not exist at all. + +- Ways with costfactor = 9999 are considered as if they did not exist during + route calculation, but the navigation hint generator takes them into account. + + +Developing and debugging scripts +-------------------------------- + +For developing scripts, the *brouter-web* web-application is your friend. You +can use that either online at https://brouter.de/brouter-web or set up a local +installation. + +*brouter-web* has a window at the lower left corner with a *Profile* and a +*Data* tab. Here, you can upload profile scripts and see the individual cost +calculations per way-section in the *Data*-tab. + +For profile debugging activate `assign processUnusedTags = true` to see all +present OSM tags on the Data tab, not just those used in the tested profile. + + +Lookup-Table evolution and the the *major* and *minor* versions +--------------------------------------------------------------- + +The lookup-table is allowed to grow over time, to include more tags and values +as needed. To support that evolution, it carries a major and a minor version +number. These numbers are also encoded into the routing data files, taken from +the lookups.dat that is used to pre-process the routing data files. + +A major version change is considered to always break compatibility between the +routing datafiles and the lookup table. + +A minor version change keeps the routing data files and the lookup-table +compatible in both directions, using the following rules: + +- if the data contains a key that is not contained in the lookup tables, it is + ignored + +- if the data contains a value that is not contained in the lookup tables (but + its key is known) that value is treated as `unknown` + +- if a profile uses a key that is not present in the data, it sees empty + (=unset) values for that key + +- if a profile uses a value that is not present in the data, lookup matches for + that value are always false. + +For a minor version change it is required that tags are only appended at the end +of the table (or replace one of the dummy tags located between the way-tags and +the relation pseudo-tags), and that values are only appended at the end of the +value lists. This is because the routing data files address tags and values by +their sequence numbers, so changing sequences would produce garbage data. + +Other resources +--------------- + +See [Poutnik's glossary](https://github.com/poutnikl/Brouter-profiles/wiki/Glossary) +as a complementary source about various profile internals. diff --git a/docs/features/alternatives.md b/docs/features/alternatives.md new file mode 100644 index 0000000..57f96e1 --- /dev/null +++ b/docs/features/alternatives.md @@ -0,0 +1,24 @@ +--- +parent: Features +--- + +# Alternative route calculations + +Sometimes the routing result is not what you want, and you are looking for some +other way, following the same routing preferences, but not following the way of +the first choice routing result. + +Maybe you don't like the first choice, or you are planning a roundtrip and don't +want to go back the same way. For this purpose, BRouter can calculate +alternatives. + +This feature is well known from handheld-navigation systems, but not found in +online services. This is because these online services need to use +pre-calculations for fast processing and cannot handle individual routing +criteria. BRouter does not do any precalculations for specific routing profiles, +so it can do whatever you ask for. + +When using a second choice route, you may want to recalculate the route using +[via or nogo points](vianogo.md) in order to define the overall routing +according to your preferences but have a route that is first choice except for +these explicit constraints. diff --git a/docs/features/costfunctions.md b/docs/features/costfunctions.md new file mode 100644 index 0000000..c367437 --- /dev/null +++ b/docs/features/costfunctions.md @@ -0,0 +1,31 @@ +--- +parent: Features +--- + +# Freely configurable routing profile + +A major reason for the limited usefulness of most bike routing software is that +routing preferences are a personal issue. Not even will MTB and racing cyclist +never agree on common routing preferences, also the same people will have +different preferences for day and night, dry and wet weather, etc. The only +solution for that problem is the use of a freely configurable cost function that +can easily be adapted to personal needs. This is far more flexible compared to a +set of static functions with a fixed set of configuration variables. + +To make that point somewhat clearer: there are other routers that are highly +configurable, look at [routino](http://www.routino.org/uk/router.html) for an +example. However, these are one-dimensional parameter sets that do not allow to +handle arbitrary correlation. BRouter's configuration is different. It is more a +scripting language that allows you to program the cost function instead of just +configuring it. E.g. a non-graded track is generally not a good track. But if it +has a surface=asphalt tag, it probably is. On the other hand, a grade5-track +with surface=asphalt is primarily a grade5-track and you should not ignore that. +Such logic is not implementable in one-dimensional parameter sets. + +See some [sample profiles](https://brouter.de/brouter/profiles2/) provided for the online router. + +See the trekking-profile [`trekking.brf`](https://brouter.de/brouter/profiles2/trekking.brf) as the +reference-profile with some explanations on the meaning of this script. + +See the [Profile Developers Guide](../developers/profile_developers_guide.md) +for a technical reference. diff --git a/docs/features/cycleroutes.md b/docs/features/cycleroutes.md new file mode 100644 index 0000000..8ea930a --- /dev/null +++ b/docs/features/cycleroutes.md @@ -0,0 +1,19 @@ +--- +parent: Features +--- + +# Following long distance cycle routes + +The long distance cycle network (see +[www.opencyclemap.org](http://www.opencyclemap.org)) is the first thing to +consider when planning a cycle trip. BRouter can do that, and the `trekking` +profile makes use of it. It does that implicitly by just making them cheap in +the cost-function, so that the routing sometimes *snaps in* to long distance +cycle routes. + +That's a good choice for long distance cycling, because these routes are a *safe +harbor* almost free of bad surprises. However, when really looking for the +*optimal* route between A and B to use it more than once (e.g. your daily +commute) you may want to ignore the long-distance network, to put more focus on +*hard-facts* like distance, hills and surface quality (use the +`trekking-ignore-cr` profile for that purpose). diff --git a/docs/features/elevation.md b/docs/features/elevation.md new file mode 100644 index 0000000..4d401a7 --- /dev/null +++ b/docs/features/elevation.md @@ -0,0 +1,28 @@ +--- +parent: Features +--- + +# Elevation awareness + +Elevation awareness is the most important issue in bike routing if not routing +in a flat country. But in most routing software, elevation is either not handled +at all or in a way that is not really useful. + +Even worse, most tools do not even report on elevation in a useful manner. The +far-too-high *total climbs* usually reported do not only accumulate real, small +height-variations that are averaged-out by the bikers momentum - they accumulate +also noise and grid-interpolation errors from the elevation data source. + +For most regions, BRouter uses elevation data from the [Shuttle Radar Topography +Mission (SRTM)](http://srtm.usgs.gov/), precisely the hole-filled Version 4.1 +Data provided by [srtm.csi.cgiar.org](http://srtm.csi.cgiar.org/), which is the +data that is displayed e.g. in Google Earth and which is used in most +elevation-enabled routing tools. However, the routing algorithm is able to +extract the information on real ascends and descends and ignores the noise. + +For latitudes above 60 degree in northern Europe, BRouter uses Lidar data, that +were [compiled and resampled by Sonny](https://data.opendataportal.at/dataset/dtm-europe) + +On the reporting side, BRouter uses a similar concept to compute the *filtered +ascend*, which is the ascend without the noise and the small hills and which +turned out to be a valid concept to estimate the real elevation penalty. diff --git a/docs/features/index.md b/docs/features/index.md new file mode 100644 index 0000000..4abc2b2 --- /dev/null +++ b/docs/features/index.md @@ -0,0 +1,5 @@ +--- +title: Features +has_children: true +nav_order: 2 +--- diff --git a/docs/features/offline.md b/docs/features/offline.md new file mode 100644 index 0000000..af3edbb --- /dev/null +++ b/docs/features/offline.md @@ -0,0 +1,29 @@ +--- +parent: Features +--- + +# Ofline routing on Android phones + +BRouter is first and foremost an offline tool. It runs on any Android phone. The +online version offered here is just for a trial and for convenience. While many +smartphone routing software use online services to do the actual route +calculations, the advantages of the offline approach are evident: + +- It is more reliable, data connection problems and server-side problems are no + issue + +- It works in foreign countries where data connections are either not available + or very expensive + +- It does not raise any data privacy issues + +- You can use a cheap dedicated, second phone for navigation, without having to + put your business smartphone on an untrusted bike mount and run it's battery + low + +The downside is that advanced route calculations are difficult to do on a +smartphone with limited computing and memory resources, which may lead +developers to implement simplifications into the routing algorithm that affect +the quality of the routing results. BRouter always does it's best on the +quality, but has a processing time that scales quadratic with distance, leading +to a limit at about 150km in air-distance, which is enough for a bikers daytrip. diff --git a/docs/features/vianogo.md b/docs/features/vianogo.md new file mode 100644 index 0000000..c839e9f --- /dev/null +++ b/docs/features/vianogo.md @@ -0,0 +1,16 @@ +--- +parent: Features +--- + +# Via-Points and NoGo-Areas + +BRouter can process via-points and nogo-areas, and [brouter-web](/brouter-web) +offers on online interface to edit both of them. + +Nogo areas are useful if you encouter an obstacle that is not contained in the +underlying map. But they can also be useful in planning alternative routes by +excluding e.g. a certain bridge or ferry. + +For offline use, nogo-areas can be defined as wayoints using a special naming +convention. Handling of via-points during offline use depends on the mode of +operation, see the README for details. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..90a79b2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,70 @@ +--- +layout: default +title: Home +nav_order: 1 +--- + +# BRouter: Let's get serious about bike routing + +There's a lot of routing software on the market, both free and commercial, both +online and offline, both OSM and proprietary maps. However, when it comes to +bike routing, it's hard to find something that's really useful. There's far less +money and engineering power in the field compared to car navigation. + +What do we expect from a bike routing software? It should be able to calculate +more or less the routes that match your experience in the regions you are +familiar with, thus giving you confidence that it yields the same quality in +unknown regions. Scanning the market with that expectation gives little to no +result. + +Here's what makes BRouter unique: + +- It uses [freely configurable routing profiles](features/costfunctions.md) +- It works [fully offline on any Android phone](features/offline.md) and is + interfaced to some of the most popular Android map tools +- It uses a sophisticated [routing-algorithm](developers/algorithm.md) with + [elevation consideration](features/elevation.md) +- It offers [alternative route calculations](features/alternatives.md) +- It supports [via and nogo-points](features/vianogo.md) +- It can [consider long distance cycle routes](features/cycleroutes.md) + +Routing data is available worldwide with automatic weekly updates + +### BRouter uses OpenStreetMap + +BRouter uses user-generated, collaboratively collected free geodata. Thanks to +OpenStreetMap.org and contributors - please donate your geographic data to +openstreetmap.org! See the [License +description](http://www.openstreetmap.org/copyright) for details. + +### Online versions + +Check [brouter-web](/brouter-web) or [bikerouter.de](https://www.bikerouter.de/) +if you want to use BRouter online. + +### Android app for offline routing + +See [Android quickstart guide](users/android_quickstart.md) for how to setup BRouter for +offline routing on an Android smartphone. + +### Revision history + +See the [revision history](revisions.md) for older revisions of the app and the +change-log. + +### Google group for support questions and feedback + +Please use the +[osm-android-bikerouting](http://groups.google.com/group/osm-android-bikerouting) +google group for any questions/feedback. + +### Other bike routing resources: + +* [OpenStreetMap wiki router comparison + matrix](http://wiki.openstreetmap.org/wiki/Routing/online_routers) +* [OpenRouteService.org](http://www.openrouteservice.org) +* [Naviki.org](http://www.naviki.org) +* [yournavigation.org](http://www.yournavigation.org) +* [maps.cloudmade.com](http://maps.cloudmade.com) +* [graphhopper.com](http://graphhopper.com) +* [cycle.travel](http://cycle.travel/map) diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 0000000..313f8a9 --- /dev/null +++ b/docs/resources.md @@ -0,0 +1,22 @@ +# Resources +## International resources + +- Please use the [osm-android-bikerouting](http://groups.google.com/group/osm-android-bikerouting) + google group for any questions/feedback. +- Video: [Energy efficient routing with OSM](https://youtu.be/VMDRr6YPOw0) at + 2018 State-of-the-Map in Milano + +## German resources + +Artikel zu BRouter: + +- im [com-magazin](http://www.com-magazin.de/praxis/android/offline-routing-rad-wandertouren-465807.html) +- bei [gpsradler.de](https://gpsradler.de/praxistest/brouter-web-tourenplaner-test/) +- bei [navigation-professionell.de](https://www.navigation-professionell.de/brouter-web-tourenplanung/) + +Vorträge zu BRouter auf der FOSSGIS Konferenz bei YouTube: + +- 2014: [Höhenbewusstes Routing mit Radardaten](https://www.youtube.com/watch?v=c0TehKCX4Ao) +- 2015: [Neues zu BRouter](https://www.youtube.com/watch?v=Eba4fcYI4h4) [(lokales mp4)](https://brouter.de/brouter_bin/fossgis_2015_neues_zu_brouter.mp4) +- 2018: [Energieeffizientes PKW Routing mit OpenStreetMap](https://youtu.be/IHV2sL7n0Qo) +- 2020: [Routenplanung mit BRouter und BRouter-Web](https://www.youtube.com/watch?v=l6X2Sm1YDLs) [(lokales mp4)](https://brouter.de/brouter_bin/fossgis_2015_neues_zu_brouter.mp4) diff --git a/docs/revisions.md b/docs/revisions.md new file mode 100644 index 0000000..460cb21 --- /dev/null +++ b/docs/revisions.md @@ -0,0 +1,342 @@ +# Revision history + +(ZIP-Archives including APK, readme + profiles) + +### [brouter-1.6.3.zip](../brouter_bin/brouter-1.6.3.zip) (current revision, 21.12.2021) + +- Enable Android 11 +- Move storage to /Android/media/btools.routingapp +- Coord reader in app specific folder (favourites.gpx and nogo*.gpx) +- new Logo +- increased download speed limit from 4 to 16 MBit/s + +### [brouter_1_6_1.zip](../brouter_bin/brouter_1_6_1.zip) (01.03.2020) + +- download manager: direct jump-in zoom to workaround a problem with + S10+Android10 + +### [brouter_1_6_0.zip](../brouter_bin/brouter_1_6_0.zip) (16.02.2020) + +- fixed Voice-Hint timing bug (locus+osmand) +- BRouter-Web related enhancements +- fixed excessive roundabout times in kinematic model +- lookup+profile extensions +- documentation updates +- pre-processor: Douglas-Peucker transfer-node elimination +- pre-processor: speedup (->daily updates) +- pre-processor: conversion of (lidar-) hgt to bef (->Northern Europe + coverage) +- route server: thread-limit logic update (guarantee 2000ms victim runtime) +- route server: extended parsed profile cache +- route server: more appropriate HTTP status codes +- download manager: rd5 delta updates +- download manager: rd5 delete function +- suspect-manager: multiple challenges + +### [brouter_1_5_5.zip](../brouter_bin/brouter_1_5_5.zip) (22.07.2019) + +- bugfix in lazy crc check +- waypount echo (brouter-web) + +### [brouter_1_5_4.zip](../brouter_bin/brouter_1_5_4.zip) (20.07.2019, hot-fix 16:40 UTC+2) + +- fixed OsmAnd Turn Instruction issue (+hot-fix) +- internal compression in service interface +- repeat timeout -> repeat any service interface routing in brouter-app +- forcing new basedir selection on 1.4.x - 1.5.x update +- more careful memory allocation + +### [brouter_1_5_3.zip](../brouter_bin/brouter_1_5_3.zip) (06.07.2019) + +- fixed car-profiles for correct OsmAnd Turn Instructions +- increased Download Manager Speed Limit 2 Mbit/s -> 4 MBit/s +- adapted download size estimates + +### [brouter_1_5_2.zip](../brouter_bin/brouter_1_5_2.zip) (04.07.2019) + +- Android-Api-28 compatibility (with some loss of function) +- easy install on external SD (but RD5s will be deleted on uninstall) +- both Api-28 and Api-10 APKs in release-zip + +### [brouter_1_5_1.zip](../brouter_bin/brouter_1_5_1.zip) (30.06.2019) + +- Android Target API back to 10 for now (too much problems on Android >= 6) + +### [brouter_1_5_0.zip](../brouter_bin/brouter_1_5_0.zip) (30.06.2019) + +- MIT License +- Android Target API 28 (to conform to Play Store Policy) +- new internal memory management (direct-weaving+escape analysis): lower + memory footprint and defined memory bounds = more reliable operation for + long distances and as embedded library +- performance improvements +- Bicycle+Foot ETA (estimated time of arrival) +- ETA data in GPX for Locus + OsmAnd +- more precice distance calculation +- weighted nogos +- BRouter-Web related additions +- maxspeed:forrward/backward +- no_entry/no_exit TRs + +### [brouter_1_4_11.zip](../brouter_bin/brouter_1_4_11.zip) (02.04.2018, hot-fix 12.4.2018) + +- automatically ignore network islands +- car-fast/eco: breaking speeds from cost model + cost tuning +- **hot-fix 12.4.2018**: fixed bug for only-TRs at start or end + segment + +### [brouter_1_4_10.zip](../brouter_bin/brouter_1_4_10.zip) (07.03.2018) + +- fixed motorcar TR exceptions +- added vr-forum profiles to distribution +- added suspect manager to RouteServer +- polygon nogo pull request (QMapShack) +- nogo encoding pull request (QMapShack) + +### [brouter_1_4_9.zip](../brouter_bin/brouter_1_4_9.zip) (24.09.2017) + +- tweaked distance calculation +- new car profiles, kinematic model based +- basic travel-time/energy support +- modular cost models +- lookup extensions (+conrcete:lanes/plate code-side-hack) +- fix for interface provided nogos +- access to way-context vars from node-context +- fixed same segment search problem +- removed size limit for encoded tags +- (**hot fix, 5pm**: fixed regression bug for TR-bike-exceptions) + +### [brouter_1_4_8.zip](../brouter_bin/brouter_1_4_8.zip) (10.12.2016, hot-fix 7.1.2017) + +- added turn restrictions (default for car, use considerTurnRestrictions=true + for bike) +- fixed elevation interpolation in start/end segments +- fixed error message for very old data files +- removed sanity checks when just reading nogos from waypoint-database +- handling url encoded parameters +- locus codes 13/14 for u-turns left/right +- workaround for app-startup-crash when not able to determine free disk-space + (hot-fix 7.1.2017) + +### [brouter_1_4_7.zip](../brouter_bin/brouter_1_4_7.zip) (19.10.2016) + +- added turncost as start-direction bias (locus only) +- fixed a nullpointer bug in voice-hint-processing +- fixed brouter-web/standalone upload path bug +- added oneway:bicycle=true to oneway logic + +### [brouter_1_4_6.zip](../brouter_bin/brouter_1_4_6.zip) (30.9.2016) + +- improved memory footprint +- tweaked recalculation timeout logic + +### [brouter_1_4_5.zip](../brouter_bin/brouter_1_4_5.zip) (10.9.2016) + +- some more performance improvements +- filtering out unused way tags to increase profile cache efficiency +- cache sizing depending on android memory class +- fixed *ups* bug at very long distances +- fixed a bug when using repeat-timeout shortcut without a cordinate source + +### [brouter_1_4_4.zip](../brouter_bin/brouter_1_4_4.zip) (29.08.2016) + +- performance improvements +- *repeat timeout* shortcut to continue a timed-out service request +- relaxed compatibility rule for lookup-data minor version +- added mtb:scale:uphill + +### [brouter_1_4_3.zip](../brouter_bin/brouter_1_4_3.zip) (06.08.2016) + +- Option for sending profiles via service interface +- more aggresive profile replacement at version upgrade +- fixed a serious rounding bug when reading locus/orux waypoints + +### [brouter_1_4_2.zip](../brouter_bin/brouter_1_4_2.zip) (16.05.2016) + +- turn instructions, elevation on locus waypoints +- turn-instructions, shift to less ambigious angles +- turn-instructions, locus transport mode cleanup + +### [brouter_1_4_1.zip](../brouter_bin/brouter_1_4_1.zip) (09.05.2016 + +- turn instructions, fixed locus roundabaouts +- added xor, lesser, sub operators for profiles + +### [brouter_1_4.zip](../brouter_bin/brouter_1_4.zip) (06.05.2016) + +- turn instructions, first version (locus+osmand) +- extended scan for searching maptool-waypoint database +- blank->underscore replacement in tag-values +- ignoring direct duplicates in waypoint selection + +### [brouter_1_3_2.zip](../brouter_bin/brouter_1_3_2.zip) (01.11.2015) + +- allow big waypoint databases (locus+orux) +- storageconfig-migration for 1.2->1.3.2 update +- dirty reference tracks for better 2nd try performance +- static profile cache re-use +- fix for osmand 2.x directory structure on 4.4+ ext-sd +- fixed some error-handling issues + +### [brouter_1_3_1.zip](../brouter_bin/brouter_1_3_1.zip) (18.10.2015) + +- target island detection +- fixed 2-node loop problem +- minor profile modifications +- changed animation to show track during final pass + +### [brouter_1_3.zip](../brouter_bin/brouter_1_3.zip) (16.10.2015) + +- statistical encoding for data files (->much smaller) +- download manager update function +- filter for routable ways on decoder-level +- -> better memory footprint, no more OOM +- removed carsubset files (not needed anymore) +- waypoint matching on decoder level +- waypoint inside nogo disables nogo +- traffic-load pseudo-tags from traffic simulation + +### [brouter_1_2.zip](../brouter_bin/brouter_1_2.zip) (4.4.2015) + +- profile syntax extensions +- csv-fixes +- safari-patch (brouter-web) +- message list in geojson (brouter-web) +- initial cost classifier +- lookup extensions (minor version 4) +- more error handling + debug tracing + +### [brouter_1_1.zip](../brouter_bin/brouter_1_1.zip) (28.12.2014) + +- performance fixes + +### [brouter_1_0_4.zip](../brouter_bin/brouter_1_0_4.zip) (28.9.2014) + +- lookup extensions +- proposed-handling for cycle relations +- reworked csv listing + +### [brouter_1_0_3.zip](../brouter_bin/brouter_1_0_3.zip) (24.8.2014) + +- support for slope dependent cost-function + +### [brouter_1_0_2.zip](../brouter_bin/brouter_1_0_2.zip) (10.8.2014) + +- fixed NullPointerException during setup +- mime-type patch for downloading from brouter-web + +### [brouter_1_0_1.zip](../brouter_bin/brouter_1_0_1.zip) (26.7.2014) + +- new file format with extended lookup table and 25% size reduction +- special, fast handling for trivial recalculations for timeout-free + recalculations +- fixed the scaling for high-density screens in the download manager +- added more [configuration options](https://brouter.de/brouter/kitkat_survival_readme.txt) to work + around the kitkat (Android 4.4) issues + +### [brouter_0_9_9.zip](../brouter_bin/brouter_0_9_9.zip) (18.4.2014, hot-fix 11.5.2014) + +- new (google-play compatible) signing key, UNINSTALL NECCESSARY! +- added crc checksums to datafiles +- fixed a bug in accessing the last 64k of a datafile +- extended basedir-proposals (**Fixed Android 4.4 issue on 11.5.2014**) +- changed RouteServer to multithreaded/nonblocking operation (for brouter-web) +- added brouter-web start-scripts +- added oneway:bicycle=no -> cycleway=opposite conversion to pre-processor +- added more cache-reuse for better short-route performance + +### [brouter_0_9_8.zip](../brouter_bin/brouter_0_9_8.zip) (12.1.2014) + +- fixed NullPointer for missing service-mode +- fixed remaining issue for short routes with from/to on same way-section +- improved reporting on OutOfMemory +- changed *fastbike* profile to fix an issue with mandatory cycleways +- fixes a bug in elevation reporting if startpoint has VOID elevation + +### [brouter_0_9_7.zip](../brouter_bin/brouter_0_9_7.zip) (31.12.2013) + +- fixed a bug for short routes with from/to on same way-section +- improved waypoint-matching +- improved nogo-handling in service interface (inverse logic, routing mode + stores veto-list) +- added waypoint-selection dialogs when from/to not given +- summary page after service-mode confifuration update +- allowed configuration of BRouter's servicemodes without any supported + maptool installed +- added a redirection-workaround for the tracks-output directory +- removed the beta-expiry + +### [brouter_0_9_6.zip](../brouter_bin/brouter_0_9_6.zip) (27.10.2013) + +- added html-page about [routing-algorithm](developers/algorithm.md) +- changed from 3-pass to 2-pass calculation +- added profile-parameters for routing coefficients +- lowered pass1-coefficient for car-test to 1.3 +- fixed a bug in nogo-handling in service interface +- fixed a bug in command-line java version + +### [brouter_0_9_5.zip](../brouter_bin/brouter_0_9_5.zip) (20.10.2013) + +- some performance improvments +- support for car-subset datafiles +- timeout-free partial recalcs in service-mode +- added java-version (executable jar) to distribution zip +- moved service-mode-mapping files to sdcard + +### [brouter_0_9_4.zip](../brouter_bin/brouter_0_9_4.zip) (4.9.2013) + +- additional maptool search at /mnt/sdcard when using a non-standard base + directory +- fixed error handling issues +- major source code refactoring + +### [brouter_0_9_3.zip](../brouter_bin/brouter_0_9_3.zip) (30.6.2013) + +- introduced new service interface as android service +- re-designed service-mode configuration to be more flexible + +### [brouter_0_9_2.zip](../brouter_bin/brouter_0_9_2.zip) (9.6.2013) + +- fixed lifecycle issues of service interface + +### [brouter_0_9_1.zip](../brouter_bin/brouter_0_9_1.zip) (2.6.2013) + +- added an experimental service interface (see readme_service.txt) + +### [brouter_0_9.zip](../brouter_bin/brouter_0_9.zip) (26.5.2013) + +- line-matching + exact positions for waypoints +- minor profile modifications +- changed track-name from mytrack so something more useful + +### [brouter_0_8.zip](../brouter_bin/brouter_0_8.zip) (4.5.2013) + +- changed beta expiry to August 2014 +- Nogo-Points next version: line-matching + radius +- line-matching for waypoints (online version only up to now) +- moped-profile + +### [brouter_0_7.zip](../brouter_bin/brouter_0_7.zip) (7.4.2013) + +- Support for OruxMaps +- Via-Points +- Nogo-Points +- fixed parsing of profiles without trailing newline +- fixed scaling of routing animation +- (No documentation update yet!) + +### [brouter_0_6.zip](../brouter_bin/brouter_0_6.zip) (9.3.2013) + +- Extended data files (more way tags, added node tags) +- Extended profiles (global-, way-, node-context) +- more precise access + oneway rules +- more evelation parameters in profiles +- explicit configuration of base directory +- elevation=void within bridges or tunnels +- fixed gpx version header +- link counter in app animation + +### [brouter_0_5.zip](../brouter_bin/brouter_0_5.zip) (27.1.2013) + +- last revision before data format change - old data files not available + anymore diff --git a/docs/users/android_advanced.md b/docs/users/android_advanced.md new file mode 100644 index 0000000..3869b5d --- /dev/null +++ b/docs/users/android_advanced.md @@ -0,0 +1,146 @@ +--- +parent: Using BRouter +nav_order: 2 +--- + +# Android advanced configuration + +### Directory structure + +BRouter uses several subdirectories inside the base directory. + +| directory | description | +| --------------------------------- | -------------------------------------------- | +| `/brouter` | | +| `/brouter/modes` | routing-mode/profile mapping and route cache | +| `/brouter/profiles2` | lookup-table and routing-profiles (\*.brf) | +| `/brouter/segments4` | **routing data files (\*.rd5)** | +| `/brouter/import` | allow a small file exchange with other apps | +| `/brouter/import/tracks` | place the `nogo*.gpx` files here | + +`modes` contains `serviceconfig.dat` which defines _routing-mode_ / +_routing-profile_ mapping and cached route results which are used for +recalculations. + +`profiles2` contains `lookup.dat` (OSM tag access), `serverconfig.txt` and +_routing-profiles_. + +`segments4` contains `storageconfig.txt` and routing data files (\*.rd5). You +can download them using the _Download Manager_ or as described in +[Download Routing Segments](download_segments.md). + +### Configuration files + +#### serverconfig.txt + +`serverconfig.txt` is used to configure download information for routing +profiles and routing segments. + +#### serviceconfig.dat + +`serviceconfig.dat` is used to configure mapping between _routing-mode_ and +_routing-profile_. + +#### storageconfig.txt + +`storageconfig.txt` is used to specifiy additional paths which BRouter should +use. + +* `secondary_segment_dir` points to an additional directory containing routing + data files. This can be located anywhere. + + When searching for datafiles, both the download manager and the router first + look in the primary (brouter/segments4) and then in the secondary directory. + On the other hand, the download manager always writes new datafiles to the + primary directory, so the secondary directory is read-only. + + You can move datafiles downloaded by the download-manager to the secondary + directory, by using a file manager, in order to free disk space on the + internal card. + +* `additional_maptool_dir` points to a directory that should be scanned for + maptool-installations in addition to the standard-guesses. + +#### Redirect files + +When using the _file interface_ with waypoints from other app's storage BRouter +tries to write the calculated tracks to the app storage. Depending on the +Android version this won't work. BRouter can be configured to write tracks to a +different directory by creating a `brouter.redirect` file which contains a +single line with the absolute path to the folder where the tracks should be +written. + +* For LocusMap `brouter.redirect` has to be located in `Locus/mapItems` +* For OruxMaps `brouter.redirect` has to be located in `oruxmaps/tracklogs` +* For OsmAnd `brouter.redirect` has to be located in `osmand/tracks` + +## Using nogo-areas + +There's a special naming-convention to specify nogo-areas: + +`nogo[radius] [name]` defines 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 names for nogo-waypoints. + +The effect is that BRouter searches a route that avoids the area defined by the +position and the radius of the nogo-area. + +Nogo-areas are used when routing via _service interface_ and _file interface_. + +When using the _file interface_ you will get a nogo-dialog allowing to de-select +them if nogo-waypoints are found in the waypoint-database. This de-selection can +also be bound to a service mode using the _Server Mode_ button to make it +effective using the _service interface_ as well, but initially, every nogo-area +is effective in the _service interface_. + +Nogo-areas can be used either to account for real obstacles or to enforce +personal routing preferences. + +## Routing via _file interface_ + +The other option is using the BRouter app to calculate a route. This is the +prefered option when calculating long-distance-routes that would not finish +within the 60 seconds timout if calculated via the _service interface_. + +To do this, start the BRouter app, select two or more waypoints and then start +the route calculation. BRouter either reads waypoints from the `import` folder +or tries to read waypoints from other map tools if it has the required +permission. These waypoints are called _Favorites_ in OsmAnd, _POIs_ in Locus or +_Waypoints_ in Oruxmaps and allow to associate a location with a name. + +If your waypoint database contains a `from` and `to` waypoint the waypoint +selection will be skipped. BRouter also uses `via1`, ..., `via9` as via +waypoints. + +If a route is calculated, it is stored as `brouter0.gpx`. Depending on the +waypoint database and permissions BRouter stores the route in +`/import/tracks` or in the map tool track directory. If started once +more with identical input, BRouter will store a second route broute1.gpx for the +first alternative and so on. + +### Permission issues + +If using the file interface BRouter needs to access the files from other apps. +Depending on your android version, your BRouter version and location of other +apps locations it will be impossible to read or write those files. + +## Mixed operation: _timeout-free recalculations_ + +You can combine both operation modes (_service interface_ + _file interface_ to +become able to calculate very long distances, but make use of the advantages of +the service interface as well, especially the dynamic recalculations if you get +off the track, without running into the 60 seconds timeout. + +To support this, BRouter can do _timeout free recalculations_. It works by +initially calculating a track to your destination and binding it to one or more +routing-modes using the _Server Mode_ button. This way, BRouter stores a +_reference track_ in the `brouter/modes` subdirectory. + +If afterwards a route to the exact same destination is calculated via the +service interface, BRouter uses a special calculation mode that makes use of the +reference track for faster processing that is guaranteed to give a result within +60 seconds. _Exact same_ destination means withing 5m, so best use the same +waypoint for re-calculating that you used for the initial calculation. + +This way you can follow a long distance route via the _service interface_, +enjoying automatic recalculations if you get off the track. diff --git a/docs/users/android_quickstart.md b/docs/users/android_quickstart.md new file mode 100644 index 0000000..9157fae --- /dev/null +++ b/docs/users/android_quickstart.md @@ -0,0 +1,92 @@ +--- +parent: Using BRouter +nav_order: 1 +--- + +# Android quickstart guide + +### Choosing and installing a map tool + +BRouter just calculates tracks as GPX or GeoJSON files. It does not display maps +or give any navigation instuctions. Therefore you need a map-tool in order for +BRouter to be useful. + +Several map tools support routing with BRouter: + +- [_OsmAnd_](http://www.osmand.net): GPLv3, Free (limited features) and paid version available +- [_Locus Map_](http://www.locusmap.eu): Proprietary, Free (ads) and paid version available +- [_Oruxmaps_](http://www.oruxmaps.com): Proprietary, Free (previous version) and paid version available + +Install any of those map tools using your favorite app store. + +### Installing BRouter + +You can install BRouter either from +[F-Droid](https://f-droid.org/packages/btools.routingapp), [Google Play +Store](https://play.google.com/store/apps/details?id=btools.routingapp) or from +the APK contained in the releases available in the [Revision +History](https://brouter.de/brouter/revisions.html). + +### Choosing a base directory + +When first starting BRouter (or after deleting/moving the base directory), it +asks for a directory and gives you proposals plus the option to enter any other +base directory. + +Most phones have an internal and an external storage, where the external storage +is a SD card which can be removed from the device. + +Navigation needs big data files that usually should go on an external storage +because it provides larger capacity. You should accept the external storage, +which is usually the one with the most space available. + +Since Android 11 apps can only write to their app-specific storage so BRouter +can only use `<...>/Android/media/btools.routingapp/` as base directory. The +app-specific storage can be located on internal or external storage. + +On Android versions prior to 11 it is possible to read and write to other +locations which is used for the _file interface_. For the _service interface_ +access to other apps app-specific storage isn't required. + +### Download routing segments + +BRouter requires routing data which is independent of the displayed map of a map +tool. Routing segments (`rd5`) can be downloaded using the BRouter _Download +Manager_. + +## Routing via _service interface_ + +BRouter is best used via it's _service interface_. It provides a service which +can be used by map tools without starting the BRouter app. + +To use BRouter in your map tool you have to configure the map tool to use +BRouter as navigation service. + +- [Instructions for LocusMap](https://docs.locusmap.eu/doku.php?id=manual:faq:how_to_navigate_offline) +- [Instructions for OsmAnd](osmand.md) + + Note: OsmAnd only displays BRouter as navigation service if BRouter is + installed. You have to install BRouter before configuring OsmAnd. + +The _service interface_ allows specifing either a _routing-mode_ (used by OsmAnd +and OruxMaps) or a _routing-profile_ (used by LocusMap). When using a +_routing-mode_ BRouter selects the _routing-profile_ according to a mapping. + +By default BRouter uses the following mapping: + +| routing-mode | routing-profile | +| -------------- | --------------- | +| motorcar_fast | car-test | +| motorcar_short | moped | +| bicycle_fast | fastbike | +| bicycle_short | trekking | +| foot_fast | shortest | +| foot_short | shortest | + +This mapping, however, can be changed any time by starting the BRouter and using +the _Server Mode_. + +If your routing request fails due to timeout you can open BRouter and select +_Server Mode_ and recalculate the route using _\_. BRouter caches +the routing result and further requests using the _same_ destination using the +_service interface_ will be successful. diff --git a/docs/users/download_segments.md b/docs/users/download_segments.md new file mode 100644 index 0000000..aba5475 --- /dev/null +++ b/docs/users/download_segments.md @@ -0,0 +1,23 @@ +--- +parent: Using BRouter +--- + +# Download Routing Segments + +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 -> you need `W50_N35.rd5` +- You want to route near East7/North47 -> you need `E5_N45.rd5` + +These data files, called _segments_ across BRouter, are generated from +[OpenStreetMap](https://www.openstreetmap.org/) data and stored in a custom +binary format (rd5) for improved efficiency of BRouter routing. + +## Download them from brouter.de + +Segments files from the whole planet are generated weekly at +[https://brouter.de/brouter/segments4/](http://brouter.de/brouter/segments4/). + +You can download one or more segments files, covering the area of the planet +your want to route, into the `segments4` directory. diff --git a/docs/users/index.md b/docs/users/index.md new file mode 100644 index 0000000..3a80abd --- /dev/null +++ b/docs/users/index.md @@ -0,0 +1,22 @@ +--- +has_children: true +nav_order: 3 +--- + +# Using BRouter + +## Online + +Check [brouter-web](https://brouter.de/brouter-web/) or +[bikerouter.de](https://bikerouter.de/) if you want to use BRouter online. + +## BRouter on Android + +BRouter provides offline route calculation on Android. To get started with +BRouter on Android see the [Quickstart](android_quickstart.md). + +## Google group for support questions and feedback + +Please use the +[osm-android-bikerouting](http://groups.google.com/group/osm-android-bikerouting) +google group for any questions/feedback. diff --git a/misc/readmes/osmand/README.md b/docs/users/osmand.md similarity index 69% rename from misc/readmes/osmand/README.md rename to docs/users/osmand.md index bf0059b..db751f7 100644 --- a/misc/readmes/osmand/README.md +++ b/docs/users/osmand.md @@ -1,9 +1,14 @@ -Using BRouter on Android with OSMAnd +--- +parent: Using BRouter +title: OsmAnd +--- + +Using BRouter on Android with OsmAnd ==================================== -BRouter integration in OSMAnd changed a lot during the summer of 2019. This +BRouter integration in OsmAnd changed a lot during the summer of 2019. This guide assumes you are using the BRouter Android app in version 1.5.0 or higher -as well as OSMAnd in version 3.4 or higher. +as well as OsmAnd in version 3.4 or higher. ## Installing BRouter app on your Android device @@ -26,9 +31,9 @@ the areas you want to route in. Then click "Start Download" and BRouter will start downloading the [segments](http://brouter.de/brouter/segments4/) files for the selected areas. -Main menu of BRouter android app +Main menu of BRouter android app -Grid selection of segments to download +Grid selection of segments to download Note that you will have to repeat this step periodically, whenever you want to have an updated version of the OSM data used for the routing. @@ -41,24 +46,24 @@ entry on the main menu. Select the routing profile you want to use and click "Server-Mode". Then, tick the boxes for the routing modes you want to use this profile for. You can use two different profiles per transportation mode, which will be mapped to the "shortest" and "fastest" presets (these are just -labelling) in OSMAnd. +labelling) in OsmAnd. -Profiles selection +Profiles selection -Profiles selection summary +Profiles selection summary -## Configure OSMAnd to make use of BRouter offline navigation +## Configure OsmAnd to make use of BRouter offline navigation -You can now create an "Application profile" in OSMAnd which will be using +You can now create an "Application profile" in OsmAnd which will be using BRouter for offline routing. Go to Settings -> Application profiles -> Add and create a new profile based on the base profile of your choice (cycling here, for bicycle routing), with a custom name of your choice ("BRouter" on the screenshot below) and making use of "BRouter (offline)" for navigation. -BRouter configuration in OSMAnd +<img src= -The BRouter app should be launched before OSMAnd for this specific entry to -appear in OSMAnd. Therefore, if you cannot find "BRouter (offline)" navigation -option, you should force quit OSMAnd and restart it. +The BRouter app should be launched before OsmAnd for this specific entry to +appear in OsmAnd. Therefore, if you cannot find "BRouter (offline)" navigation +option, you should force quit OsmAnd and restart it. diff --git a/misc/readmes/osmand/brouter-grid.png b/docs/users/osmand/brouter-grid.png similarity index 100% rename from misc/readmes/osmand/brouter-grid.png rename to docs/users/osmand/brouter-grid.png diff --git a/misc/readmes/osmand/brouter-main.png b/docs/users/osmand/brouter-main.png similarity index 100% rename from misc/readmes/osmand/brouter-main.png rename to docs/users/osmand/brouter-main.png diff --git a/misc/readmes/osmand/brouter-osmand.png b/docs/users/osmand/brouter-osmand.png similarity index 100% rename from misc/readmes/osmand/brouter-osmand.png rename to docs/users/osmand/brouter-osmand.png diff --git a/misc/readmes/osmand/brouter-profiles-summary.png b/docs/users/osmand/brouter-profiles-summary.png similarity index 100% rename from misc/readmes/osmand/brouter-profiles-summary.png rename to docs/users/osmand/brouter-profiles-summary.png diff --git a/misc/readmes/osmand/brouter-profiles.png b/docs/users/osmand/brouter-profiles.png similarity index 100% rename from misc/readmes/osmand/brouter-profiles.png rename to docs/users/osmand/brouter-profiles.png diff --git a/misc/readmes/kitkat_survival_readme.txt b/misc/readmes/kitkat_survival_readme.txt deleted file mode 100644 index d1561ba..0000000 --- a/misc/readmes/kitkat_survival_readme.txt +++ /dev/null @@ -1,66 +0,0 @@ -Surviving with Android 4.4 (KitKat) or 5.x (Lollipop) using latest BRouter -======================================================= - -BRouter has some basic support to reclaim your external SD card. - -Brouter must be installed on internal drive ("SD card"), but maps could be moved to external SD card. - -What's new is a configuration file located at: - - brouter/segments4/storageconfig.txt - -which has 2 configuration items: - - "secondary_segment_dir" points to an additional directory containing - routing data files. This can be located anywhere. - - "additional_maptool_dir" points to a base-directory that should - be scanned for maptool-installations in addition to the standard-guesses. - -Initially, the value for "secondary_segment_dir" is "../segments3" to support the -file-format transition from 1.2 to 1.3, so that, after upgrading, your existing -datafiles are found via the secondary directory. - -However, for surviving KitKatn and later, you are supposed to change that to the -absolute path to a directory on the external card, e.g.: - -secondary_segment_dir=/storage/external_SD/brouter_segments4 - -When searching for datafiles, both the download manager and the router first look in the primary (brouter/segments4) and then in the secondary directory. -On the other hand, the download manager always writes new datafiles to the primary directory, so the secondary directory is read-only. - -So you can move datafiles downloaded by the download-manager to the secondary directory, by using a file manager, in order to free disk space on the internal card. Or you ca download datafiles directly to the secondary directory by doing manual http downloads -from http://brouter.de/brouter/segments4 - -Depending on how your maptool handles the file-system structure, you are done. - -However, e.g. for OsmAnd it is likely that BRouter still has no access to OsmAnd's waypoint database. The reason is: - -When, after installing OsmAnd, you choose to move it's resources to the external SD Card, -it moves it to a special directory where it has write-access even with Android 4.4, e.g.: - - /storage/external_SD/Android/data/net.osmand/files - -The package name slightly differs for OsmAnd+. - -This directory is not found automatically by BRouter, so you have to configure -it as "additional_maptool_dir". - -However, you are still not done, because if BRouter finds a wayoint-database file -under: - - /storage/external_SD/Android/data/net.osmand/files/osmand/favourites.gpx - -then it decides to write it's tracks to: - - /storage/external_SD/Android/data/net.osmand/files/osmand/tracks - -But this directory is not writable by BRouter. So what you have to do is to create -a redirection-file (create the tracks folder if it does not exist!) - - /storage/external_SD/Android/data/net.osmand/files/osmand/tracks/brouter.redirect - -and that should contain a single line with the absolute path to the folder where -the tracks should be written (e.g. /mnt/sdcard/brouter ). Redirection file is normal file named brouter.redirect and containing single line pointing to folder writable by BRouter and readable by OsmAnd. - -THEN you are done. diff --git a/misc/readmes/profile_developers_guide.txt b/misc/readmes/profile_developers_guide.txt deleted file mode 100644 index 2cfde9e..0000000 --- a/misc/readmes/profile_developers_guide.txt +++ /dev/null @@ -1,411 +0,0 @@ -Profile developers guide - Technical reference -for BRouter profile scripts -============================================== - -The tag-value lookup table --------------------------- - -Within the routing data files (rd5), tag information -is encoded in a binary bitstream for the way tags and -the node tags each. - -To encode and decode to/from this bitstream, 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: - -- if the tag is not set or the value is empty -- "unknown" if the value is not contained in the table - -Each value can have optional "aliases", these alias -values are encoded into the same binary value as the -associated primary value. - -A profile must use the primary value in expressions, as -aliases trigger a parse error. E.g. if there is a line -in lookups.dat file: - -bicycle;0001245560 yes allowed - -then a profile must use "bicycle=yes", as "bicycle=allowed" -gives an error. - -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. - -An exception from context separation is the node-context, -where variables from the way-context of the originating -way can be accessed using the "way:" prefix. For the -variable nodeaccessgranted there's an additional -legacy-hack to access it as a lookup value without prefix: - - if nodeaccessgranted=yes then ... - -while in the general case the prefixed expressions are variables: - - if greater way:costfactor 5 then ... - -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: - - - 7 elevation configuration parameters: - - - downhillcost - - downhillcutoff - - uphillcost - - uphillcutoff - - elevationpenaltybuffer - - elevationmaxbuffer - - elevationbufferreduce - - - 3 boolean mode-hint flags - - - validForBikes - - validForFoot - - validForCars - - - 2 variables to change the heuristic - coefficients for the 2 routing passes - ( <0 disables a routing pass ) - - - pass1coefficient - - pass2coefficient - - - 3 variables to influence the generation of turn-instructions - - - turnInstructionMode 0=none, 1=auto-choose, 2=locus-style, 3=osmand-style - - turnInstructionCatchingRange default 40m - - turnInstructionRoundabouts default=true=generate explicit roundabout hints - - - variables to modify BRouter behaviour - - - processUnusedTags ( default is false ) - If an OSM tag is unused within the profile, - BRouter totally ignores the tag existence. - Skipping unused tags improves BRouter speed. - As a side effect, the tag is not even listed - in the route segment table nor the table exported as CSV. - Setting it to true/1, Brouter-web Data page will list - all tags present in the RD5 file. - -- for the way section these are - - - turncost - - initialcost - - costfactor - - uphillcostfactor - - downhillcostfactor - - nodeaccessgranted - - initialclassifier - - priorityclassifier - -- for the node section this is just - - - initialcost - - -The operators of the profile scripts ------------------------------------- - -The profile scripts use polish notation (operator first). - -The "assign" operator is special: it can be used -only on the top level of the expression hierarchy -and has 2 operands: - - assign - -It just assigns the expression value to this -variable (which can be a predefined 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 unlimited -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: - - - - - - - - - <1-op-operator> - - <2-op-operator> - - <3-op-operator> - -- A numeric value is just a number, floating point, with "." as - decimal separator. Boolean values are treated as numbers as well, - with "0" = false and every nonzero value = true. - -- A lookup match has the form =, e.g. highway=primary - Only the primary values can be used in lookup-matches, not aliases. - The value is referred to as an empty string, e.g. access= - -- 1 Operand operators are: - - not - -- 2 Operand operators are: - - or - and - xor - multiply - add - sub - max - min - equal - greater - lesser - -- 3 Operand operators are: - - switch - - So the switch expression has a numeric value which is the - true-expression if the boolean expression is true, the - false-expression otherwise. - - -Syntactic Sugar ---------------- - -To improve the readablity of the profile scripts, some syntactic variations -are possible: - -- "if then else" : "if" can be used instead of the "switch" operator, if the - additional keywords "then" and "else" are placed between the operators: - - if then else - -- Parentheses: each expression can be surrounded by parentheses: ( ) - Please note that the profile syntax, due to the polish notation, does not - need parentheses, they are always optional. However, if there are parentheses, - the parser checks if they really match the expression boundaries. - -- or-ing lookup-matches: the pipe-symbol can be used as a short syntax for - lookup matches where more than one value is accepted for a key: - highway=primary|secondary|tertiary - -- additional "=" symbol for "assign" operations: - assign = - -- boolean constants: "true" and "false" can be used instead of 1 and 0 - -Please note that the tokenizer always expects blank space to separate -symbols and expressions so it is not allowed to place parentheses or -the "=" symbol without separating blank space! - - -The initial cost classifier ---------------------------- - -To trigger the addition of the "initialcost", another variable is used: -"initialclassifier" - any change in the value of that variable leads -to adding the value of "initialcost". - -Initial cost is used typically for a ferry, where you want to apply -a penalty independent of the length of the ferry line. - -Another useful case may be an initial cost for bicycle mounting/dismounting, -having set an initialclassifier for ways without bicycle access, with high initialcost. -For backward compatibility, if "initialclassifier" = 0, it is replaced -by the costfactor. - - -The priority classifier ------------------------ - -Priorityclassifier is a BRouter numerical parameter -calculated for ways and used for generation of pictogram/voice navigation instructions. - -Higher values means the more significant (noticeable) way, -as far as it can be predicted from OSM data. - -To avoid a navigation instruction flood, it was decided -that the instructions are provided only if: - -1/ You are supposed to turn at a crossroad/junction - and some other ways having the same or higher Priorityclassifier value. -OR -2/ You are supposed to go straight ahead - and some other ways having the higher Priorityclassifier value. - - -The elevation buffer ( From Poutnik's glossary ) ------------------------------------------------- - -With related 3 internal BRouter variables: - - elevationpenaltybuffer - - elevationmaxbuffer - - elevationbufferreduce - -the Elevation Buffer is BRouter feature to filter elevation noise along the route. -It may be real, or caused by the artefacts of used SRTM elevation data. - -From every elevation change is at the first place cut out amount 10*up/downhillcutoff -per every km of the way length. What remains, starts to accumulate in the buffer. -IF cutoff demand of elevation per length is not saturated from incoming elevation, -it is applied on elevation remaining in the buffer as well. - -E.g. if the way climbs 20 m along 500 m, and uphillcutoff=3.0, then 10*3.0*0.5 = 15 m -is taken away and only remaining 5 m accumulates. But if it climbed only 10 m -on those 500m, all 10 m would be "swallowed" by cutoff, -together with up to 5 m from the buffer, if there were any. - -When elevation does not fit the buffer of size elevationmaxbuffer, -it is converted by up/downhillcost ratio to Elevationcost portion of Equivalentlength. -Up/downhillcostfactors are used, if defined, otherwise CostFactor is used. - -elevationpenaltybuffer is BRouter variable, with default value 5(m). - The variable value is used for 2 purposes: - With the buffer content > elevationpenaltybuffer, it starts partially convert - the buffered elevation to ElevationCost by Up/downhillcost, with elevation taken - = MIN (Buffer - elevationpenaltybuffer, WayLength[km] * elevationbufferreduce*10 - The Up/downhillcost factor takes place instead of costfactor at the percentage of - how much is WayLength[km] * elevationbufferreduce*10 is saturated - by the buffer content above elevationpenaltybuffer. - -elevationmaxbuffer - default 10(m) - is the size of the buffer, above which - all elevation is converted to Elevationcost by Up/Downhillcost ratio, - and - if defined - Up/downhillcostfactor fully replaces Costfactor - in way cost calculation. - -elevationbufferreduce - default 0(slope%)- is rate of conversion of the buffer content - above elevationpenaltybuffer to ElevationCost. For a way of length L, - the amount of converted elevation is L[km] * elevationbufferreduce[%] * 10. - The elevation to Elevationcost conversion ratio is given by Up/downhillcost. - -Example: - Let's examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5, - elevationbufferreduce=0.5, cutoffs=1.5, Up/downhillcosts=60. - - All slopes within 0 .. 1.5% are swallowed by the cutoff. - - For slope 1.75%, there will remain 0.25%. - That saturates the elevationbufferreduce 0.5% by 50%. That gives Way cost - to be calculated 50% from costfactor and 50% from Up/downhillcostfactor. - Additionally, 0.25% gives 2.5m per 1km, converted to 2.5*60 = 150m of Elevationcost. - - For slope 2.0%, there will remain 0.5%. - That saturates the elevationbufferreduce 0.5% by 100%. That gives Way cost - to be calculated fully from Up/downhillcostfactor. Additionally, - 0.5% gives 5m per 1km, converted to 5*60 = 300m of Elevationcost. - Up to slope 2.0% the buffer value stays at 5m = elevationpenaltybuffer. - - For slope 2.5%, there will remain 1.0% after cutoff subtract, - and 0.5% after the buffer reduce subtract. The remaining 0.5% accumulates in the buffer - by rate 5 m/km. When the buffer is full (elevationmaxbuffer), - the elevation transforms to elevationcost by full rate of 1.0%, i.e. 10 m/km, - giving elevationcost 10*60=600 m/km. - - -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. Technically, values >= 10000 for a - (way-)costfactor, and >= 1000000 for a nodes "initalcost" are treated - as infinity, so please use these as the "forbidden" values. - -- Ways with costfactor >= 10000 are considered as if they did not exist at all. - -- Ways with costfactor = 9999 are considered as - if they did not exist during route calculation, - but the navigation hint generator takes them into account. - - -Developing and debugging scripts --------------------------------- - -For developing scripts, the "brouter-web" web-application is your -friend. You can use that either online at https://brouter.de/brouter-web -or set up a local installation. - -BRouter-Web has a window at the lower left corner with a "Profile" -and a "Data" tab. Here, you can upload profile scripts and see -the individual cost calculations per way-section in the "Data"-tab. - -For profile debugging activate "assign processUnusedTags = true" -to see all present OSM tags on the Data tab, not just those used in the tested profile. - - -Lookup-Table evolution and the the "major" and "minor" versions ---------------------------------------------------------------- - -The lookup-table is allowed to grow over time, to include more tags -and values as needed. To support that evolution, it carries a major -and a minor version number. These numbers are also encoded into -the routing data files, taken from the lookups.dat that is used -to pre-process the routing data files. - -A major version change is considered to always break compatibility -between the routing datafiles and the lookup table. - -A minor version change keeps the routing data files and the lookup-table -compatible in both directions, using the following rules: - -- if the data contains a key that is not contained in the lookup - tables, it is ignored - -- if the data contains a value that is not contained in the lookup - tables (but its key is known) that value is treated as "unknown" - -- if a profile uses a key that is not present in the data, - it sees empty (=unset) values for that key - -- if a profile uses a value that is not present in the data, - lookup matches for that value are always false. - -For a minor version change it is required that tags are only -appended at the end of the table (or replace one of the dummy -tags located between the way-tags and the relation pseudo-tags), -and that values are only appended at the end of the value lists. -This is because the routing data files address tags and values -by their sequence numbers, so changing sequences would produce -garbage data. - - -Other resources ---------------- - -See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary -as a complementary source about various profile internals. - diff --git a/misc/readmes/readme.txt b/misc/readmes/readme.txt deleted file mode 100644 index 3221c78..0000000 --- a/misc/readmes/readme.txt +++ /dev/null @@ -1,262 +0,0 @@ -BRouter - Version 1.4 - 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/ - -- "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. All three have elevation profile diagrams. - -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. - -Installing the BRouter App --------------------------- - -You can install the BRouter-App either from Google's Play Store -or directly from the APK-File contained within the "brouter_1_4.zip" -distribution zip-file. - -Choosing a SD-Card Base Directory ---------------------------------- - -When first starting BRouter (or after deleting/moving -the brouter folder on the sd-card), it asks for a -sd-card base directory and gives you proposals plus -the option to enter any other base directory. - -Most 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. - -Navigation needs big data files that usually should go on an -external, big sd-card. You should accept the external card, which -is usually the one with the most space available. - -However, on Android >= 4.4, write access to the external card -is restricted, and usually you will not get a proposal to use -the external card. Here you should accept to go with the -internal card - later on you can setup a "secondary" data -directory on the external card where you can move the datafiles -to. - -*** see the kitkat_survival_readme.txt for special Android 4.4 and Android 5x issues *** - -Try to make sure your map-tool uses the same base directory -to store the offline maps and other stuff, because BRouter -tries to access the maptool's waypoint-database and tracks-directory, -and this works only if they use either the same base directory -or if the maptool uses the standard, internal base /mnt/sdcard. - -In OsmAnd, this works by choosing an "SD-Card base directory". - -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). - -If you have a non-standard maptool location, that is not -detected by the default logic, you can configure an "additional maptool directory" -in a configuration file located unter brouter/segments3/storageconfig.txt -This is neccessary e.g. if you operate OsmAnd on the external SD card -under Android 4.4. Then this uses a special base directory to obey -Android 4.4's access restrictions, and this base directory is not found -by the default logic. See the kitkat_survival_readme.txt for details. - - - -Completing your installation ----------------------------- - -After accepting a base-directory proposal, "BRouter" creates a subfolders -relative to this base directory, so you end up with e.g. the following structure: -(depending on base dir and your map-tool choice): - -/mnt/sdcard/brouter -/mnt/sdcard/brouter/segments4 <- ** put routing data files (*.rd5) here ** -/mnt/sdcard/brouter/profiles2 <- lookup-table and routing profiles -/mnt/sdcard/brouter/modes <- routing-mode/profile mapping - -/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 - - -The "profiles2" and the "modes" directory get some reasonable default-configuration -from the installation procedure, but the "segments4" directory is basically empty -(except for the storageconfig.txt file) so you have to get routing-datafiles in -order to complete your installation. - -After accepting the base directory, the download manager starts automatically to -help you with this download. Or you can download -them manually from the following location: - - http://brouter.de/brouter/segments4 - -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. The carsubset datafiles are needed only if you want to -calculate car-routes over long distances, otherwise you are fine with just the -normal (full) rd5's. - -The minimum files BRouter needs to work are e.g. - -/mnt/sdcard/brouter/segments4/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. - - -Routing via the service interface -================================= - -BRouter is best used via it's "service interface". No need to start the BRouter-App -in order to do that, it's just a services that sits in the background and can be -called by the map-tools very much like on online routing service. - -To do that, you have to choose BRouter as a navigation service in your map-tool. -This is supported by OsmAnd, Locus-Maps and OruxMaps (In OsmAnd starting with version 1.7, -you see BRouter as a navigation service if BRouter is installed. You do not see the -option if BRouter is not installed). - -There's a mapping between the "routing-mode" asked for by the map-tool -(on out of 6: car/bike/foot * fast/slow) and BRouter's routing-profiles. -This mapping is stored in the file brouter/modes/serviceconfig.dat and is -pre-configured by the installation process to the following mapping: - - motorcar_fast -> car-test - motorcar_short -> moped - bicycle_fast -> fastbike - bicycle_short -> trekking - foot_fast -> shortest - foot_short -> shortest - -This mapping, however, can be changed any time by starting the BRouter-APP and using -the "Server Mode" button (or by editing the serviceconfig.dat manually). You can also -change gthe profiles themselves or create new ones. Please refer to the -"profile_developers_guide.txt" (contained in the distribution-zip) if you plan to -adapt routing profiles to your preferences. - -Note that if called via the service-interface, BRouter uses a timeout of 60 seconds, -which sets a limit on the distances you can calculate. - - -Calculate routes using the file interface -========================================= - -The other option is using the BRouter-App to calculate a route. This is the prefered option -when calculating long-distance-routes that would not finish within the 60 seconds timout -if calculated via the service-interface. - -To do this, start the BRouter-App, select two or more waypoints from the waypoint-database -of your map-tool and then start the route calculation. These waypoints are called "Favorites" -in OsmAnd, "POI"s in Locus or "Waypoints" in Oruxmaps and allow to store a location -on the map and give it a name. - -No need anymore to create special "to", "from", "via1..via9" points, but they are still supported -and if a "from" and a "to" wayppoint is found in the database, you will not be prompted -to select waypoints from the database. - -If a route is calculated, it is stored as "brouter0.gpx" in the map-tools track directory -(or, if there is no write-access, in brouter's base directory) -If started once more with identical input, BRouter will store a second route broute1.gpx -for the first alternative and so on. - -If more than one of the supported maptools is installed, BRouter chooses the way-point database -with the most recent timestamp. - - -Using nogo-areas -================ - -There's a special naming-convention to specify nogo-areas: - - "nogo[radius] [name]" defines 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 - names for nogo-waypoints. - -The effect is that BRouter searches a route that does not touch the disc -defined by the position and the radius of the nogo-area. - -Nogo-Areas are effective in the service-interface and in the BRouter-App. -In the BRouter-App, you will get a nogo-dialog allowing to de-select them -if nogo-waypoints are found in the waypoint-database. This de-selection -can also be bound to a service mode using the "Server Mode" button to make -it effective in the service-interface as well, but initially, every nogo-area -is effective in the service-interface. - -Nogo areas can be used either to account for real obstacles or to enforce -personal routing preferences. - - -Mixed operation: "timeout-free recalculations" -============================================== - -You can combine both operation modes (service-interface + BRouter-App) to -become able to calculate very long distances, but make use of the advantages of -the service interface as well, especially the dynamic recalculations if you get -off the track, without running into the 60 seconds timeout. - -To support this, BRouter can do "timeout free recalculations". It works by -initially calculating a track to your destination and binding it to one or -more routing-modes using the "Server Mode" button. This way, BRouter stores -a "reference track" in the "brouter/modes" subdirectory. - -If afterwards a route to the exact same destination is calculated via the service interface, -BRouter uses a special calculation mode that makes use of the reference track for -faster processing that is guaranteed to give a result within 60 seconds. -"Exact same" destination means withing 5m, so best use the same waypoint for -re-calculating that you used for the initial calculation. - -This way you can follow a long distance route via the service interface, enjoying -automatic recalculations if you get off the track. - - -Issues and bugs: -================ - diff --git a/misc/readmes/readme_Android11.txt b/misc/readmes/readme_Android11.txt deleted file mode 100644 index 0e49d33..0000000 --- a/misc/readmes/readme_Android11.txt +++ /dev/null @@ -1,221 +0,0 @@ -BRouter - Version 1.6.2 - Setting up the Android App -==================================================== - -Choosing and Installing a Map-Tool ----------------------------------- - - -BRouter just calculates tracks as GPX- or Geojson-output, 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 any map tool that can use the BRouter -interface without file access. So you need to install some, 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/ - -- "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. - - -Installing the BRouter App --------------------------- - -You can install the BRouter-App either from Google's Play Store -or directly from the APK-File contained within the "brouter-1.6.2.zip" -distribution zip-file. - -Choosing a SD-Card Base Directory ---------------------------------- - -When first starting BRouter (or after deleting/moving -the brouter folder on the sd-card), it asks for a -sd-card base directory and gives you proposals plus -the option to enter any other base directory. - -Most 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. - -Navigation needs big data files that usually should go on an -external, big sd-card. You should accept the external card, which -is usually the one with the most space available. - -Since Android 11 BRouter app uses only its local storage on -.../Android/media/btools.routingapp/ - -That means it can't access the folders from other apps like OsmAnd, OruxMaps or Locus. - - -Completing your installation ----------------------------- - -After accepting a base-directory proposal, "BRouter" creates a subfolders -relative to this base directory, so you end up with e.g. the following structure: -(depending on base dir and your map-tool choice): - -/mnt/sdcard/Android/media/btools.routingapp/brouter -/mnt/sdcard/Android/media/btools.routingapp/brouter/segments4 <- ** put routing data files (*.rd5) here ** -/mnt/sdcard/Android/media/btools.routingapp/brouter/profiles2 <- lookup-table and routing profiles -/mnt/sdcard/Android/media/btools.routingapp/brouter/modes <- routing-mode/profile mapping -/mnt/sdcard/Android/media/btools.routingapp/import <- allow a small file exchange with other apps -/mnt/sdcard/Android/media/btools.routingapp/import/tracks <- place the nogo* files here - - -The "profiles2" and the "modes" directory get some reasonable default-configuration -from the installation procedure, but the "segments4" directory is basically empty -(except for the storageconfig.txt file) so you have to get routing-datafiles in -order to complete your installation. - -After accepting the base directory, the download manager starts automatically to -help you with this download. Or you can download -them manually from the following location: - - http://brouter.de/brouter/segments4 - -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. The carsubset datafiles are needed only if you want to -calculate car-routes over long distances, otherwise you are fine with just the -normal (full) rd5's. - -The minimum files BRouter needs to work are e.g. - -/mnt/sdcard/Android/media/btools.routingapp/brouter/segments4/E5_N45.rd5 -/mnt/sdcard/Android/media/btools.routingapp/brouter/profiles2/lookups.dat -/mnt/sdcard/Android/media/btools.routingapp/brouter/profiles2/trekking.brf - -But of course you can put as many routing data files -and routing profiles as you like. - -Since folders on other apps are not longer available you could use the -import folder to place a favourites.gpx with waypoints or -in subfolder 'tracks' your nogo*.gpx files. - - -Routing via the service interface -================================= - -BRouter is best used via it's "service interface". No need to start the BRouter-App -in order to do that, it's just a services that sits in the background and can be -called by the map-tools very much like on online routing service. - -To do that, you have to choose BRouter as a navigation service in your map-tool. -This is supported by OsmAnd, Locus-Maps and OruxMaps (In OsmAnd starting with version 1.7, -you see BRouter as a navigation service if BRouter is installed. You do not see the -option if BRouter is not installed). - -There's a mapping between the "routing-mode" asked for by the map-tool -(on out of 6: car/bike/foot * fast/slow) and BRouter's routing-profiles. -This mapping is stored in the file brouter/modes/serviceconfig.dat and is -pre-configured by the installation process to the following mapping: - - motorcar_fast -> car-test - motorcar_short -> moped - bicycle_fast -> fastbike - bicycle_short -> trekking - foot_fast -> shortest - foot_short -> shortest - -This mapping, however, can be changed any time by starting the BRouter-APP and using -the "Server Mode" button (or by editing the serviceconfig.dat manually). You can also -change gthe profiles themselves or create new ones. Please refer to the -"profile_developers_guide.txt" (contained in the distribution-zip) if you plan to -adapt routing profiles to your preferences. - -Note that if called via the service-interface, BRouter uses a timeout of 60 seconds, -which sets a limit on the distances you can calculate. - - -Calculate routes using the file interface -========================================= - -The other option is using the BRouter-App to calculate a route. This is the prefered option -when calculating long-distance-routes that would not finish within the 60 seconds timout -if calculated via the service-interface. - -To do this, start the BRouter-App, select two or more waypoints from the favorite waypoint-database -in your import folder and then start the route calculation. These waypoints are called "Favorites" -in OsmAnd, "POI"s in Locus or "Waypoints" in Oruxmaps and allow to store a location -on the map and give it a name. Export them from the app to the import folder. - -No need anymore to create special "to", "from", "via1..via9" points, but they are still supported -and if a "from" and a "to" wayppoint is found in the database, you will not be prompted -to select waypoints from the database. - -If a route is calculated, it is stored as "brouter0.gpx" in the BRouter import/tracks directory. -If started once more with identical input, BRouter will store a second route broute1.gpx -for the first alternative and so on. - - -Using nogo-areas -================ - -There's a special naming-convention to specify nogo-areas: - - "nogo[radius] [name]" defines 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 - names for nogo-waypoints. - -The effect is that BRouter searches a route that does not touch the disc -defined by the position and the radius of the nogo-area. - -Nogo-Areas are effective in the service-interface and in the BRouter-App. -In the BRouter-App, you will get a nogo-dialog allowing to de-select them -if nogo-waypoints are found in the waypoint-database. This de-selection -can also be bound to a service mode using the "Server Mode" button to make -it effective in the service-interface as well, but initially, every nogo-area -is effective in the service-interface. - -Nogo areas can be used either to account for real obstacles or to enforce -personal routing preferences. - -Please note that nogo values can transfer also by new interface -parameter: polylines, polygons -see 'IBRouterService.aidl' for more information. - - -Mixed operation: "timeout-free recalculations" -============================================== - -You can combine both operation modes (service-interface + BRouter-App) to -become able to calculate very long distances, but make use of the advantages of -the service interface as well, especially the dynamic recalculations if you get -off the track, without running into the 60 seconds timeout. - -To support this, BRouter can do "timeout free recalculations". It works by -initially calculating a track to your destination and binding it to one or -more routing-modes using the "Server Mode" button. This way, BRouter stores -a "reference track" in the "brouter/modes" subdirectory. - -If afterwards a route to the exact same destination is calculated via the service interface, -BRouter uses a special calculation mode that makes use of the reference track for -faster processing that is guaranteed to give a result within 60 seconds. -"Exact same" destination means withing 5m, so best use the same waypoint for -re-calculating that you used for the initial calculation. - -This way you can follow a long distance route via the service interface, enjoying -automatic recalculations if you get off the track. - - -Issues and bugs: -================ -