DE:Mkgmap/help/style rules
Regeln ermöglichen, die Merkmale einer OSM-Karte, die durch einen Satz von TAGs beschrieben werden, in das Format der GARMIN-Karten zu überführen, in dem alle Merkmale mittels einer Nummer eindeutig gekennzeichnet sind.
Die Regeln wie Punkte, Linien und Polygone konvertiert werden stehen in Dateien, die nach den Regeln benannt sind. Dies ist in custom styles beschrieben.
Jede Datei enthält mehrere Regeln die die Werte von Tags eines OSM-Knoten oder -Weges prüfen und abhängig von dem Ergebnis den Garmin-spezifischen Style dem Knoten oder Weg zuordnen.
Siehe hierzu auch: style examples.
--- Rest kommt noch ---
Einfaches Beispiel
In the majority of cases everything is very simple. Say you want roads that are tagged as highway=motorway to have the Garmin type 0x01 ("motorway") and for it to appear up until the zoom level 3.
Then you would write the following rule.
highway=motorway [0x01 level 3]
Nodes that have an id and a subid are referenced by concatenating both ids.
amenity=bank [0x2f06 level 3]
This will be explained in more detail in the following sections along with how to use more than one tag to make the choice. However with that one form of rule, you can do everything that the old map-features file could do.
More detail
A rule is made up of two parts. The first part is a set of tests that are performed on the tags of the item to be converted. The second part is the Garmin type that will used if the tests match and associated details. This part is contained in square brackets [...].
As a general point, space and newlines don't matter. There is no need to have rules all on the same line (although I will present most of the examples in that way), and you can spread them out over several lines and add extra spaces where ever you like.
Tag tests
The main test is that a particular tag exists and has a given value. So in the example above we had:
highway=motorway
This means that we look up the highway tag and if it exists and has the value 'motorway' then this test has matched.
You can also compare numeric quantities:
population > 10000
maxspeed >= 30
population < 10000000
This means a population greater than ten thousand, a max speed greater than or equal to 30 and a population less than one million respectively. You will be able to compare quantities that have units too, for example
max_speed > 30mph
If a different unit is given in the tag (say km/h) then conversion will be performed. This is not implemented at the time of writing, so please let me know real useful cases that you come across that you would like to work.
You may also use regular expressions:
ele ~ '\d*00'
This checks whether ele is a multiple of 100.
Combining tag tests
Although it is possible to convert most OSM nodes and ways just using one tag, it is occasionally necessary to use more than one. For special purpose maps it is more likely that you will need to look at more than one tag too.
For example, say you want to take roads that are tagged both as highway=unclassified abutters=residential differently than roads that just have a plain highway=unclassified, you might have the following rules:
highway=unclassified & abutters=residential [0x06] highway=unclassified [0x05]
This means that roads that have both tags would have Garmin element type of 6, whereas unclassified roads without would have the type 5.
It is important to note that the order is important here. The rules are matched in the order that they occur and stop at the first one that matches. If you had them in the other order, then the highway=unclassified rule would match both cases. In general you want the most specific rules first and simpler, more general rules later on to catch the cases that are not caught by the more complex rules.
You can also combine alternatives into the one rule. For example
highway=footway | highway=path [0x7]
This means if the road has either the highway=footway tag or the highway=path tags (or both), then the condition matches and it would be represented with type 0x07. It is exactly the same in behaviour and speed as writing the two rules, one for footway and one for path and is converted to those two rules internally.
You are not limited to two tests and you can combine and group them almost in whatever way you like (with one exception, see below). So for a slightly forced example the following would be possible:
place=town & (population > 1000000 | capital=true) | place=city
This would match if there was a place tag with the value city, or if place had the value town and either the population was over a million or it was tagged a capital.
Important note
You must start each test with a simple test for tag equality. It may be possible in future that this restriction will be relaxed, although it is likely to be slower if you make use of it.
Additional tests
To wrap up this section here are the other available tests.
highway!=motorway This will be true when the highway tag exists, but it does NOT have the value motorway.
highway=* This will be true when the highway tag exists on the element. It doesn't matter what the value is. This is especially useful for tags where it is just their presence that matters.
highway!=* This is true when there is no highway tag.
Element type definition
As noted above this is contained in square brackets.
The first thing must be the element type and this is the only thing that is required to be there. Following the type you can have a number of optional keywords and values.
level
This is the highest zoom level that this element should appear at (like EndLevel in the mp format). If this is not given then it defaults to 0 and so the feature will only appear at the most detailed level. You can also give a range 1-3 and it will appear between those levels (not implemented at the time of writing).
resolution
This is an alternative way of specifying the level. It is the number from 0-24 which corresponds to one of the zoom levels that the hardware recognises. You should not use this if you have given the level and it is usually simpler to use 'level'.
default_name
If you give this, then if the element does not already have a name, then it will be given this name. This might be useful for things that usually don't have names and don't have a recognisable separate Garmin symbol. You could give a default name of 'bus stop' for example and all bus stops that didn't have their own name would now be labeled as such.
road_class
Used for routing; gives the class of the road where 4 is the best roads eg. motorways and 0 are residential roads etc. The classes are used as follows:
| Class | Used as |
|---|---|
| 4 | Major HW/Ramp |
| 3 | Principal HW |
| 2 | Arterial St / Other HW |
| 1 | Roundabout / Collector |
| 0 | Residential Street / Unpaved road / Trail |
road_speed
Used for routing; an indication of how fast traffic on the road is. 0 is the slowest and 7 the fastest. The speed limits that Garmin knows are shown in the following table:
| road_speed | highest speed |
|---|---|
| 7 | No speed limit |
| 6 | 70 mph / 110 kmh |
| 5 | 60 mph / 90 kmh |
| 4 | 50 mph / 80 kmh |
| 3 | 35 mph / 60 kmh |
| 2 | 25 mph / 40 kmh |
| 1 | 15 mph / 20 kmh |
| 0 | 3 mph / 5 kmh |
Example of a full element type definition:
[0x2 road_class=3 road_speed=5 level 2]
Action block
An action block is enclosed in braces {...} and contains a number of statements that can alter the element being displayed; all statements are seperated by ;. When there is an action block, the element type definition is optional, but if it occurs it comes after the action block.
name
This sets the final name of the element, that is the name that will be used on the map. It is distinct from any 'name' tag on the element. You can give a list of alternatives separated by '|' pipe symbols. This first alternative that matches will be used. Once the name is set it cannot be overridden, so if more than one 'name' command matches then only the first to set the name will take effect.
Tags can be used in the value by using the notation: ${tagname}.
Example for roads we do this:
{name '${name} (${ref})' | '${ref}' | '${name}';}
This means that if name='Main St' and ref=A1 the name would be "Main St (A1)", but if there was no 'name' tag then the result would be just "A1". If the name tag was set and not the ref tag, then the element-name would just be the value of the name tag. This emulates the historical behaviour of mkgmap.
For highway shields, you can use the notation ${tagname|highway-symbol:box}. Valid symbols are interstate, shield, round, hbox, box and oval. (latest code from svn only)
add
The add command adds a tag if it does not already exist. The only tag where this is directly useful is the 'oneway' or 'name' tags. For example make motorways oneway unless the oneway tag is set:
highway=motorway { add oneway=yes }
The other use is in in relations with the 'apply' command.
All the same you can set any tag you want, it might be useful so you can match on it elsewhere in the rules.
You can also use substitutions.
{set name='${ele}'; set name='${ref}';}
These two commands would set the 'name' tag to the value of the 'ele' tag if it exists, or to the value of the 'ref' tag if that exists.
set
The 'set' command is just like the 'add' command, except that it sets the tag, even if the tag already exists.
apply
The apply command only makes sense in relations. Say you have a relation marking a bus route but none of the ways that are in the relation have any special tags to indicate that it is a bus route. You want to display the bus route specially. You might write a rule in the relations file such as:
type=route & route=bus {
apply {
set route=bus;
set route_ref='${route_ref}';
}
}
Then in the lines file you can write a rule to match on 'route=bus. All the relation rules are run before any others so that this works.
The substitution '${route_ref}' takes the value of the tag on the relation and applies it to each of the ways in the relation.
Troubleshooting
For each node/way/relation, mkgmap goes through the tags exactly once and finds the earliest rule that matches. Rules with actions have the actions run when seen.
- Where possible always have the same tag on the left. This will make things more predictable.
- Always set made-up tag names if you want to also match on them later, rather than setting tags that might be used already.
Note on backward compatibility
If you convert an old map-features.csv file to the new style-rules files then you will get exactly the same output as you did with the old map-features file and it will run at the same speed. There is a script for doing this called new_style.py in the scripts directory (requires python to run).
The following two sets of examples show how the map-features lines can be converted into identical rules.
OLD: point|amenity|bank|0x2f|0x06|21 NEW: amenity=bank [0x2f06 resolution 21] OLD: polyline|highway|primary|0x04||19 NEW: highway=primary [0x04 resolution 19]
If you have both a map-features.csv file and the points, lines, polygons rule files, then the result is exactly the same as if you wrote the corresponding rules for each line in map-features as above and appended to the bottom of the rule files.