logo separator

List of options

Note that option order is significant: An option only applies to subsequent input files. So if you are using splitter, you probably want to put most of your options before '-c template.args'.

General options

Print help on the given topic. If the topic is omitted then a list of all the help topics is printed instead.
Output program version to stderr.

File options

Read input data from the give file. This option (or just a filename) may be given more than once. Make sure to set all wanted options before using this.
Create a gmapsupp.img file that can be uploaded to a Garmin or placed in "/Garmin" in a microSD card (such as by mounting the device in USB mass storage mode). It can be used on ready compiled img files, if the input files are not already compiled then they are compiled first and then the gmapsupp is created.
-c filename
The given file is opened and each line is an option setting of the form option=value, any option that could be used on the command line can be used, however you omit the leading '--'. The short option names with a single '-' cannot be used, simply use the long name instead.

The directory in which all output files are written. It defaults to the current working directory, i.e. the directory the command is executed from.

-n name
Set the name of the map. Garmin maps are named by 8 digit numbersList. The default is 63240001. It is best to use a different 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.

Sets the descriptive text for the map. This may be displayed in QLandkarte, MapSource or on a GPS, where it is normally shown below the family name. Example: --description="Germany, Denmark" Please note: if you use splitter.jar to build a template.args file and use -c template.args, then that file may contain a "description" that will override this option for each single tile. Make sure to set the description for the gmapsupp.img after "-c template.args".

Sets the map's country name. The default is "COUNTRY".

Sets the map's abbreviated country name. The default is "ABC".

Sets the map's region name. By default, the map has no region name.

Sets the map's abbreviated region name. By default, the map has no abbreviated region name.

Label options

This is equivalent to --code-page=1252.

This is equivalent to --code-page=65001. Note that some devices don't support unicode maps produced by mkgmap.

This option enables the use of international characters. Only 8 bit character sets are supported and so you have to specify which code page you want to use.

It is entirely dependent on the device firmware which code pages are supported.

This option is obsolete. Change the character set with the --code-page option.

Allow labels to contain lower case letters. Note that most or all Garmin devices are not able to display lower case letters at an angle so this option is not generally useful.

Address search options

Generate a global address search index. If the --gmapsupp option is also given, then the index is generated within the resulting gmapsupp.img file so that address search will work on a GPS device.

If instead the --tdbfile option is given then the index consists of two files named osmmap.mdx and osmmap_mdr.img which can be used with MapSource. (For compatibility, you do not need the tdbfile option if gmapsupp is not given).

If both the --gmapsupp and --tdbfile options are given alongside the --index option, then both indexes will be created. Note that this will require roughly twice as much memory.

The --overview-mapname option can be used to change these names. If the mapset is sent to the device from MapSource, it will enable find by name and address search on the GPS.

The address fields are assigned by special mkgmap address tags using the style file:
 (mkgmap:is_in - used by location-autofill=is_in)

If the index is created from previously compiled .img files, then the same code page and sorting options (e.g. --code-page, --latin1) must be used as were used to compile the individual map tiles.
An option to enable indexing each part of a street name separately. So for example if the street is "Aleksandra Gryglewskiego" then you will be able to search for it as both "Aleksandra" and "Gryglewskiego". It will also increase the size of the index. Useful in countries where searching for the first word in name is not the right thing to do. Words following an opening bracket '(' are ignored. See also option road-name-config.

This option handles the problem that some countries have road names which often start or end with very similar words, e.g. in France the first word is very often 'Rue', often followed by a preposition like 'de la' or 'des'. This leads to rather long road names like 'Rue de la Concorde' where only the word 'Concorde' is really interesting. In the USA, you often have names like 'West Main Street' where only the word 'Main' is important. Garmin software has some tricks to handle this problem. It allows to use special characters in the road labels which mark the beginning and end of the important part. In combinarion with option split-name-index only the words in the important part are indexed.

There are two different visiual effects of this option:
- On the PC, when zooming out, the name 'Rue de la Concorde' is only rendered as 'Concorde'.
- The index for road names only contains the important part of the name. You can search for road name Conc to find road names like 'Rue de la Concorde'. One problem: Search for 'Rue' will not list 'Rue de la Concorde' or 'Rue du Moulin'. It may list 'Rueben Brookins Road' if that is in the map. Only MapSource shows a corresponding hint.

