Mkgmap/known issues

From OpenStreetMap Wiki
Jump to navigation Jump to search


This is a list of current issues known to affect mkgmap.

Compatibility issues

IMG files produced using mkgmap are known to work on some but not all Garmin GPS units. Some newer Garmin GPS units require Unicode maps that can display multiple alphabets or scripts in one map. Some examples of these devices are the Garmin Edge 1030, Garmin Oregon 700/750, Garmin Montana 610/680, and Garmin eTrex Touch 25/351. Notably, IMG files produced with mkgmap do not work on the Drive series of automotive GPS units.

IMG files produced using mkgmap are generally compatible with the Garmin nüvi series of automotive GPS units, and work particularly well with the 259x models using the fast 800Mhz processor, since mkgmap does not compress data in its IMG files as much as Garmin does. Navigation-Professionell published a list of known-to-be-compatible handheld units here. OpenMapChest has published another list of known-to-be-compatible Garmin units here. DC Rainmaker offers lists of compatible and incompatible models here.

Exit refs not used

Motorway exits (highway=motorway_junction) can be assigned a reference number and an exit_to value indicating where the exit leads. Neither of these values is used by mkgmap to generate routing hints. For instance, if there is an exit with ref 32 on a highway with ref E-11, and the exit is also tagged with exit_to=somePlace, the ideal situation would be routing hints that read:

  • Proceed along highway E-11 to exit 32
  • Exit at junction 32 to somePlace

This is not currently possible with mkgmap.

There are two options that fix the problem: --process-destination and --process-exits.

Draw order of ways is not understood

MapSource and Garmin GPS units ignore any OSM layer tags in ways, meaning that when rendered, the order of crossing ways does not reflect the true layer hierarchy stipulated in the layer tags. It is not clear if this is an explicit limitation of the Garmin IMG format, or if mkgmap is just not able to encode the appropriate information.

No basemap/overview map is created

Work is needed to create a basemap, which will speed up map redraw when zoomed far out inside when using Basecamp/Mapsource/Qlandkarte GT. This will allow for more sensible resolutions.

Routing over tile boundaries is broken in Mapsource/Basecamp

Routing inside Mapsource/Basecamp (though not on GPS) works inconsistently when the route crosses (several) tile boundaries.

Should not happen any more since mkgmap r3116.

Sea polygon generation works inconsistently

The --generate-sea option can be used to generate the sea polygons but is currently to be considered as "beta". There are two alternative ways of using --generate-sea: either with multipolygons (--generate-sea:multipolygon) or without multipolygons (--generate-sea:no-mp) combined with a TYP file.

This is fixed since r2278. Since this version the --precomp-sea option gives the directory where precompiled sea tiles containing the sea/land data only are located. Sea tiles can be compiled once and used for each mkgmap run. Please read how to compile the sea tiles. There are some sites that provide readily compiled sea tile packages.

add-pois-to-areas sometimes places the POI outside the polygon

When the --add-pois-to-area switch is applied to complex polygons (e.g. with strongly concave edges, such as beaches) the POI can be placed outside of the polygon with which it is associated. The calculation of what is "inside" a polygon is computationally complex, hence why no solution has yet been implemented.

Area too large

The Garmin files have a maximum size, so to create a map of a large area you need to split the file into a number of tiles using splitter. Here is how to do it:

java -Xmx1000m -jar splitter.jar file.osm
  • Run mkgmap on the resulting files, for instance
java -Xmx1000m -ea -jar mkgmap.jar -c template.args

See here for more details (you will most likely need to change splitter's --max-nodes switch to a lower value than the default).


The apply action in the style language allows relations to be translated. It is missing some features. Let us consider route relations as an example.

Match member roles by regular expression
Currently, apply role=value is for fixed strings.
Match relation members by type (way, node, relation)
Currently, relation members can only be matched by role
Match relation members by the tags that they already carry
Example: apply certain things to highway=bus_stop nodes only
Before applying, sort the relations by a user-defined criterion
A way may be served by multiple bus lines. Sort the bus route relations by alphabetic order of ref=*.
Allow filtering out duplicates
Opposing bus routes of the same line can consist of oneway segments as well as shared non-oneway segments.
Currently, the oneway segments would be labeled “42” and the non-oneway segments “42,42” for a bus line “42”.
If the bus route is defined as a single relation comprising both directions, then apply_once would do the trick.
Generate multiple map layers in one pass
This would reduce parsing overhead and reduce the complexity in style files and invocation scripts.
You normally might want to see only one of route=road, route=bicycle, route=bus at a time, by selecting visible map layers on the device.
This would be useful for certain points and lines too, e.g., generate traffic_calming=* on a separate layer

Error parsing pbf files

The error message:

Error at line 1, col 1
Bad file format: 63240001.osm.pbf
Error parsing file

usually means that mkgmap's pbf support is disabled. This happens if the pbf dependency jars are unavailable at buildtime and/or runtime.

The versions of mkgmap at have been built with pbf support enabled and the required jars are included, so they should work. If you build mkgmap from the svn repository yourself, you can use the ant buildscript. The resolve target downloads all required jar files.