Subversion Repositories mkgmap

{|
|-
| style="padding: 5px 50px" | ''Under construction, the new style features are under development and this documentation may not be completely aligned with the implementation''
|}

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.

==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. ''TODO: link to example template''

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 and 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
several 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
things that are read first take priority of things read later.

===version===
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===
This optional file, can contain a short description of the style and other
information such as the author etc.

===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 <tt>name-tag-list</tt> and <tt>levels</tt>.

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.

 levels=0:23, 1:21, 2:19

===points===
This contains a set of rules that show how to convert nodes to garmin
POIs.
See the [[Mkgmap/help/style_rules style rules page]] for complete details
of how this file works.

===lines===
This is the same as the points file, except that it deals with OSM ways
that are meant to be lines.
See the [[Mkgmap/help/style_rules style rules page]] for complete details
of how this file works.

===polygons===
This is the same as the points file, except that it deals with OSM ways
that are meant to be areas.
See the [[Mkgmap/help/style_rules style rules page]] for complete details
of how this file works.

===map-features.csv===
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/help/custom|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
<code>--style-file</code> argument and the name of the directory or
folder that contains the style.

 ... --style-file=path-to-style ...

==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.

Several different styles can be placed into the same zip archive file.