Improve documentation
* Improve documentation about BRouter usage and the provided scripts (misc/scripts). * Document how to use BRouter with third-party apps on Android (Locus / OSMAnd). * Improved process_planet_pbf.sh map creation script to make use of osmupdate if available and avoid downloading the planet file if not needed.
This commit is contained in:
Phyks (Lucas Verney)
parent
6faaa6ec23
commit
6ed1850518
9 changed files with 274 additions and 27 deletions
139
README.md
139
README.md
|
|
@ -1,40 +1,129 @@
|
|||
BRouter
|
||||
=======
|
||||
|
||||
BRouter is a configurable OSM offline router with elevation awareness, Java + Android. Designed to be multi-modal with a particular emphasis on bicycle routing.
|
||||
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.
|
||||
|
||||
For more infos see http://brouter.de/brouter
|
||||
For more infos see [http://brouter.de/brouter](http://brouter.de/brouter).
|
||||
|
||||
|
||||
## 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). 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).
|
||||
|
||||
<a href="https://f-droid.org/packages/btools.routingapp" target="_blank">
|
||||
<img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="90"/></a>
|
||||
<a href="https://play.google.com/store/apps/details?id=btools.routingapp" target="_blank">
|
||||
<img src="https://play.google.com/intl/en_us/badges/images/generic/en-play-badge.png" alt="Get it on Google Play" height="90"/></a>
|
||||
|
||||
### Android with Locus
|
||||
|
||||
## Build and Install
|
||||
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.
|
||||
|
||||
Compile with (Java 6!):
|
||||
|
||||
> mvn clean install -Dandroid.sdk.path=<your-sdk-path>
|
||||
|
||||
To skip building for Android, add ``-pl '!brouter-routing-app'``.
|
||||
|
||||
Next, download one or more [data file(s)](http://brouter.de/brouter/segments4/) (rd5) into the ``misc/segments4`` directory.
|
||||
|
||||
## Run
|
||||
|
||||
On Linux:
|
||||
> ./misc/scripts/standalone/server.sh
|
||||
|
||||
On Windows (using Bash):
|
||||
> ./misc/scripts/standalone/server.sh
|
||||
|
||||
On Windows (using CMD):
|
||||
> misc\scripts\standalone\server.cmd
|
||||
A full documentation on how to set this up is available at
|
||||
[https://www.locusmap.eu/locus-map-can-navigate-offline/](https://www.locusmap.eu/locus-map-can-navigate-offline/).
|
||||
|
||||
|
||||
Related Projects
|
||||
================
|
||||
### Android with OSMAnd
|
||||
|
||||
* https://github.com/nrenner/brouter-web
|
||||
* https://github.com/poutnikl/Brouter-profiles/wiki
|
||||
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).
|
||||
|
||||
|
||||
## BRouter on Windows/Linux/Mac OS
|
||||
|
||||
### Build and Install
|
||||
|
||||
To compile BRouter (including the BRouter Android app), use
|
||||
|
||||
```
|
||||
mvn clean install -Dandroid.sdk.path=<your-sdk-path>
|
||||
```
|
||||
|
||||
If you only want to compile BRouter and the server part (skipping the Android
|
||||
app), use
|
||||
|
||||
```
|
||||
mvn clean install -pl '!brouter-routing-app'
|
||||
```
|
||||
|
||||
You can use `-Dmaven.javadoc.skip=true` to skip the JavaDoc processing and
|
||||
`-DskipTests` to skip running the unitary tests.
|
||||
|
||||
|
||||
### Get the required segments (data) files
|
||||
|
||||
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
|
||||
[http://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 `misc/segments4` directory.
|
||||
|
||||
#### Generate your own segments files
|
||||
|
||||
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.
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
## Documentation
|
||||
|
||||
More documentation is available in the [`misc/readmes`](misc/readmes) folder.
|
||||
|
||||
|
||||
## Related Projects
|
||||
|
||||
* [nrenner/BRouter-web](https://github.com/nrenner/brouter-web), a web interface on
|
||||
top of the BRouter HTTP server. An online instance is available at
|
||||
[http://brouter.de/brouter-web/](http://brouter.de/brouter-web/).
|
||||
* [poutnikl/Brouter-profiles](https://github.com/poutnikl/Brouter-profiles/wiki),
|
||||
a collection of BRouter profiles.
|
||||
* [Phyks/BRouterTesting](https://github.com/Phyks/BrouterTesting), a
|
||||
collection of test cases for helping develop new BRouter profiles.
|
||||
|
||||
|
||||
## License
|
||||
|
||||
BRouter is released under an [MIT License](LICENSE).
|
||||
|
|
|
|||
81
misc/readmes/mapcreation.md
Normal file
81
misc/readmes/mapcreation.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
Build your own BRouter 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.
|
||||
|
||||
|
||||
## Build the pbfparser
|
||||
|
||||
First, there are two file formats available to download OSM data: `bzip`-ed
|
||||
XML files (very large) and `.pbf`
|
||||
([Protobuf](https://github.com/protocolbuffers/protobuf) format) which is much
|
||||
more efficient. If you want to use the latter one, you will have to build the
|
||||
`pbfparser` (located in `misc/pbfparser` first):
|
||||
|
||||
* Download [the latest
|
||||
version](https://bretth.dev.openstreetmap.org/osmosis-build/osmosis-latest.zip)
|
||||
of [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and unzip it
|
||||
somewhere.
|
||||
* Copy the `lib/default/protobuf-java-*.jar` and
|
||||
`lib/default/osmosis-osm-binary-*.jar` files from the unzipped Osmosis
|
||||
archive to `misc/pbfparser/protobuf.jar` and `misc/pbfparser/osmosis.jar`.
|
||||
* Build BRouter and copy
|
||||
`brouter-server/target/brouter-server-*-jar-with-dependencies.jar` to
|
||||
`misc/pbfparser/brouter.jar`.
|
||||
* You can build the `pbfparser` using, in the `misc/pbfparser/`
|
||||
folder,
|
||||
|
||||
```
|
||||
javac -d . -cp "brouter.jar:protobuf.jar:osmosis.jar" *.java
|
||||
```
|
||||
|
||||
* Finally, you can build a `jar` file from these files using
|
||||
|
||||
```
|
||||
jar cf pbfparser.jar btools/**/*.class
|
||||
```
|
||||
|
||||
_Note:_ If the `jar` file is not properly created, everything else will seem
|
||||
to work normally but there will not be any data extracted from the OSM data
|
||||
dump. You can check what is actually inside the built `jar` file using
|
||||
`jar tf pbfparser.jar`.
|
||||
|
||||
|
||||
## Run the map creation script
|
||||
|
||||
If you want to have elevation information in the generated segments files, you
|
||||
should download the required [SRTM
|
||||
files](https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/)
|
||||
and set the `SRTM_PATH` variable when running the `process_pbf_planet.sh`
|
||||
script.
|
||||
|
||||
Any flavor of the 90m SRTM database should be working, but the one used by the
|
||||
official BRouter segments files are the ones provided by
|
||||
[CGIAR](https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/).
|
||||
If you are working with rather small geographical extracts, you can download
|
||||
tiles manually using [this
|
||||
interface](http://srtm.csi.cgiar.org/SELECTION/inputCoord.asp) (use the
|
||||
"ArcInfo ASCII" format), instead of having to ask for an access for bulk
|
||||
download of data. There is no need to unzip the downloaded files, the
|
||||
`process_pbf_planet.sh` script expects a folder with all the ZIP files inside
|
||||
and will manage it.
|
||||
|
||||
Note that if you don't have the SRTM data available, the segments files will
|
||||
still be generated without any issue (but they will miss the elevation data).
|
||||
If you are not sure which SRTM files you have to download, you can run the
|
||||
script once and it will log all the SRTM files it is looking for.
|
||||
|
||||
You can now run the `misc/scripts/mapcreation/process_pbf_planet.sh` script to
|
||||
build the segments. Have a look at the variables defined at the beginning of
|
||||
the files and overwrite them according to your needs. By default, the script
|
||||
will download the latest full planet dump from
|
||||
[planet.osm.org](https://planet.osm.org/). You can also download a
|
||||
geographical extract provided by [Geofabrik](https://download.geofabrik.de/)
|
||||
and set the `PLANET_FILE` variable to point to it.
|
||||
|
||||
_Note:_ It is possible that you encounter an error complaining about not being
|
||||
able to run `bash^M` on Linux/Mac OS. You can fix this one by running
|
||||
`sed -i -e 's/\r$//' process_pbf_planet.sh`.
|
||||
64
misc/readmes/osmand/README.md
Normal file
64
misc/readmes/osmand/README.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
Using BRouter on Android with OSMAnd
|
||||
====================================
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Installing BRouter app on your Android device
|
||||
|
||||
First, 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). You
|
||||
can also build the BRouter Android app yourself.
|
||||
|
||||
<a href="https://f-droid.org/packages/btools.routingapp" target="_blank">
|
||||
<img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="90"/></a>
|
||||
<a href="https://play.google.com/store/apps/details?id=btools.routingapp" target="_blank">
|
||||
<img src="https://play.google.com/intl/en_us/badges/images/generic/en-play-badge.png" alt="Get it on Google Play" height="90"/></a>
|
||||
|
||||
|
||||
## Downloading BRouter segments
|
||||
|
||||
Then, launch the BRouter app and choose "Download Manager". Zoom in and select
|
||||
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.
|
||||
|
||||
<img src="./brouter-main.png" alt="Main menu of BRouter android app"/>
|
||||
|
||||
<img src="./brouter-grid.png" alt="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.
|
||||
|
||||
|
||||
## Selecting profiles to use
|
||||
|
||||
Once this is done, start again the BRouter app and choose the "BRouter App"
|
||||
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.
|
||||
|
||||
<img src="./brouter-profiles.png" alt="Profiles selection"/>
|
||||
|
||||
<img src="./brouter-profiles-summary.png" alt="Profiles selection summary"/>
|
||||
|
||||
|
||||
## Configure OSMAnd to make use of BRouter offline navigation
|
||||
|
||||
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.
|
||||
|
||||
<img src="./brouter-osmand.png" alt="BRouter configuration in OSMAnd
|
||||
application profiles"/>
|
||||
|
||||
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.
|
||||
BIN
misc/readmes/osmand/brouter-grid.png
Normal file
BIN
misc/readmes/osmand/brouter-grid.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
BIN
misc/readmes/osmand/brouter-main.png
Normal file
BIN
misc/readmes/osmand/brouter-main.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
BIN
misc/readmes/osmand/brouter-osmand.png
Normal file
BIN
misc/readmes/osmand/brouter-osmand.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
BIN
misc/readmes/osmand/brouter-profiles-summary.png
Normal file
BIN
misc/readmes/osmand/brouter-profiles-summary.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
BIN
misc/readmes/osmand/brouter-profiles.png
Normal file
BIN
misc/readmes/osmand/brouter-profiles.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
|
|
@ -1,6 +1,19 @@
|
|||
#!/bin/bash
|
||||
set -e
|
||||
wget -N http://planet.openstreetmap.org/pbf/planet-latest.osm.pbf
|
||||
cd "$(dirname "$0")"
|
||||
|
||||
# Fetch OSM planet dump if no planet file is specified
|
||||
if [ -z "$PLANET_FILE" ]; then
|
||||
if [ -x "$(command -v osmupdate)" ] && [[ -f "./planet-latest.osm.pbf" ]]; then
|
||||
# Prefer running osmupdate to update the planet file if available
|
||||
mv "./planet-latest.osm.pbf" "./planet-latest.old.osm.pbf"
|
||||
osmupdate "planet-latest.old.osm.pbf" "./planet-latest.osm.pbf"
|
||||
rm "./planet-latest.old.osm.pbf"
|
||||
else
|
||||
# Otherwise, download it again
|
||||
wget -N http://planet.openstreetmap.org/pbf/planet-latest.osm.pbf
|
||||
fi
|
||||
fi
|
||||
|
||||
if test lastmaprun.date -nt planet-latest.osm.pbf; then
|
||||
echo "no osm update, exiting"
|
||||
|
|
@ -20,7 +33,7 @@ OSMOSIS_JAR=$(realpath "../../pbfparser/osmosis.jar")
|
|||
PROTOBUF_JAR=$(realpath "../../pbfparser/protobuf.jar")
|
||||
PBFPARSER_JAR=$(realpath "../../pbfparser/pbfparser.jar")
|
||||
|
||||
PLANET_FILE=$(realpath "./planet-latest.osm.pbf")
|
||||
PLANET_FILE=${PLANET_FILE:-$(realpath "./planet-latest.osm.pbf")}
|
||||
# Download SRTM zip files from
|
||||
# https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/
|
||||
# (use the "ArcInfo ASCII" version) and put the ZIP files directly in this
|
||||
|
|
|
|||
Loading…
Reference in a new issue