Another effect is that the index is smaller.
The option specifies the path to a file which gives the details. See comments in the sample roadNameConfig.txt for further details.

This option allows to specify words which should not be in the road index. It was added before option road-name-config and is probably no longer needed.
Example usage: --x-mdr7-excl="Road, Street, Stra├če, Weg"

Use this option if your style adds strings to the labels of roads which you want to see in the map but which should not appear in the result list of a road name / address search. The list is used like this: For each road label mkgmap searches the last blank. If one is found, it checks if the word after it appears in the given list. If so, the word is removed and the search is repeated. The remaining string is used to create the index.
Example: Assume your style adds surface attributes like 'pav.' or 'unp.' to a road label. You can use --mdr7-del="pav.,unp." to remove these apendixes from the index.

By default, mkgmap indexes the following POI types with a non-empty label:
- 0x00 .. 0x0f (cities, sub type 0, type <= 0xf)
- 0x2axx..0x30xx (Food & Drink, Lodging, ...)
- 0x28xx (no category ?)
- 0x64xx .. 0x66xx (attractions)
This option allows to exclude POI types from the index. The exclueded types are not indexed, but may still be searchable on a device as some devices seem to ignore most of the index, e.g. an Oregon 600 with firmware 5.00 only seems to use it for city search. If you device finds a POI name like 'Planet' when you search for 'Net' it doesn't use the index because the index created by mkgmap cannot help for that search.

So, this option may help when you care about the size of the index or the memory that is needed to calculate it. The option expects a comma separated list of types or type ranges. A range is given with from-type-to-type, e.g. 0x6400-0x6405. First and last type are both excluded.A range can span multiple types, e.g. 0x6400-0x661f.
Examples for usage:
- Assume your style adds a POI with type 0x2800 for each addr:housenumber. It is not useful to index those numbers, so you can use --poi-excl-index=0x2800 to exclude this.
- For the mentioned Oregon you may use --poi-excl-index=0x2a00-0x661f to reduce the index size.

A directory or a zip file containing the preprocessed bounds files. Bounds files in a zip file must be located in the zip file's root directory.

The preprocessed boundaries are used to add special tags to all elements (points, lines and polygons) containing the elements location information. The style file can be used to assign the address tags mkgmap:country, mkgmap:region etc. using these values.

The following special tags are added:

  mkgmap:admin_level2 : Name of the admin_level=2 boundary 
  mkgmap:admin_level3 : Name of the admin_level=3 boundary
  mkgmap:postcode : the postal_code value
Preprocessed bounds can be created with the following command:
   java -cp mkgmap.jar 
      <inputfile> <boundsdir>
The input file must contain the boundaries that should be preprocessed. It can have OSM, PBF or O5M file format. It is recommended that it contains the boundary data only to avoid very high memory usage. The boundsdir gives the directory where the processed files are stored. This directory can be used as --bounds parameter with mkgmap.

Controls how the address fields for country, region, city and zip info are gathered automatically if the fields are not set by using the special mkgmap address tags (e.g. mkgmap:city - see option index). Warning: automatic assignment of address fields is somehow a best guess.
The is_in tag is analyzed for country and region information.

The city/hamlet points that are closest to the element are used to assign the missing address fields. Beware that cities located in the same tile are used only. So the results close to a tile border have less quality.
Enables house number search for OSM input files. All nodes and polygons having addr:housenumber set are matched to streets. A match between a house number element and a street is created if the street is located within a radius of 150m and the addr:street tag value of the house number element equals the mgkmap:street tag value of the street. The mkgmap:street tag must be added to the street in the style file. For optimal results, the tags mkgmap:city and mkgmap:postal_code should be set for the housenumber element. If a street connects two or more cities this allows to find all addresses along the road, even they have the same number.
Example for given street name:
Node - addr:street=Main Street addr:housenumber=2
Way 1 - name=Main Street
Way 2 - name=Main Street, mkgmap:street=Main Street
Way 3 - mkgmap:street=Mainstreet
Way 4 - name=Main Street [A504]
The node matches to Way 2. It has mkgmap:street set with a value equal to the addr:street tag value of the house number node.

