Fork me on GitHub

Mapsforge Support


This article will walk you through the setup, usage and known limitations of using osmdroid's MapsForge adapter

What is Mapsforge?

MapsForge is a vector map library written in Java with support for Android and JRE. It works by rendering osm data on demand (on device).


Osmdroid's adapter for MapsForge is located here. This was migrated from osmbonuspack in version 5.2.


MapsForge code is LGPLv3. osmdroid's adapter for mapsforge is ASF 2.0.

How to Use

Adding the dependency

This is pretty basic. The maps forge adapter is published to Maven Central as an Android Archive (.aar) file. Add the following under dependencies in your file.

compile "org.osmdroid:osmdroid-mapsforge:<VERSION>@aar"

(currently =6.0.1)

You will also have to add the following dependencies:

compile 'org.mapsforge:mapsforge-map-android:<MapsForge VERSION>'
compile 'org.mapsforge:mapsforge-map:<MapsForge VERSION>'
compile 'org.mapsforge:mapsforge-themes:<MapsForge VERSION>'

(currently =0.8.0)

The minimum API level required by MapsForge is API 10.

Code setup

//super important to configure some of the mapsforge settings first in your activity onCreate:

File[] maps = null;  //TODO scan/prompt for map files (.map)

XmlRenderTheme theme = null; //null is ok here, uses the default rendering theme if it's not set
try {
//this file should be picked up by the mapsforge dependencies
	theme = new AssetsRenderTheme(getContext().getApplicationContext(), "renderthemes/", "rendertheme-v4.xml");
	//alternative: theme = new ExternalRenderTheme(userDefinedRenderingFile);
} catch (Exception ex) {

MapsForgeTileSource fromFiles = MapsForgeTileSource.createFromFiles(maps, theme, "rendertheme-v4");
MapsForgeTileProvider forge = new MapsForgeTileProvider(
	new SimpleRegisterReceiver(getContext()),
	fromFiles, null);


//now for a magic trick
//since we have no idea what will be on the
//user's device and what geographic area it is, this will attempt to center the map
//on whatever the map data provides
        new Runnable() {
            public void run() {
                mMapView.zoomToBoundingBox(fromFiles.getBoundsOsmdroid(), false);

Lifecycle/resource management issues

  • There are cleanup tasks required if you are switching providers around on the fly. See the function example for details.
  • The MapsForge adapter will honor the IConfigurationProvider.getTileFileSystemThreads() for the maximum number of concurrent rendering threads.

Functioning Examples

For a complete function example, see MapsforgeTileProviderSample

Combining Mapsforge tiles with other sources

It is possible to use multiple tile providers at the same time. This can be done by having multiple TileOverlays. The MapView will always have one of them, which can be interacted with by MapView.getOverlayManager().getTilesOverlay(). There's an example of this here.

How does this work?

The MapsForge adapter implements the tile provider pattern. It is not a simple tile source since there are lifecycle issues and Mapforge tile source didn't seem possible.


None that are known