From OpenStreetMap Wiki
Jump to navigation Jump to search

New maintainer needed

I had forgotten about this application to be honest, although I'm pleased to hear that after 8+ years there are still users. I received a crash report, and it seems things have changed in the .IMG file format that this converter does not understand... I don't have a Garmin anymore, nor the time to delve into this. Therefore, a new maintainer is needed! I did update the UI to provide an error message instead of crashing and a small fix (which may improve things from an external contributor), but that's all I can do for now.


Garmin only provides a Windows application, MapConverter.exe to convert Garmin maps from MapSource format to the OS X format so you can use the maps in Roadtrip and combine them with other maps if you have them.

In order to remedy this, I've written a small Python script which can be used to convert a collection of .img and .tdb files to the OS X format. It is only meant for OSM maps, such as created by Mkgmap or cGPSmapper, it is not meant as a replacement for Garmins application, I have not tested this on commercially available maps, and it probably will not work – commercial maps are usually encrypted.

The application is available in a command-line version and in an experimental version. Note that for example Lambertus provides daily builds for maps of the Netherlands which include an OS X installer.

Graphical version

The graphical version is probably the easiest to use. It can be downloaded here (100kb). It has been written as a Python script, and should work out of the box on at least OS X 10.4–10.12 (has been tested on 10.4 & 10.5 and 10.12), with the default Python systems, it requires no external modules. The various steps are illustrated by the pictures on the right.

(1) The empty main screen

1) After running the program, you see the main screen on the right. In order to succesfully convert a map, you need to select a .tdb file, the accompanying ‘base image’ and an input directory with a bunch of ‘.img’ files. Futhermore, you can specify the output directory where the .gmapi file will be located. For this to work, you first need to download a MapSource version of a map, consisting of one .tdb file and a many .img files, in this manual I use the map of Germany from Computerteddy, which you can find on his userpage as deutschland.tgz, described as Deutschlandkarte für den Einsatz mit QLandkarte oder Mapsource or Germany for use with QLandkarte or Mapsource.

(2) Selecting the TDB file

2) Pressing the top ‘...’ gives a normal OS X open dialog. Use this to navigate to the .tdb file. Here I have unpacked the deutschland.tgz archive to the directory ‘deutschland’, in which I select the (only) .tdb file.

(3) Selecting the .tdb fills the other fields with default values.

3) After you have selected the TDB file, some information about the map will be displayed, such as the name. Also, the program will guess the name of the base-image, which is usually the same as the tdb-file, only ending in .img; if this is not the case, you can change this by pressing the ‘...’ button. Furthermore, the directory containing all the other .img files is assumed to be the same as the directory in which the .tdb-file was located. By default, the gmapi folder will also be created under this directory. You can now press convert (the button should become active by now) or you can change a few settings.

(4) These other fields can be changed.

4) Optionally you can select a .typ file to include in order to style your map, if you don't have one, just leave this empty. Here I have included ‘teddy.typ’ which can also be found on Computerteddy’s userpage. Futhermore, I have changed the output directory. This does not influence the other fields, only selecting the .tdb file does.

(5) While converting progress is indicated.

5) While converting, it will indicate the status at the bottom. This shouldn't take too long normally. After converting, it will show a message. In case of any problems you'll get an Error popup. Conversion has failed. Quit the program...

Final message.
(6) The .gmapi in Finder

6) The name of the .gmapi file (which is in fact a directory) is determined by the value of the MapSeries in the .tdb file, as we can see here, it is called ‘OSM-Germany’. By default this should be associated with Garmins MapManager for Mac. If you double click it, it will ask whether it can install the map. (7)

(7) Garmins MapManager

Finally, after this is done, you can delete the directory with the tiles, if you want, and the .gmapi directory. The MapInstaller software copies everything to '~/Library/Application Support/Garmin/Maps/OSM-German.gmap'; this is the directory you need to delete if you want to get rid of the map. Then you can fire up Roadtrip and select the map from the menu at the top right:

Gmapibuilder Berlin.png


The Garmin format is not completely understood, and Mkgmap might produce maps which make Roadtrip and/or MapInstaller crash. The Windows versions of Garmins software appear to be more stable. If the map should cause really many problems, you can remove it by going to '~/Library/Application Support/Garmin/Maps' and move the appropriate folder to the trash. In case of MapInstall it can happen that it keeps crashing because it has some tiles selected of an OSM map and is unable to deselect them. If this happens, open up a and execute:

 rm "~/Library/Application Support/Garmin/MapInstall/lastSelected.gdb"
 rm "~/Library/Preferences/com.garmin.MapInstall.plist"

This way MapInstall will startup without any map selected. If you encounter other problems, please let me know also.

Upgrading / installing new maps

If you decide to install a new version of the same map, for example deutschland.tgz again, two weeks later, you can simply convert it in the same way (gmapi-builder will remove a previous version if it exists at the output location) and Garmins MapManager will also overwrite older version when installing.

You should note however that Roadtrip does not support two maps with the same Family ID and Product ID, if possible map makers should at least specify a product ID different from the (i.e. not 1) if they keep the Family ID at 0; otherwise it will be impossible to install maps along each other.

Commandline version

The commandline version can be downloaded here or direct from the bitbucket repository here and works both under OS X and Linux (at least). It requires Python 2.4, but will probably work with 2.3 too. The version from mkgmap repository supports index creation and non-ASCII characters.

Suppose you have downloaded deutschland.tgz from Computerteddy, and have unpacked this in the directory 'deutschland' which contains a bunch of .IMG files and a TDB file, then you could convert them like this (assuming is in your path): -t deutschland/63239999.tdb -b deutschland/63239999.img deutschland/*img

The -t switch indicates the TDB file, and the -b indicates the 'basemap', usually these have the same number. Finally you supply all the img files that belong to the map (including the baseimage!).

The program reads the map name, family name, product id and such from the supplied TDB file and will create a directory named '<Map Series>.gmapi'. In this case the map is called 'OSM-Germany', so it will make 'OSM Germany.gmapi'. By default it is done under the currunt working directory, but you can use -o to specify a different output directory under which the map is output.

If 'OSM-Germany.gmapi' already exists, it will be (recursively) removed. The output directory as specified by -o should exist however, because it will not be created.

Finally the inclusion of a style-file or .TYP file is supported by specifying -s.

Specifying -v or even -v -v increases the verbosity. Finally, specifying -d will not write anything; it will only parse the files. If you don't supply -vv you won't really see any progress while converting, but it shouldn't take too long.

This has been tested on maps created by mkgmap and cGPSmapper too, and will most certainly not work on commercially available maps. For one, these are usually encrypted (with an easy to decode encryption) and secondly, they use a different version of the file format (v 4.x usually, whereas mkgmap uses v 3.00); which might cause problems.


Same as for the graphical version.

If one runs mkgmap and gives --gmapsupp, one will have also a file gmapsupp.img, containing all the tiles and ready to load onto a device. One might be tempted to give that to gmapbuilder instead of all the constituent tiles, but that will fail to build a working gmapi map.


Robx for confirming that routable maps work too. Eckart Jäde for reporting the problems with .TYP files and suggesting a fix.


The software is licensed under the BSD license.