OsmAndMapCreator

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages
català Deutsch English 한국어 polski

OsmAndMapCreator is an open-source Java tool that accompanies OsmAnd. It can download tiles from Mapnik and create POI, address, transport and routing indexes from OSM files (.osm, .bz2, .pbf). The most important feature is the creation of OBF files out of OSM data. OBF files are the basis for offline rendering, offline routing and offline search at a smartphone.

Editor's comment: This text aims to be understandable for ordinary people, too.

OsmAndMapCreator screenshot

Process of Map Creation

  1. Download an OSM data extract (PBF format from Geofabrik for the area you want to convert to OBF. Please pay attention to the high RAM consumption of OsmAndMapCreator (see below).
  2. If the extract is too large, you have to clip a smaller area out of it using Osmconvert.
  3. Create the OBF file with OsmAndMapCreator.
  4. Copy the resulting OBF file to your smartphone.

Downloading OsmAndMapCreator

OsmAndMapCreator does not need to be installed at your computer, just Java (Windows) or OpenJDK (Linux, OSX) has to be installed. You do not need administrative/root access if Java is installed already. If you do not know if Java is installed, just open a command line window and run the command java. If the output describes some arguments for starting Java and does not show a simple "file not found" (or something like this), Java is installed.

OsmAndMapCreator can be downloaded from developers' website. Afterwards extract the download zip-archive at any directory. If you use a Unix-like operating system (OS X, Linux) you have to make the .jar file excutable.

Creating Single OBF Files using the Graphical User Interface

Starting OsmAndMapCreator by a simple double-click is not the right way. You should assign OsmAndMapCreator more RAM than usually Java does in order that OsmAndMapCreator does not abort of lack of memory.

  • Users with command line experience: Open a command line window, change dirctory (cd) to the directory where OsmAndMapCreator.jar is and run the command java -jar -Xms1G -Xmx6G OsmAndMapCreator.jar. The numbers following -Xms and -Xmx declare the amount of RAM you assign to OsmAndMapCreator/Java. M stands for megabyte, G for gigabyte. The amount depends on the amount of RAM your computer has and the size of the PBF file. Details see below.
  • Users without command line experience: Open a file manager window (Windows Explorer, Nautilus etc.), change to the directory where OsmAndMapCreator.jar is and double-click OsmAndMapCreator.bat (Windows) / OsmAndMapCreator.sh (OS X/Linux). The bat or sh file starts OsmAndMapCreator and asserts a defined amount of memory as the command above. You should adapt the amount of memory in the bat/sh file. Details see below.

After starting OsmAndMapCreator, click on File, then on Create .obf from OSM file and select the downloaded/clipped PBF file. Wait until OsmAndMapCreator has finished. If you want to create a second OBF file, you should restart OsmAndMapCreator because OsmAndMapCreator does not free the used RAM.

Regular Creation of OBF Files (via Command Line)

If you use OBF files periodically you would like to automate this process. Even if it does not seem so, OBF files can be created via command line (and therefore via cronjobs)

On Debian-like Linux distributions you also have to install libcommons-logging-java (other distributions not tested)

The workflow:

  1. Download raw data (e.g. at Geofabrik) or update existing extracts using Osmconvert or Osmosis.
  2. Clip raw data if necessary.
  3. Rename raw data files to COUNTRY.osm.pbf and move them to /home/$user/mapbuild/osmand-pbf
  4. Start OsmAndMapCreator, all extracts will be converted to OBF and saved at /home/$user/mapbuild/osmand-obf

If you use other directories than those called above, you have to change them in batch.xml (see below).

Batch.xml

Before you start OsmAndMapCreator you have to adapt the settings inside batch.xml in your OsmAndMapCreator directory.


batch.xml Template

Replace $user by your local user name.

<?xml version="1.0" encoding="utf-8"?>
<batch_process>
	<process_attributes mapZooms="" renderingTypesFile="" 
                zoomWaySmoothness="" osmDbDialect="sqlite" mapDbDialect="sqlite" />
	<process directory_for_osm_files="/home/$user/mapbuild/osmand-pbf" 
		directory_for_index_files="/home/$user/mapbuild/osmand-obf" 
		directory_for_generation="/home/$user/mapbuild/osmand-gen"
		skipExistingIndexesAt="/home/$user/mapbuild/osmand" 
		indexPOI="true" indexRouting="true" indexMap="true"	
		indexTransport="true" indexAddress="true"/>		
	</process/>
</batch_process/> 

batch.xml Settings

The XML element process_attributes describes the settings for creation of OBF files. You can just use the example batch.xml above without editing apart from adapting the paths.

If you have a large amount of RAM available, you can store the temporary SQLite databases in RAM instead at the working directory (see attribut directory_for_generation in batch.xml). Storing the temporary databases in RAM speeds up the creation of OBF files about 10–50 %. If you do not have enough RAM, you should not store the temporary databases in RAM because then the operating systems has to swap. To store the temporary databases in RAM replace
<process_attributes mapZooms="" renderingTypesFile="" zoomWaySmoothness="" osmDbDialect="sqlite" mapDbDialect="sqlite" />
by
<process_attributes mapZooms="" renderingTypesFile="" zoomWaySmoothness="" osmDbDialect="sqlite_in_memory" mapDbDialect="sqlite_in_memory"/>
'Warning: OsmAndMapCreator needs a very large amout of RAM. For a 230 MB PBF file you should have at least 12 GB RAM if you do not want to store the databases at HDD/SSD.

The other settings in batch.xml are:

key value
directory_for_osm_files directory where downloaded/updated and clipped PBF files are
directory_for_index_files directory where the final OBF files will be saved
directory_for_generation directory where the temporary SQLite databases are saved
indexPOI make POI index (true/false)
indexRouting make routing index (true/false)
indexMap make map index for rendering (true/false)
indexTransport make public transport index (true/false)
indexAddresses make address index for address search (true/false)

Starting OBF creation

OsmAndMapCreator does only convert the PBF files if they are name as LAND.osm.pbf and stored at directory_for_osm_files! To start OsmAndMapCreator, change to the directory where you have unzipped OsmAndMapCreator and run the following command (adapt the memory assignment if necessary):

java -Djava.util.logging.config.file=logging.properties -Xms64M -Xmx6300M -cp "./OsmAndMapCreator.jar:lib/OsmAnd-core.jar:./lib/*.jar" net.osmand.data.index.IndexBatchCreator batch.xml

RAM requirement

RAM usage

OsmAndMapCreator needs a multiple of the size of the OBF file. You should only make OBF files of large areas if your computer has enough RAM. Please remember that the operating system also needs some RAM. Just have a look at task manager in idle state. Remember that 32-Bit systems can only use 3.3 GB RAM.

The following table lists the example file size and memory consumption. Please bear in mind that OSM contains more and more data. That's why PBF files increase day by day.

Annotation: This table is not finish. You can add your values if you created an OBF file. Please only add your RAM and time consumption if you have not run any other programs with high RAM consumption at the same time. (similar test conditions)

region size of PBF file RAM consumption RAM assigned at starting OsmAndMapCreator time consumption
Baden-Württemberg, Germany 220 MB ca, 3 h 15 min (Linux 64 Bit, Intel Core i5-460M, 8 GB RAM)
Bayern, Germany 300 MB aborted by user after more than 7 h (Linux 64 Bit, Intel Core i5-460M, 8 GB RAM)
Niedersachsen, Germany 280 MB below 4 GB 1500 MB (OsmAndMC V1.1.0) 52 min (Win 64, AMD II X2 3.0 GB, 16 GB RAM)
Sachsen-Anhalt, Germany 46 MB ca. 15–20 min (Linux 64 Bit, Intel Core i5-460M, 8 GB RAM)

Areas at the size of Bavaria (300 MB) and large cannot be converted into OBF format at a stretch. You have to split this areas and convert each parts. That's why the OsmAnd developers do not provide whole Germany as OBF (1.8 GB PBF file) for download.

Adapt amount of assigned RAM

There is the string -Xms64M -Xmx512M in OsmAndMapCreator.bat and OsmAndMapCreator.sh file. Replace this values (64M and 512M) by values from the table above. You should leave at least 1.3 GB for the operating system if you use Windows. Under Linux this amount depends on your desktop environment, e.g. 800 MB for the RAM-hungry Unity.

Example calculation:

(1) installed RAM 4 GB
(2) RAM consumption in idle state (depends on operating system, see task manager) 1.3 GB
(3) difference between (1) and (2) 2.7 GB
(4) minimal RAM assignation (value after -Xms) 200 MB
(5) maximum RAM assignation (Wert after -Xmx) 2.5 GB (Do not use a decimal seperator, write -Xmx2500M instead.)

There must not be a space between -Xms or -Xmx and the numerical value.

Copy OBF File(s) to Your Smartphone

The finish OBF file(s) are stored in OsmAnd's app directory on your phone. You can change the location of the app directory in OsmAnd settings at section General. /mnt/sdcard/osmand is a good location. (Attention! The mount point of the SD card may be different to /mnt/sdcard.) If you want to store the OBF files at /mnt/sdcard/osmand, you have to set /mnt/sdcard (without osmand) as Storage directory. Please attend that Android is based on Linux and case-sensitive! /mnt/extSdCard and /mnt/extsdcard are two different directories!

See also