Building road network graphs

ODL Studio uses the Graphhopper project to provide road network distances and times based on OpenStreetMap data. Graphhopper uses a road network graph, stored in several different files, to calculate the distances and times. To use Graphhopper for different countries you must first build the road network graph from the original OpenStreetMap source data.

You will also need to rebuild this graph sometimes when you upgrade to a new version of ODL Studio - for example graphs built before ODL Studio version 1.3.4 do not work with version 1.3.4 or later.

To build a graph for your own country, you need an OpenStreetMap extract for it. Geofabrik provides extracts for different countries on their download server. If you download from Geofabrik, be sure to download the file version with the .pbf extension.

For 64-bit Windows users

As of ODL Studio v1.4.0 we now include a graph builder tool to simplify building road network graphs. In Windows file explorer, navigate to the ODL Studio install directory and then run the appropriate bat file to start the tool:

• Build graph for osm-pbf file less than 1 GB - needs 2 GB RAM free - 64 bit Windows.bat

• Build graph for osm-pbf file less than 3 GB - needs 5 GB RAM free - 64 bit Windows.bat

• Build graph for osm-pbf file more than 3 GB - needs 10 GB RAM free - 64 bit Windows.bat

After starting the .bat file, follow the on-screen instructions. You should pay attention to the requirements for your computer memory, if you have less memory available on your system the tool may either (a) not start at all or (b) stop working when it runs out of memory.

If you’re building a graph for the whole USA you will also need to modify the run ODL Studio .bat file to be able to run it - see technical details in the section below.

All other users

For all other users we have a command line tool. In this example we will build a road network graph for Malta. The original OpenStreetMap file for Malta is available here (unzip the .pbf file before using it).

Once you have your .pbf extract file, create a new directory on your computer to store it and place the file in this directory. You should use a directory outside of Program Files as by default Windows will not let applications write to directories within Program Files. In this example, we store malta-latest.osm.pbf in a directory c:\temp. You should also avoid directory names containing spaces.

Now open up a command window by entering ‘cmd’ into the search box of the window start menu. Use the cd command (short for change directory) to navigate to the Graphhopper subdirectory within the ODL Studio installation directory, for example:

cd c:\Program Files\ODLStudio-1.3.2-Win-64-bit\graphhopper

Within this directory there are two important files - a file named graphhopperXXXXX.jar (where XXXXX will vary for different versions of ODL Studio) and a file config.properties which stores Graphhopper’s configuration. graphhopperXXXXX.jar is an executable java jar file which builds the road network graph. Now build the graph for Malta by entering the following into the command line:

java -Xmx2G -jar graphhopper-0.4-SNAPSHOT-jar-with-dependencies.jar config=config.properties osmreader.osm=c:\temp\malta-latest.osm.pbf

If the java command isn’t recognised, install java on your computer. Similarly if the command is recognised but you get an error saying ‘class version not supported’ or similar, you probably need to upgrade to the latest version of java.

In this example, graphhopperXXXXX.jar is called graphhopper-0.4-SNAPSHOT-jar-with-dependencies.jar. You should ensure you enter the exact name of the graphhopper jar file in your directory (in later versions it is called graphhopper-fat-jar instead). When you build the road network graph for your own country, you should replace c:\temp\malta-latest.osm.pbf with the path to your input OSM extract.

When you run the above command, Graphhopper will process the file for a few minutes and then create an output directory with the Graphhopper files. Once you have the output directory, configure ODL Studio to point towards this directory under the distance options as shown in the vehicle routing youtube video. If you have updated your input .pbf file and want to create a new output road network graph, you should delete the output directory before running the command.

Graph files for large countries (e.g. USA)

For larger countries - such as the USA - you also need to give java more memory when its building the file, otherwise you will get an out-of-memory error. You do this using the -Xmx command. In the above example, we’ve set -Xmx2G which gives java a maximum of 2 GB. For the USA you need to set this to at least 8 GB (so change to -Xmx8G). If you set the maximum memory higher you should also ensure that your computer actually has this RAM physically available (roughly speaking if you close all other applications, then you can guarantee having the physical memory of your machine minus around 2 GB for windows). You also need to change this Xmx setting when running ODL Studio, by editing the Run ODL Studio 64-bit.bat file in your ODL Studio installation directory (if you have file Run ODL Studio 32-bit.bat instead then you’re running the 32 bit version of ODL Studio, for 32 bit computers, which can only use a maximum of 2 GB anyway). Edit the file and insert the -Xmx8G command into the run line before -jar com.opendoorlogistics.studio.jar. You’ll probably need to copy the .bat file into another directory outside of program files to be able to edit it, and then copy it back afterwards.

Building for bike, motorcycle or pedestrian routes

As of ODL Studio version 1.3.4, you can also model route for bicycles, motorcycles or pedestrians (but only one type at time). The graphhopper directory comes with alternative config.properties files for these vehicle types:

• config-bike.properties
• config-foot.properties
• config-motorcycle.properties

Simply replace config.properties in the command line above with properties file for the type of vehicle you want to use, and then build your graph for that vehicle instead. For example, for a Windows install this command will build for bicycle:

java -Xmx2G -jar graphhopper-0.4-SNAPSHOT-jar-with-dependencies.jar config=config-foot.properties osmreader.osm=c:\temp\malta-latest.osm.pbf