diff --git a/README.md b/README.md index 290c09f..9d4d9ec 100644 --- a/README.md +++ b/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). Get it on F-Droid Get it on Google Play +### 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= - -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= +``` + +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). diff --git a/misc/readmes/mapcreation.md b/misc/readmes/mapcreation.md new file mode 100644 index 0000000..debc738 --- /dev/null +++ b/misc/readmes/mapcreation.md @@ -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`. diff --git a/misc/readmes/osmand/README.md b/misc/readmes/osmand/README.md new file mode 100644 index 0000000..bf0059b --- /dev/null +++ b/misc/readmes/osmand/README.md @@ -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. + + +Get it on F-Droid + +Get it on Google Play + + +## 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. + +Main menu of BRouter android app + +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. + +Profiles selection + +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. + +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. diff --git a/misc/readmes/osmand/brouter-grid.png b/misc/readmes/osmand/brouter-grid.png new file mode 100644 index 0000000..0d97c68 Binary files /dev/null and b/misc/readmes/osmand/brouter-grid.png differ diff --git a/misc/readmes/osmand/brouter-main.png b/misc/readmes/osmand/brouter-main.png new file mode 100644 index 0000000..3541654 Binary files /dev/null and b/misc/readmes/osmand/brouter-main.png differ diff --git a/misc/readmes/osmand/brouter-osmand.png b/misc/readmes/osmand/brouter-osmand.png new file mode 100644 index 0000000..3586cc2 Binary files /dev/null and b/misc/readmes/osmand/brouter-osmand.png differ diff --git a/misc/readmes/osmand/brouter-profiles-summary.png b/misc/readmes/osmand/brouter-profiles-summary.png new file mode 100644 index 0000000..d849a9e Binary files /dev/null and b/misc/readmes/osmand/brouter-profiles-summary.png differ diff --git a/misc/readmes/osmand/brouter-profiles.png b/misc/readmes/osmand/brouter-profiles.png new file mode 100644 index 0000000..e795b53 Binary files /dev/null and b/misc/readmes/osmand/brouter-profiles.png differ diff --git a/misc/scripts/mapcreation/process_pbf_planet.sh b/misc/scripts/mapcreation/process_pbf_planet.sh index 36b635e..dd6d97d 100755 --- a/misc/scripts/mapcreation/process_pbf_planet.sh +++ b/misc/scripts/mapcreation/process_pbf_planet.sh @@ -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