Mkgmap/help/Custom styles
This page is outdated. Please refer to the style manual of mkgmap for up-to-date information.
This page shows you how to design your own mkgmap style. A style is used to choose which OSM map features appear in the Garmin map and which Garmin symbols are used.
As there are many different purposes a map may used for, the default style in mkgmap will not be ideal for everyone. So a mechanism to allow different named styles to be included within mkgmap has been developed. You can also create and use styles external to mkgmap.
To be clear this is only needed for converting OSM tags, if you are starting with a Polish format file, there is no style involved as the garmin types are already fully specified in the input file.
See also: Style rules.
Writing a style
A style consists of a number of files in a single directory. The best way is to start out with an existing style that is close to what you want and then work from there. See the mkgmap directory /resources/styles/default for an example style.
A complete description of the format of all the files that make up a style follows.
First steps
Choose a short name for your style, it should be one word or a couple of words joined by an underscore or hyphen. This is how people will refer to the style when it is finished. Create a directory or folder with that name. Then you must create one or more files in this directory as detailed below. Only the version file is required.
Files
This files are read in the order that they are listed here. In general files that are read first take priority over files read later.
version
Mandatory. This file must exist as it is used to recognise a valid style. It should contain the number 0. Make sure that there is a new line after the number, place an empty line afterwards to be sure.
info
Optional. This file can contain a short description of the style and other information such as the author etc. See the comments in this file.
options
This file contains a number of options that should be set for this style as if they were set on the command line. Only command line options that affect the style will have any effect. The current list is name-tag-list and levels.
It is advisable to set up the levels that you want as the default is not suitable for all kinds of maps and may change in the future. Ideally, you should set the same levels as are used in your style files. For example, if your style files use levels 12,16,20,22,23,24 then it's a good idea to make sure your options style file declares these levels explicitly.
levels=0:23, 1:21, 2:19
points
Optional. This contains a set of rules that show how to convert nodes to Garmin POIs (restaurants, bars, ATMs etc). See the style rules page for complete details of how this file works.
lines
Optional. This contains a set of rules that show how to convert OSM ways to Garmin lines (roads, rivers, barriers etc). See the style rules page for complete details of how this file works.
polygons
Optional. This contains a set of rules that show how to convert polygons to Garmin areas (fields, buildings, residential areas etc). See the style rules page for complete details of how this file works.
relations
Optional. Can be used to highlight mtb, bicycle, foot or other relations. Explications on how to use it are explained in the Relations file in the default style-file of mkgmap. Works in general like the other files.
overlays
Optional. Used where you want a single way to be converted to two ways in the output map (for example a road might be rendered as normal but an additional line is created if the road is oneway - this then allows you to use a TYP file to add oneway arrows to the road). An example of use might be:
In the lines file:
highway=trunk & oneway=yes [0x123 road_class=3 road_speed=5 resolution 16]
In the overlays file:
0x123: 0x02, 0x23
Then set the TYP file contain arrows for code 0x23.
Note that only the first way in the overlays file is routeable.
map-features.csv
Note: As of r2636, map-features.csv is no longer supported by mkgmap.
For backward compatibility this file is exactly the same as the file that previously used to hold the styling rules. New styles shouldn't use this file. See the old mkgmap style customisation page for details of the contents of this file.
point|amenity|bank|0x2f|0x06|21 # is exactly the same as the rule in the points file: amenity=bank [0x2f06 resolution 21]
If you have both the new points, lines and polygons files and a map-features file, then the new files will be read first and will override anything in the map-features.csv file that they conflict with.
Testing a style
You can test your style by calling mkgmap with the --style-file=path-to-style and the --list-styles option. If you see your style listed, then your style is recognized by mkgmap. Then you can test if your style is valid by using it when creating a map.
Packaging a style
A style can be used just as it was created, but if you want to make it available to others it will be easier if you make a zip file out of it and then you just have the one file to distribute. You just can zip all files of the style. Several different styles can be placed into the same zip archive file.
To use a zipped style, you can use --style-file=stylename.zip. If there is more than one style in the zip file, then you can use --style-file=zipname.zip --style=stylename.