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

Restrucuture documentation to smaller parts

Browse source
This commit is contained in:
Manuel Fuhr 2021-12-29 08:49:47 +01:00
parent 76f20ca864
commit 80681b78c6
12 changed files with 300 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/developers/android_service.md Normal file
View file

@ -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.

1
docs/developers/build_segments.md
View file

@ -1,5 +1,6 @@
---
parent: Developers
title: Build segment files
---
Build your own segments files

16
docs/developers/http_server.md Normal file
View file

@ -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`

21
docs/developers/index.md
View file

@ -22,24 +22,3 @@ 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.
## 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
[`brouter-server/src/main/java/btools/server/request/ServerHandler.java`](brouter-server/src/main/java/btools/server/request/ServerHandler.java)
file.
## 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
[`brouter-routing-app/src/main/aidl/btools/routingapp/IBRouterService.aidl`](brouter-routing-app/src/main/aidl/btools/routingapp/IBRouterService.aidl)
for the interface definition.

2
docs/features/elevation.md
View file

@ -2,7 +2,7 @@
parent: Features
---
## Elevation algorithm
## 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

28
docs/features/offline.md
View file

@ -27,31 +27,3 @@ 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.
### Installing the BETA Version of BRouter on an Android smartphone.
Before trying the Android app, you should have a look one the [online
version](/brouter-web) to see what it's doing.
What you should also do before trying the BRouter Android app is to install, an
get familiar with, one of the supported map-apps. This is either
[OsmAnd](http://www.osmand.net), which is a full offline navigation solution on
it's own, but especially it's a wonderful offline OSM map tool and is able to
give spoken directions to routes calculated either internally or externally.
Other options are [Locus](http://www.locusmap.eu/) or
[OruxMaps](http://www.oruxmaps.com/index_en.html).
The BRouter Android app assumes that at least one of OsmAnd, Locus or OruxMaps
is installed - it will not work otherwise.
If you are o.k. with all that, you can install the BRouter Android app from the
[brouter_1_6_1.zip](../brouter_bin/brouter_1_6_1.zip) installation ZIP-file
including the APK and read the [readme.txt](readme.txt) ( **READ ME !** ) for
details on how to add routing data and navigation profiles to your installation
and how the interfacing between BRouter and the supported map-tools works.
Navigation profiles and the lookup-data are [here](profiles2) Routing data files
per 5*5-degree square are [here](/brouter/segments4)
(The Map-Snapshot date is about 2 days before the timestamp of the routing data
files)

15
docs/features/vianogo.md
View file

@ -7,17 +7,10 @@ parent: Features
BRouter can process via-points and nogo-areas, and [brouter-web](/brouter-web)
offers on online interface to edit both of them.
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.
NoGo-Areas are forbidden areas. In fact, these are areas, not points, with a
default radius of 20m around the given point. Every way that is touching this
disc of 20m radius is excluded by the routing algorithm. But the radius can also
be specified: a waypoint `nogo` default to 20m radius, but `nogo100` defines a
nogo area with 100m radius. Theres no limit in radius, so you can also exclude a
whole geographic region with a single nogo-area.
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.

9
docs/index.md
View file

@ -4,7 +4,7 @@ title: Home
nav_order: 1
---
## BRouter: Let's get serious about bike routing
# 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
@ -20,17 +20,12 @@ 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
@ -49,7 +44,7 @@ if you want to use BRouter online.
### Android app for offline routing
See [offline routing app](features/offline.md) for how to setup BRouter for
See [Android quickstart guide](users/android_quickstart.md) for how to setup BRouter for
offline routing on an Android smartphone.
### Revision history

146
docs/users/android_advanced.md Normal file
View file

@ -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 |
| --------------------------------- | -------------------------------------------- |
| `<basedir>/brouter` | |
| `<basedir>/brouter/modes` | routing-mode/profile mapping and route cache |
| `<basedir>/brouter/profiles2` | lookup-table and routing-profiles (\*.brf) |
| `<basedir>/brouter/segments4` | **routing data files (\*.rd5)** |
| `<basedir>/brouter/import` | allow a small file exchange with other apps |
| `<basedir>/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](users/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
`<basedir>/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.

92
docs/users/android_quickstart.md Normal file
View file

@ -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](https://osmand.net/features/navigation-profiles#create_brouter)
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 _\<repeat:...\>_. BRouter caches
the routing result and further requests using the _same_ destination using the
_service interface_ will be successful.

23
docs/users/download_segments.md Normal file
View file

@ -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.

30
docs/users/index.md
View file

@ -1,8 +1,10 @@
---
title: Using BRouter
has_children: true
nav_order: 3
---
# Using BRouter
## Online
Check [brouter-web](https://brouter.de/brouter-web/) or
@ -10,30 +12,8 @@ Check [brouter-web](https://brouter.de/brouter-web/) or
## BRouter on Android
You can install the BRouter app on your Android device from
[F-Droid](https://f-droid.org/packages/btools.routingapp) or [Google Play
Store](https://play.google.com/store/apps/details?id=btools.routingapp). Older
versions are available in the [revision history](../revisions.md). You can find
detailed documentation of the BRouter Android app in
[`misc/readmes/readme.txt`](misc/readmes/readme.txt).
### Android with Locus
You can use BRouter as the offline routing engine for [Locus
Map](https://www.locusmap.eu/) on your Android device. This is currently the
most featureful and maintained solutions for using BRouter on your Android
device.
A full documentation on how to set this up is available in the [LocusMap user
manual](https://docs.locusmap.eu/doku.php?id=manual:faq:how_to_navigate_offline).
### Android with OsmAnd
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 in the [OsmAnd feature
description](https://osmand.net/features/navigation-profiles#create_brouter).
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