Mkgmap/dev/option-review

From OpenStreetMap Wiki
< Mkgmap‎ | dev
Jump to: navigation, search

Option review

There is a perception (which I agree with) that there are too many options to mkgmap and/or that they are confusing.

One solution to this is to divide clearly the options in the documentation into ones that you are likely to need straight away and those that are only useful for published maps or in rare cases. This is an important part of the solution but it is not discussed further here.

The other part of the solution is to have more generally useful defaults, remove options that are not really useful and to rename or combine options to better describe their use.

This page lists all the current options, and my thoughts on what should be done for each one.

I don't expect anyone to agree with all these.

There is not going to be any massive overnight changes, but I want to approach one option at a time and start removing obsolete options and adding a few defaults, rather than waiting for a big plan.

Option classification

The options are classified according to why they exist. Don't worry too much if you disagree with any of the classifications as is just an aid to thinking about what to do and many could be said to be in more than one category.

1 non-optional
shouldn't even be an option because there is only one setting that works. Perhaps had some genuine use in the past. Basically these should be removed.
2 workaround
automatic algorithm fails and needs human help depending on the map. Might be a quick fix to something that could be done better in the future. If there already is a better solution, then such an option could be considered for removal.
3 style
This is meant to cover anything that affects the look or performance of the map which is not a matter of broken or working. Should have reasonable default values, so that they only need changing in rare cases.
4 information
add information to the map (eg --family-id). Mostly these should stay, although combining them could be considered.
5 output
select what is created. Mostly should be kept, although could be combined, defaulted or renamed.
6 performance
control operations with a large performance impact (time or memory) that is likely to make it impossible for some people to use the program. This is not meant to include anything that produces a broken map if omitted.
7 warnings
control warnings about the input osm files. Will probably combine all these into a --warnings option.
8 generate
generate extra elements based on the input data. Consider each one separately.
9 obsolete
Just not needed any more, or doesn't work. Remove.
10 random
supports some random thing that someone wanted to do once. See if it is still needed or just do it and remove the option.
11 input
selecting input files. Mostly can't avoid this but could consider combining options perhaps.
12 informational
produces some informational output, eg --help etc

The options

Option Class Notes Action
--help=topic 12 informational keep
--version 12 informational keep
--input-file=filename 11 input keep
--gmapsupp 5 output Create map for GPS device. Not an obvious name to anyone new to Garmin devices. Possibly rename to --gps (and --desktop) or --output=[gps,desktop]
-c filename, --read-config=filename 11 input keep
--output-dir=filename 5 output keep
-n name, --mapname=name 4 information keep
--description=text 4 information keep
--country-name=name 4 information perhaps all these country/region parameters could be combined

somehow?

keep
--country-abbr=abbreviation 4 information keep
--region-name=name 4 information keep, perhaps combine
--region-abbr=abbreviation 4 information keep, perhaps combine
--latin1, --unicode, --code-page=number 4 information defaults to ascii only, should default to 1252, I know that is

western european centric, but the current default is less useful.

default to 1252
--charset=name 9 obsolete this was from before I understood the character set options. remove+code
--lower-case 1 non-optional I only put this in to show that it doesn't work (for all devices).

Now all that happens is that people write to me complaining that it doesn't work.

remove+code
--index 5 output requires a significant amount of memory for large maps. keep or default on?
--x-split-name-index 5 output still experimental? keep or default on?
--createboundsfile=filename 11 input a separate mode of operation, reuse another option? replaced by separate program (r2426)
--bounds=directory/zipfile 11 input keep
--location-autofill=[option1,[option2]] 2 workaround investigate how useful this still is. Basically obsoleted by bounds?
--housenumbers 5 output default on
--style=name 11 input keep
--style-file=file 11 input keep
--list-styles 12 informational keep
--check-styles 12 informational keep
--levels=levels code, --overview-levels=levels code 3 style this really lives inside the style. Changing it without modifying the style leads to unbalanced results. remove?, style-option
--name-tag-list 3 style a style option, that can be overriden from the command line. keep
--map-features=file 9 obsolete This was the first style file format, not useful today. remove+code
--family-id 4 information keep
--family-name 4 information keep
--product-id 4 information keep
--product-version 4 information keep
--series-name 4 information keep
--area-name 4 information keep
--overview-mapname=name 4 information keep
--overview-mapnumber=8 digit number 4 information keep
--remove-ovm-work-files 6 performance keep
--copyright-message=note 4 information keep
--copyright-file=file 4 information keep
--license-file=file 4 information keep
--reduce-point-density=NUM 3 style default to a reasonable value
--reduce-point-density-polygon=NUM 3 style default to a reasonable value
--merge-lines 3 style investigate if this works safely, enable always if so. Else fix or