If the street is not given with addr:housenumber, mkgmap uses heuristics to find the best match.

Overview map options

If --tdbfile is enabled, this gives the name of the overview .img and .tdb files. The default map name is osmmap.

--overview-mapnumber=8 digit number
If --tdbfile is enabled, this gives the internal 8 digit number used in the overview map and tdb file. The default number is 63240000.

like levels, specifies additional levels that are to be written to the overview map. Counting of the levels should continue. Up to 8 additional levels may be specified, but the lowest usable resolution with MapSource seems to be 11. The hard coded default is empty.

If overview-levels is used, mkgmap creates one additional file with the prefix ovm_ for each map (*.img) file. These files are used to create the overview map. With option --remove-ovm-work-files=true the files are removed after the overview map was created. The default is to keep the files.

Style options

Specify an external file to obtain the style from. "file" can be a directory containing files such as info, lines, options (see resources/styles/default for an example). The directory path must be absolute or relative to the current working directory when mkgmap is invoked.

The file can be a zip file containing the files instead of a directory.

The files can be at the top level or contained in a folder within the zip file. If the zip file contains more than one top level folder then each folder is the name of a style that can be selected with the --style option.

The argument can also be a URL that specifies the location of a style file.

Specify a style name. Must be used if --style-file points to a directory or zip file containing multiple styles. If --style-file is not used, it selects one of the built-in styles.

Provide a semicolon separated list of tags which can be used in the style. The intended use is to make a single style more flexible, e.g. you may want to use a slightly different set of rules for a map of a whole continent. The tags given will be prefixed with "mkgmap:option:". If no value is provided the default "true" is used. This option allows to use rules like mkgmap:option:light=true & landuse=farmland {remove landuse} Example: -- style-option=light;routing=car will add the tags mkgmap:option:light=true and mkgmap:option:routing=car to each element before style processing happens.

List the available styles. If this option is preceded by a style-file option then it lists the styles available within that file.

Perform some checks on the available styles. If this option is preceded by a style-file option then it checks the styles available within that file. If it is also preceded by the style option it will only check that style.

--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: "0:24, 1:22, 2:20, 3:18, 4:16", although each style can have its own default. Up to 8 levels may be specified.

Get the tag that will be used to supply the name. Useful for language variations. You can supply a list and the first one will be used. e.g. --name-tag-list=name:en,int_name,name

This option is ignored; use the --style-file option instead.

Product description options

This is an integer that identifies a family of products. Range: [1..9999] Mkgmap default: 6324

If you build several maps, this option describes the family name of all of your maps. Garmin will display this in the map selection screen.

Example: --family-name="OpenStreetmap mkgmap XL 2019"

This is an integer that identifies a product within a family. It is often just 1, which is the default.

The version of the product. Default value is 100 which means version 1.00.

This name will be displayed in MapSource in the map selection drop-down. The default is "OSM map".

Area name is displayed on Garmin units (or at least on eTrex) as the second part of the mapname in the list of the individual maps.

Specify a copyright message for files that do not contain one.

Specify copyright messages from a file. Note that the first copyright message is not displayed on a device, but is shown in BaseCamp. The copyright file must include at least two lines and be UTF-8 encoded. The following symbols will be substituted by mkgmap: $MKGMAP_VERSION$, $JAVA_VERSION$, $YEAR$, $LONG_DATE$, $SHORT_DATE$ and $TIME$. Time and date substitutions use the local date and time formats.

Specify a file which content will be added as license. The license file must be UTF-8 encoded. The following symbols will be substituted by mkgmap: $MKGMAP_VERSION$, $JAVA_VERSION$, $YEAR$, $LONG_DATE$, $SHORT_DATE$ and $TIME$. Time and date substitutions use the local date and time formats. All entries of all maps will be merged in the overview map.

Optimization options

Simplifies the ways with the Douglas Peucker algorithm. NUM is the maximal allowed error distance, by which the resulting way may differ from the original one. This distance gets shifted with lower zoom levels. Recommended setting is 4, this should lead to only small differences (Default is 2.6, which should lead to invisible changes)

