As we explained in the introduction to rendering rules, Maperitive rules work on features. Maperitive provides a simple query language which is used to to specify what a feature represents. Let's look at one simple example of a feature:
street : way [highway=residential]
Here we defined a feature called street which covers OSM ways tagged as highway=residential. The text after the colon (':') is called a spatial specification:
The above spatial specification in consists of two parts:
Maperitive currently supports these targets:
Good question. They are, and they are not - depending on the situation. You don't need to specify the target - in certain situations Maperitive can figure out by itself what you're actually targeting. An example:
features ... areas parking : amenity=parking ...
is perfectly valid and it should work OK within the rules. This is because you specified the parking feature under the areas subsection, so Maperitive knows that it has to look for closed OSM ways. If, on the other hand, you specified it like this:
features ... parking : amenity=parking ...
it means that the parking feature can be targeted to any feature type (point, line and area). In this case the feature will cover both OSM parking nodes and OSM parking areas. But it will also target any non-closed OSM way that has mistakenly been specified as amenity=parking. To avoid this, you can also specify it like this:
features ... parking : node[amenity=parking] area[amenity=parking] ...
As you can see, you can use several spatial specifications for a feature. This way you're telling Maperitive to look both at nodes and areas and the end feature will contain the combination of them.
As their name says, spatial conditions specify what qualities the map elements must satisfy in order to be selected. Typically these qualities are expressed through element tags and their values, for example:
specifies that we are looking for elements which have a tag called amenity and the value of this tag must be parking in order for the element to be selected.
There are several distinct ways a condition can be specified:
Each of these will now be described.
This is a most common scenario: we want to find elements which have a certain tag and value combination. Examples:
highway=motorway name="New York" name:de=Muenchen "strange key"="strange value"
As you can see from examples, you can enclose both the tag name and the tag value within quotes. This is necessary if the tag name or value contains spaces or some special characters which are otherwise reserved for Maperitive's query language.
Let's say you're looking for a restaurant, even if fast-food. Instead of writing a condition like
amenity=restaurant OR amenity=fast_food
you can use the isOneOf function to test the tag against multiple values:
@isOneOf(amenity, restaurant, fast_food)
If you are only interested in whether a certain tag exists (regardless of its value), you simply specify the tag name, for example:
will match any kind of road in the OSM data.
If a tag value represents a numeric value, you can compare against it using the standard comparison operators: >, >=, < and <=. For example
population >= 100000
will match all elements which have a population larger than 100,000. You can of course specify decimal values too:
width > 2.5
Maperitive supports several functions which can be used inside conditions. These functions accept a series of arguments and return result indicating whether the condition was satisfied or not.
USAGE: @isTrue (tag name)
This function checks whether the specified tag contains a Boolean true value. Following conventions in the OSM world, the method will return a successful response if the tag has one of the following values:
If the tag does not exist or the value of the tag is not one of the above, the method returns a negative response.
@isFalse function is the exact opposite to the @isTrue function.
USAGE: @isFalse (tag name)
This function checks whether the specified tag contains a Boolean false value. Following conventions in the OSM world, the method will return a successful response if the tag has one of the following values:
@isTrue function is the exact opposite to the @isFalse function.
USAGE: @isOneOf (tag name, tag value 1, tag value 2, ..., tag value N)
Tests the value of the specified tag against multiple values (specified in function arguments). The function returns a successful response if one of the values is matched. If none of the values matches the tag value, the function returns a negative response.
@isOneOf(highway, motorway, trunk, primary)
USAGE: @isMatch (tag name, regular expression)
Tests the value of the specified tag against the specified regular expression. The function returns a successful response if the value matches the regular expression. Otherwise the function returns a negative response.
matches any element whose name ends with "wald".
USAGE: @isMulti (tag name, multiplier numeric value)
Tests whether the specified tag's numeric value is a multiplier of the second argument value. If an element's tag value cannot be interpreted as a numeric value, the function will return a negative response.
matches any element whose elevation is a multiplier of 100 (100, 200, 300 etc).
Maperitive also supports nested queries like
This query is made out of two spatial specifications:
looks for OSM nodes which represent gate barriers, and
then acts on the results of the first query, so for each of the gate barriers it looks for OSM ways it belongs to and selects only those ways which are tagged as footpaths.
You can do further nesting using the '.' syntax.
In addition to specifying features in rules, you can also use the query language to look for things interactively. This is what the find command and find-here command are for. For example, if you type the following command in the command box:
find way[highway=residential AND NOT name]
...Maperitive will look for unnamed residential streets in any OSM file you've loaded into your current map. If it finds any, it will highlight them on the map. You can then go through the results using the find-next (TODO) and find-prev (TODO) commands.
To illustrate the usage and syntax of the querying language, this section lists some examples of queries.
Finds all ways.
Finds all nodes (be careful with this one on a large OSM area, since there can be a lot of nodes).
area [landuse=forest OR natural=wood]
Finds areas designated as forests.
relation[type=route and route=bicycle and network=icn]
Finds international cycle routes defined as OSM relations.
Finds parking areas, both those designated by OSM nodes and those designated by OSM areas (closed ways).
Finds contours with the elevation which is a multiplier of 50 (50 m, 100 m, 1000 m etc.).
Finds all OSM ways which have the highway tag (regardless of its value).
Opposite case: finds all OSM ways which do not have the highway tag.
way[highway and not name]
Finds all OSM ways which have the highway tag and do not have the name tag.
Finds all OSM nodes which represent a gate barrier and are on the footpaths.
Finds all OSM ways which represent footpaths and which have at least one gate barrier on them.
Finds all points of all GPS tracks.