remove if we can't do that (may need a different approach).

default on, or remove
--min-size-polygon=NUM 3 style default to a reasonable value.
--polygon-size-limits=limits code 3 style default to a reasonable value.
--max-jobs[=number] 6 performance keep
--keep-going 12 informational Would be clearer if it was called --ignore-errors rename?
--block-size=number 11 output, 9 obsolete Now automatic calculation works. remove
--net 5 output default to on
--route 5 output default to on
--drive-on=left/right/detect/detect,left/detect,right 3 style keep
--check-roundabouts 7 warnings, and modifies the data undecided. I think perhaps it should become just a warning.
--check-roundabout-flares 7 warnings combine into --warnings
--max-flare-length-ratio=NUM 10 random, 7 warnings do we really need this? remove
--ignore-maxspeeds 3 style belongs in the style , see include roadspeed already ignored
--ignore-builtin-relations 10 random, 1 non-optional claims performance benefit, but only if you want a broken map. remove
--ignore-turn-restrictions 1 non-optional or 2 workaround don't know why you would want to do this remove
--ignore-osm-bounds 1 non-optional, 2 workaround breaks routing across tiles, was a quick fix for files that have multiple bounds. The correct solution is for mkgmap to just deal with multiple bounds. remove (and fix properly)
--preserve-element-order 10 random added for a particular application. Perhaps should just be made default, it only uses a small amount of extra memory (if any) and is quite useful when tracking down problems. default on, and remove
--remove-short-arcs[=MinLength] 1 non-optional obsolete already ignored
--adjust-turn-headings[=BITMASK] 2 workaround or 1 non-optional makes turn directions better. Investigate if it works well, if so default on and improve as necessary.

Otherwise remove.

default on, or remove
--report-similar-arcs 7 warnings not a particularly useful warning? combine in --warnings
--report-dead-ends=LEVEL 7 warnings combine in --warnings
--road-name-pois[=GarminCode] 9 obsolete, a work around from before we had address index, now more trouble than it is worth. ignored since r3605
--add-pois-to-lines 8 generate should be handled with care, is likely to produce a large number

of POI, style should check mkgmap:line2poitype tag in points file.

limit number of generated POI?
--add-pois-to-areas 8 generate always need to do this, controlled by style? or should be. default on
--pois-to-areas-placement[=taglist] 3 style seems like it should be controlled in the style move to style
--precomp-sea=directory/zipfile 11 input keep
--coastlinefile=filename[,filename] 11 input is this obsolete with --precomp-sea? anyway only need one way to get

sea polygons. Or have one option that works out what kind of file it is given and acts accordingly.

 ?
--generate-sea[=ValueList] 8 generate this itself has a whole slew of sub-options. Is this obsolete with --precom-sea? Only need one way to create the sea.
--make-poi-index 5 output, 1 non-optional Doesn't work? If it works enable and remove the option, else remove the code. remove
--nsis 5 output default on, not really much point in not creating this file. Could combine as --desktop or --output=desktop default on
--make-all-cycleways 8 generate depreacated, treated like --make-opposite-cycleways keep with warning
--make-opposite-cycleways 8 generate better solutions using the style file, but not simple keep
--make-cycleways 8 generate already ignored
--link-pois-to-ways 1 non-optional implements access restrictions default on and remove
--process-destination, --process-exits 3 style seems like it should always be done. Or controlled by style. default on and remove
--delete-tags-file=FILENAME 11 input keep?
--tdbfile 5 output annoyingly it defaults to on but only if there is more than one file.

may as well always produce these files. remove or perhaps control with --desktop

default to on.
--show-profiles=1 5 output perhaps could be a style option keep
--draw-priority=25 5 output keep
--transparent 5 output keep
--poi-address 1 non-optional or 3 style not even sure why this is a thing, default is on now remove?
--verbose 12 informational keep