Allows to set the maximal allowed error distance for the DP algorithm to be applied against polygons. Recommended setting is 8.

Try to merge lines. This helps the simplify filter to straighten out longer chunks at lower zoom levels. Decreases file size more. Increases paint speed at low zoom levels. Default is enabled, use --no-merge-lines to disable.

Removes all polygons smaller than NUM from the map. This reduces map size and speeds up redrawing of maps. Recommended value is 8 to 15, default is 8. See also polygon-size-limits.

--polygon-size-limits=limits code
Allows to specify different min-size-polygon values for each resolution. Sample: --polygon-size-limits="24:12, 18:10, 16:8, 14:4, 12:2, 11:0" If a resolution is not given, mkgmap uses the value for the next higher one. For the given sample, resolutions 19 to 24 will use value 12, resolution 17 and 18 will use 10, and so on. Value 0 means to skip the size filter. Note that in resolution 24 the filter is not used.

Miscellaneous options

When number is specified, allow that number of maps to be processed concurrently. If number is not specified, the limit is set equal to the number of CPU cores. If this option is not given at all, the limit is 1 (i.e., the maps are processed sequentially).

Don't quit whole application if an exception occurs while processing a map - continue to process the other maps.

Changes the block size that is used in the generated map. This option is not usually needed, but sometimes an error message will ask you to try a value for this option.

Obsolete, use --route instead.

Create maps that support routing.

Explicitly specify which side of the road vehicles are expected to drive on. If the first option is detect, the program tries to find out the proper flag. If that detection fails, the second value is used (or right if none is given). With OSM data as input, the detection tries to find out the country each road is in and compares the number of drive-on-left roads with the rest. Use the --bounds option to make sure that the detection finds the correct country.

Deprecated: Use drive-on instead. The options are translated to drive-on=left|right.

Check that roundabouts have the expected direction (clockwise when vehicles drive on the left). Roundabouts that are complete loops and have the wrong direction are reversed. Also checks that the roundabouts do not fork or overlap other roundabouts and that no more than one connecting highway joins at each node.

Sanity check roundabout flare roads - warn if they don't point in the correct direction or if they are not one-way or if they extend too far.

When checking flare roads, ignore roads whose length is greater than NUM (an integer) times the distance between the nodes on the roundabout that the flare roads connect to. Using this option with a value of at least 5 will cut down the number of legitimate roads that are flagged as flare road problems. Default value is 0 (disabled) because it's not a completely reliable heuristic.

Now ignored, former usage: When reading OSM files, ignore any "maxspeed" tags.

Now ignored, former usage: When reading OSM files, skip the built-in processing of relations. This speeds up the processing non-routable map layers that do not contain multipolygons. This implies --ignore-turn-restrictions.

When reading OSM files, ignore any "restriction" relations.

When reading OSM files, ignore any "bounds" elements. With this option selected generate-sea sometimes works better, but routing across tiles will not work.

Process the map elements (nodes, ways, relations) in the order in which they appear in the OSM input. Without this option, the order in which the elements are processed is not defined.

Now ignored, former usage: Merge nodes to remove short arcs that can cause routing problems. If MinLength is specified (in metres), arcs shorter than that length will be removed. If a length is not specified, only zero-length arcs will be removed.

Now ignored, former usage: Where possible, ensure that turns off to side roads change heading sufficiently so that the GPS believes that a turn is required rather than a fork. This also avoids spurious instructions to "keep right/left" when the road doesn't actually fork.

Optional BITMASK (default value 3) allows you to specify which adjustments are to be made (where necessary):

  • 1 = increase angle between side road and outgoing main road
  • 2 = increase angle between side road and incoming main road

Tells mkgmap that the map is for cyclists. This assumes that different vehicles are different kinds of bicycles, e.g. a way with mkgmap:car=yes and mkgmap:bicycle=no may be a road that is good for racing bikes, but not for other cyclists. This allows to optimise sharp angles at junctions of those roads. Don't use with the default style as that is a general style!

Issue a warning when more than one arc connects two nodes and the ways that the arcs are derived from contain identical points. It doesn't make sense to use this option at the same time as using the cycleway creating options.

