Defines how map text labels will be constructed. Text is rendered using the text symbol.

Label Definitions

The text uses a label definition syntax. A label consists of one or more label parts. A label part can be one of the following things:

If you specify two or more label parts then Maperitive will merge them together into a single label. Let's look at an example label definition:

text : name " (" ele ")"

specifies a label which will display object's name and elevation (in brackets), for example:

Mt. Everest (8848)

Literal Text

Anything you enter in quoted text will be displayed literally in the label. In the above example, we specified opening and closing brackets as literals: " (" ")" (notice that we inserted a space character before the opening bracket to separate it from any preceding text).

If you want to break the label into several lines of text, you can use the newline symbol "\n", example:

text : name "\n" ele

will display the name and the elevation each in its own line.

Tag References

If you want your text label to display a value of some object tag, you simply specify that tag's name as part of the label definition:

text : name

If the tag's name contains special characters, you need to surround it with double square brackets, like

text : [[name:en]]

If the object does not have the specified tag, this label part will be left empty when Maperitive generates the actual label.


Maperitive provides a set of functions which can be used for more advanced labeling techniques. The functions are described in the following subsections.

@low() Function

Converts the label text to lowercase.


@low(<label definition>)


@low(name "ele")

@up() Function

Converts the label text to uppercase.


@up(<label definition>)


@up(name "ele")

@if() Function

Performs conditional logic based on the existence (or non-existence) of a tag.


@if(<tag reference>, <positive label definition>)


@if(<tag reference>, <positive label definition>, <negative label definition>)


@if(ele, ele "m")

will display the elevation and the literal "m" if the tag ele exists. Otherwise it will not display anything.

@if(ele, ele "m", "-")

will display the elevation and the literal "m" if the tag ele exists. If the tag does not exist, it will display a minus sign.

@if(name, name @if(ele, "\n(" ele ")"), ele)

Displays object name and elevation. Depending on the existence of the name and ele tags, several different labels can be produced:

Mt. Everest


Mt. Everest



@any() Function

Chooses the first available tag among the list of tags.


@any(<tag reference 1>, <tag reference 2>, <tag reference 3>, ... <tag reference N>)


@any([[name:fr]], name)

will tell Maperitive to use French names (name:fr tag) by default, but if the French name is not specified, the rendering will "fall back" to international names (name tag). You can specify as many fallback tags as you like - they will be processed in the decreasing order of priority.

@elevation() Function

Displays the elevation in meters or feet, depending on the user.use-metric setting.


@elevation(<tag reference>)

The tag reference should point to a tag which contains the elevation. If this tag does not exist or cannot be interpreted as a numeric value, nothing will be displayed.

The elevation will be rounded to the nearest integer value.

If you want to force displaying of meters or feet as elevation units, you can specify the user.use-metric setting value inside the rules file, just like any other rendering property, for example:

	user.use-metric : false

Otherwise Maperitive will use the setting's value defined in user's settings.

See also: