Mkgmap

From OpenStreetMap

Jump to: navigation, search
Quick links
Documentation
Development
Download maps

This program converts OpenStreetMap data into a map that can be loaded onto a Garmin GPS device. It does the conversion in one step without depending on any other program.

The goal of the project is to take OpenStreetMap data and put it on my Garmin Legend Cx to help show me when mapping what is done and what is not. Plus its just fun to see the map that you created being used.

It requires Java 1.5, so should work anywhere that JOSM is available.

It was written by Steve Ratcliffe. Bug report or suggestions can be e-mailed to me or added to the talk page. I'd be interested to hear of successfully loading maps to other than a Legend Cx too.

Contents

Downloading

The downloads are now available as zip file, which may be more convenient on Windows machines as well as compressed tar files. The contents of the archives are identical.

30 Apr 2008 Current stable version is 586

The main changes since 563 are:

  • New style system that allows for different named styles. There are no alternative styles yet, although you can write them.
  • Can specify which tag(s) to use for the name. So for example you could create a Welsh map by specifying --name-tag-list='name:cy,name'. (Actually you could do that before, but I forgot to mention it)
  • Man page, --help and --version options added.
  • Beginning of POI support
  • Runs again with GNU classpath, although only seems to work for smallish files.
  • (From r584) Re-instated --map-features option.
Download

Notes:

  • It requires Java 1.5 or above. If you don't have that you can get that from the Sun Java site. As of March 2007, the current Java version is 1.6.

Creating a map

  • Create a file containing OSM data. I do this by saving from JOSM. You can call the file anything you like — I'm using data.osm in the example. You can also get a larger map area by using Osmxapi like this (example for the UK Midlands area): 
   wget http://www.informationfreeway.org/api/0.5/*[bbox=-3.5,51.5,-1.0,53.5] -O data.osm
  • Then to make the map image for the Garmin run the following command: 
   java -jar mkgmap.jar [options] data.osm
  • This will produce a file called 63240001.img

It's possible that the application may crash out after a point, particularly if you're processing a large area, with Exception in thread "main" java.lang.OutOfMemoryError: Java heap space errors. If this happens, simply increase the size of your max heap space like this: 

   java -Xmx512M -jar mkgmap.jar [options] data.osm

which would allocate 512Mb of physical memory to the process.

Command line options

For larger maps you may want to alter some details of the default map there are options you can set. If you want to set several options it might be easier to put the options into a file and use the the -c option.

-c filename
The given file is opened and each line is an option setting of the form option=value, just like on the command line except that there is no leading '--'.
-n name
--mapname=name
Change the name of the map. Garmin maps are named by 8 digit numbers. The default is 63240001. It is best to change the name if you are going to be making a map for others to use so that it is unique and does not clash with others.
NOTE: enter just the name, without the ".img" extension, otherwise the tool will throw an exception --Breki 20:17, 25 October 2007 (BST)
--description=text
Sets the descriptive text for the map. This may be displayed in QLandkarte, MapSource on on a GPS etc.
--map-features=file
Use your own map features file. You can completely change which features are shown and at what levels. See customisation help.
--levels=levels code
Change the way that the levels on the map correspond to the zoom levels in the device. See customisation help. The default is the equivalent of: "0=24, 1=22, 2=21, 3=19, 4=18, 5=16" although this may change.
--latin1
This option allows the use of non-ascii characters in street names. It is hardware dependant what is actually supported on a particular device. Some devices can only do ascii characters for example.
Mkgmap goes to some length to convert un-displayable characters however. It will convert accented characters that cannot be displayed in the chosen character set into unaccented characters.
--gmapsupp
This creates also a combined map (GMAPSUPP.IMG) from all supplied .osm/.img files. Combined maps can be copied directly to GPS devices that support mass storage mode. Make sure to put the file into the /Garmin directory. This option needs version 388 or later.


Installing

  • Load this onto your Garmin GPS device. Garmin models such as the Legend Cx can be set into USB mass storage mode, where they appear as just another drive letter (on Windows) or filesystem (on Unix/Linux type systems). In this case you can just copy the map to the file Garmin/gmapsupp.img. Create the folder Garmin if it does not already exist.
  • If you have an older serial connecting and map displaying Garmin device you can upload the .img file to your Garmin unit using Sendmap.
  • You can also combine two ore more maps to one map with Sendmap or gmaptool.
  • The QLandkarte program can be used to upload to the GPSmap 60CSx and the latest version also works to my Legend Cx.

Known issues

Currently known problems.

  1. At a particular level of zoom, some roads look like staircases.
  2. The coastline is shown, but really there should be sea polygons instead.
  3. If you are using mkgmap on the UK, you will run into problems. This is due to the size of the UK file now, which no longer fits into a single Garmin map tile. To resolve this, download osmcut.jar from here and before running mkgmap, run 
   java -Xmx512M -jar osmcut.jar 3.5 data.osm <output directory>

Note: This will split the UK into separate planet files, which each contain roughly 3.5degrees of data. This will allow you to then run mkgmap on all the files in the output directory, and you will get a single gampsupp.img combining all these back together again. Unfortunately, there is a known issue with this solution - a number of short ways which cross the joins of these files will be lost, so your resulting map will not be 100% complete.

Development

There is a wiki page for development, mainly based around OSM usage.

There is also an external page for using mkgmap to create garmin img format maps.

Licence

The software is licensed under the GPL version 2. The maps it produces are to be licensed according to the data they were derived from which is Creative Commons CC-BY-SA 2.0 for OSM data. There is therefore no licensing conflict that might exist with other approaches.

Links

Retrieved from "http://wiki.openstreetmap.org/index.php/Mkgmap"
Personal tools
recent changes