Set the dead end road warning level. The value of LEVEL (which defaults to 1 if this option is not specified) determines those roads to report: 0 = none, 1 = multiple one-way roads that join together but go nowhere, 2 = individual one-way roads that go nowhere.

Now ignored, former usage: Generate a POI for each named road. By default, the POIs' Garmin type code is 0x640a. If desired, a different type code can be specified with this option. This is a workaround for not being able to search for roads. 0x2f15: a blue dot in the middle of the road, and if you select, or 'hover' over it, the street name appears.
Generate POIs for lines. For each line (must not be closed) POIs are created at several points of the line. Each POI is tagged with the same tags like the line and additional tags added by mkgmap: mkgmap:line2poi=true and tag mkgmap:line2poitype having the following values:
  • start - The first point of the line
  • end - The last point of the line
  • inner - Each point of the line except the first and the last
  • mid - The middle point
Generate a POI for each polygon and multipolygon. The POIs are created after the relation style but before the other styles are applied. Each POI is tagged with the same tags of the area/multipolygon. Additionally the tag mkgmap:area2poi=true is set so that it is possible to use that information in the points style file. Artifical polygons created by multipolyon processing are not used. The POIs are created at the following positions (first rule that applies):
First rule that applies of
  • the first node tagged with a tag defined by the pois-to-areas-placement option
  • the centre point
First rule that applies of
  • the node with role=label
  • the centre point of the biggest area
A semicolon separated list of tag=value definitions. A POI is placed at the first node of the polygon tagged with the first tag/value pair. If none of the nodes are tagged with the first tag-value pair the first node tagged with the second tag-value pair is used and so on. If none of the tag-value pairs matches or the taglist is empty the centre of the polygon is used. It is possible to define wildcards for tag values like entrance=*.

Default: entrance=main;entrance=yes;building=entrance

Defines the directory or a zip file that contains precompiled sea tiles. Sea files in a zip file must be located in the zip file's root directory or in a sub directory sea. When this option is defined all natural=coastline tags from the input OSM tiles are removed and the precompiled data is used instead. This option can be combined with the generate-sea options multipolygon, polygons and land-tag. The coastlinefile option is ignored if precomp-sea is set.

Defines a comma separated list of files that contain coastline data. The coastline data from the input files is removed if this option is set. Files must have OSM or PBF fileformat.

Generate sea polygons. ValueList is an optional comma separated list of values:

generate the sea using a multipolygon (the default behaviour so this really doesn't need to be specified).
polygons | no-mp
don't generate the sea using a multipolygon - instead, generate a background sea polygon plus individual land polygons with tag natural=land. This requires a suitable land polygon type to be defined in the style file (suggested type is 0x010100) and the polygon must be defined in the TYP file as having a higher drawing level than the sea polygon type.
disable the generation of "sea sectors" when the coastline fails to reach the tile's boundary.
same as no-sea-sectors. Additional adds a point so coastline reaches the nearest tile boundary.
tag to use for land polygons (default natural=land).
close gaps in coastline that are less than this distance (metres)
enable the flood blocker that prevents a flooding of land by checking if the sea polygons contain streets (works only with multipolygon processing)
flood blocker gap in metre (default 40) points that are closer to the sea polygon do not block
at least so many highway points must be contained in a sea polygon so that it may be removed by the flood blocker (default 20)
only sea polygons with a higher ratio (highway points * 100000 / polygon size) are removed (default 0.5)
switches on the debugging of the flood blocker generates GPX files for each polygon checked by the flood blocker
Generate a POI index in each map tile. Probably not used by modern devices, but still supported.

Write a .nsi file that can be used with the Nullsoft Scriptable Install System (NSIS) to create a Windows Mapsource Installer.

Deprecated, use --make-opposite-cycleways instead. Former meaning:
Turn on all of the options that make cycleways.
Some one-way streets allow bicycle traffic in the reverse direction and this option makes a way with the same points as the original that allows bicycle traffic (in both directions).

Now ignored, former meaning:
Some streets have a separate cycleway track/lane just for bicycle traffic and this option makes a way with the same points as the original that allows bicycle traffic. Also, bicycle traffic is prohibited from using the original way (unless that way's bicycle access has been defined).
This option may copy some specific attributes of a POI to a small part of the way the POI is located on. This can be used to let barriers block a way or to lower the calculated speed around traffic signals. POIs with the tags highway=* (e.g. highway=traffic_signals) or barrier=* (e.g. barrier=cycle_barrier) are supported. The style developer must add at least one of the access tags (mkgmap:foot, mkgmap:car etc.), mkgmap:road-speed and/or mkgmap:road-class to the POI. The access tags are ignored if they have no effect for the way, else a route restriction is added at the POI so that only allowed vehicles are routed through it. The tags mkgmap:road-speed and/or mkgmap:road-class are applied to a small part of the way around the POI, typically to the next junction or a length of ~25 m. The tags are ignored for pedestrian-only ways.

Splits all motorway_link, trunk_link, primary_link, secondary_link, and tertiary_link ways tagged with destination into two or three parts where the second part is additionally tagged with mkgmap:dest_hint=*. The code checks for the tags destination, destination:lanes, destination:street and some variants with :forward/:backward like destination:forward or destination:lanes:backward. If a value for destination is found, the special tag mkgmap:dest_hint is set to it and the way is split. This happens before the style rules are processed. This allows to use any routable Garmin type (except 0x08 and 0x09) for that part so that the Garmin device tells the name of this part as hint which destination to follow. See also --process-exits.

Usual Garmin devices do not tell the name of the exit on motorways while routing with mkgmap created maps. This option splits each motorway_link, trunk_link, primary_link, secondary_link, and tertiary_link way into three parts. All parts are tagged with the original tags of the link. Additionally the middle part is tagged with the following tags:
  mkgmap:exit_hint_ref=<ref tag value of the exit>
  mkgmap:exit_hint_name=<name tag value of the exit>
  mkgmap:exit_hint_exit_to=<exit_to tag value of the exit>
Adding a rule checking the mkgmap:exit_hint=true makes it possible to use any routable Garmin type (except 0x08 and 0x09) for the middle part so that the Garmin device tells the name of this middle part as hint where to leave the motorway/trunk. The first part must have type 0x08 or 0x09 so that Garmin uses the hint.
Names a file that should contain one or more lines of the form TAG=VALUE or TAG=*. Blank lines and lines that start with a # or ; are ignored. All tag/value pairs in the OSM input are compared with these patterns and those that match are deleted.

Tells mkgmap to ignore all tags for which the value matches the pattern "(?i)fix[ _]?+me".

Write files that are essential to running with MapSource, a .tdb file and an overview map.

Sets a flag in tdb file which marks set mapset as having contour lines and allows showing profile in MapSource. Default is 0 which means disabled.

When two maps cover the same area, this option controls what order they are drawn in and therefore which map is on top of which. Higher priorities are drawn "on top" of lower priorities.

Make the map transparent, so that if two maps are loaded that cover the same area, you can see through this map and see the lower map too. Useful for contour line maps among other things.

Write a different TRE header. With this option mkgmap writes the bytes 0x170401 instead of the default 0x110301 at offset 43. Useful for marine maps.

Set a bit in the gmapsupp.img that tells PC software that the file is already installed on the PC and therefore there is no need to read it from the device.

Enable address / phone information to POIs. Address info is read according to the "Karlsruhe" tagging schema. Automatic filling of missing information could be enabled using the "location-autofill" option. Default is enabled, use --no-poi-address to disable.

Makes some operations more verbose. Mostly used with --list-styles.

Puts area/polygons into the mapfile in decreasing size so that smaller features are rendered over larger ones (assuming _drawOrder is equal). The tag mkgmap:drawLevel can be used to override the natural area of a polygon, so forcing changes to the rendering order.

Latest commits

  • display-r503 Start to improve DemDisplay with new knowledge from Frank Stinner.
    18 nov 2017
  • display-r502 Print out any DEM files in the TDB..
    04 nov 2017
  • mkgmap-r3997 merge from branch expr which fixes errors in the style file reader.
    26 sep 2017
  • mkgmap-r3996 add test to avoid rare NPE in HousenumberGenerator.useAddrPlaceTag().
    11 sep 2017
  • mkgmap-r3995 default style: ignore highway=stopline.
    24 aug 2017
See more...