Kosmos Rendering Help

One of the most interesting features of Kosmos rendering engine is the ability of users to define how maps should be rendered by writing definitions in OpenStreetMap Wiki pages. One example of such a page is Kosmos General Purpose Rules page, which is intended to contain rules for rendering standard maps.

Kosmos will automatically download rendering rules page and parse it. The idea is to "democratize" rendering of OSM data by providing a Wiki mechanism so that many OSM users can contribute their rendering rules. Also, there could be many Wiki pages containing different sets of rendering rules for different types of maps - city maps, hiking maps, driving maps etc. There could even be separate rendering rules pages for displaying on the screen and for printing maps.

You can also save the raw contents of the rendering rules Wiki page into a file and use this file in Kosmos instead (see FAQ).

If you have any questions about using rendering rules, maybe a visit to Kosmos FAQ page will help.

Contents 1 Rules Table(s) 1.1 Child Rules 2 Element Selectors 2.1 Complex Expressions Syntax 3 Templates 3.1 Standard Parameters 3.2 Polyline Template Parameters 3.3 Polygon Template Parameters 3.4 Text Template Parameters 3.5 Symbol Template Parameters 3.6 Icon Template Parameters 3.7 Using Colors 3.8 Zoom Factor Values 3.9 Dash Styles 3.10 Line Caps 3.11 Hatch Styles 4 Rendering Options 5 Layering in Kosmos 6 Performance Considerations 7 Limitations 8 Links

Rules Table(s)

Rules have to be entered in one or more tables as seen on the KosmosStandardRules and Kosmos General Purpose Rules pages. Anything outside the tables is ignored by Kosmos and can be used for writing comments or separating the Wiki page into several sections (which is highly recommended, since you can then edit portions of rule list separately).

Each row represents a single rule:

Rule Name	Targets	Selector	Templates	Options	Comment
RestaurantNode		amenity=restaurant	Icon (MinZoom=13, IconUrl=http://wiki.openstreetmap.org/images/5/58/Restaurant.png, Width=12:5;17:20) Text (MinZoom=15, Color=black, TagToUse=name, FontName=Arial, FontStyle=regular, FontSize=15:5;17:9, TextLineOffset=-200%)

The table column's are as follows:

• Rule Name: some uniquely identifiable string
• Targets: tells Kosmos the types of OSM objects this rule should apply to. You must use OSM IconNode, IconWay, IconArea and IconRelation templates, example:

  {{IconWay}}

  tells Kosmos the rule only applies to ways.
• Selector: tells Kosmos which concrete elements should be covered by this rule. See #Element Selectors for more.
• Templates: tells Kosmos what kind of graphics to display as a representation of the matched element. See #Templates for more.
• Options: Some additional rendering options (not required)
• Comment: Some human-readable comment for the rule, ignored by Kosmos (not required)

Child Rules

By giving the rule a name which starts with a dot, you are specifying that this is a child rule of the parent rule (parent rule is the first non-child rule that appears before in the table). Example:

HighwaySecondary		highway=secondary	Text (MinZoom=15, Color=black, TagToUse=name, FontName=Arial, FontStyle=regular, FontSize=15:6;17:9)	ChildrenFirst
.Bridge		bridge=yes	Polyline (MinZoom=8, Color=#FDBF6F, BorderColor=gray, BorderWidth=30%, Width=8:1;10:2;13:6;17:14)
.*			Polyline (MinZoom=8, Color=#FDBF6F, BorderColor=gray, Width=8:1;10:2;13:6;17:14)

What does this all mean? We are specifying that all ways tagged with highway=secondary will have their names rendered as text. Also, all such ways which represent bridges will be drawn using a polyline with a thicker border. All other ways (non-bridges) will be drawn using a normal border width.

Child rules compete for the right to be rendered. The first child rule that meets the selector criteria will be used to render an OSM element. All child rules (of the same parent) after that will be ignored for this OSM element.

A child rule named as .* represents a special case (called the default child rule) which is used to cover all OSM elements which did not match other child rules. You do not have to specify this default child rule, but if you do, make sure it is the last child rule in the list.

Any Targets or Options specified for child rules are ignored by Kosmos.

Sometimes you want templates specified by child rules to be rendered before those of the parent. In this case, specify ChildrenFirst option for the parent rule.

Element Selectors

Two types of element selectors are available:

• Using the OSM Wiki tag template (tag_name=* or tag_name=tag_value): selects all OSM elements which are tagged with the tag_name. tag_name=* will select elements regardless of its value, while tag_name=tag_value will select elements which have a specified value for the tag. Defined using the OSM Wiki tag template, example:

  {{tag|highway}}

  or

  {{tag|natural|coastline}}

It is possible to set more than one tag for each rule. This means that only those elements which have all of the specified tags would match the query. So for example:

{{tag|amenity|restaurant}} {{tag|cuisine|chinese}} {{tag|name|Hot Rat}}

would select all Chinese food restaurants whose names are 'Hot Rat' (not that I know any ;) ).

• Complex expression: used for more complex queries. Example:

  IsTaggedWith(e,"ele") AND ValueNum(e,"ele") % 100 = 0

  will select all OSM elements which have the ele tag and its value is divisible by 100 (this is used for rendering major elevation contours generated by Srtm2Osm tool).

Complex Expressions Syntax

NOTE: complex expressions are an experimental feature at the moment. The syntax described below will probably change in the near future (it will be simplified). Also, I will try to make expressions evaluation less performance-intensive.

Kosmos currently uses Flee library to evaluate complex expressions. Check out the link to see all the available operators.

Three specials functions are provided by Kosmos to be used in the complex expressions:

1. IsTaggedWith (e,"key"): returns true if the element (node, way, area) has any tag which uses the specified key ; otherwise false.
2. ValueNum (e,"tag"): returns a numerical value of the tag tag
3. ValueString (e,"tag"): returns a string value of the tag tag

Be sure to read Kosmos Rendering Help#Performance Considerations regarding the use of complex expressions.

Templates

Kosmos templates are graphical representations of OSM elements on the map. Currently these are templates which can be used:

• Polyline: draws a polyline
• Polygon: draws a closed polygon
• Text: draws a text
• Symbol: draws a simple symbol or a series of symbols along a polyline
• Icon: draws an icon

Each rule can have one or more templates (the example above uses two). Each template has to be its own line, example:

Name der Regel	Ziel	Selektor	Vorlagen	Optionen	Kommentar
RestaurantNode		amenity=restaurant	Icon (MinZoom=13, IconUrl=http://wiki.openstreetmap.org/images/5/58/Restaurant.png, Width=12:5;17:20) Text (MinZoom=15, Color=black, TagToUse=name, FontName=Arial, FontStyle=regular, FontSize=15:5;17:9, TextLineOffset=-200%)

Each template has associated parameters. Some parameters are available for all template types and some are specialized for an individual template type.

Standard Parameters

• MinZoom: the minimum zoom level at which the template will be rendered (default: unlimited)
• MaxZoom: the maximum zoom level at which the template will be rendered (default: unlimited)
• Color: the basic color of the template. Colors must be entered in the HTML style, examples: #FEADB8, white
• Options: specifies options for rendering the template. Currently only one option is supported: TopLevel (see Kosmos Layering for more information about this option).

Polyline Template Parameters

• Width: the width of the polyline, entered as the zoom factor value (required)
• DashStyle: if set, the polyline will be drawn with the specified dash style
• LineStartCap: if set, the polyline will be drawn with the specified starting line cap
• LineEndCap: if set, the polyline will be drawn with the specified ending line cap
• BorderColor: if set, the polyline will be rendered in the highway-stile, with the outside border
• BorderWidth: the width of the polyline border, entered as a percentage of the Width, defaults to 10%
• BorderDashStyle: if set, the polyline border will be drawn with the specified dash style

Polygon Template Parameters

• BorderColor: if set, the polygon will have a border
• BorderWidth: the width of the polyline border, entered as the zoom factor value
• BorderDashStyle: if set, the polyline border will be drawn with the specified dash style
• HatchStyle: if set, the polygon will be hatched using a specified style
• BackgroundColor: the background (second) color of the hatch

Text Template Parameters

The text template works in two modes, depending on the type of the OSM element which it represents. For nodes, the text is rendered horizontally and centered on the node. For polylines, the text is rendered along the polyline.

• TextMode: in what way the text will be rendered. The possible values are:
  • Node: the text will be centered on the associated node. This mode can only be used with rules which target nodes and it is a default value, so it is not necessary to set it.
  • AlongWay: the text will be displayed along the associated way. This mode can only be used with rules which target ways or areas and it is a default value, so it is not necessary to set it.
  • AreaCenter: the text will be displayed on the center of the associated area. This mode can only be used with rules which target ways or areas.
  • WayCenter: (new in v2.1) the text will be displayed (roughly) in the center of the way. This mode can only be used with rules which target ways.
• TagToUse: the name of the OSM element's tag whose value will be used as the text to be rendered. You can enter multiple tags separated by semicolon (;). Kosmos will use the first of the tags that it finds. Example: TagToUse=nat_name;name will cause national names to be rendered for OSM features. If a national name does not exist, a common default name will be used.
• FontName: the name of the font to use
• FontStyle: the style of the font. Can be one of following values: Bold, Italic, Regular, Strikeout, Underline. If not set, "Regular" is used
• FontSize: the size of the font
• TextLineOffset: specifies the line (vertical) offset of the text as a percentage of the text size. The offset is calculated from the corresponding OSM node's position. Negative offset means moving the text down from the original node’s position. This parameter is supported for Node, AreaCenter and WayCenter TextModes (since version 2.3).
• BorderWidth: the width of the box surrounding the text, expressed in pixels. If not set, the box will not be rendered.
• BackgroundColor: the background color of the box surrounding the text.
• OutlineColor: (new in v2.1) the color of the text outline. If not set, the text will not be outlined.
• OutlineWidth: (new in v2.1) the width of the text outline, entered as a percentage of the original font height.

Symbol Template Parameters

• Type: the type of the symbol. Can be one of following values: Square, Circle, Triangle, Diamond
• Size: the size of the symbol, entered as the zoom factor value
• BorderColor: if set, the symbol will have a border
• BorderWidth: the width of the symbol border, entered as a percentage of the Width
• BorderDashStyle: if set, the symbol border will be drawn using a specified dash style
• HatchStyle: if set, the symbol will be hatched using a specified style
• BackgroundColor: the background (second) color of the hatch
• Density: when Symbol is used for ways or ares, the density specifies the space between symbols along the polyline. Entered as a zoom factor value.

Icon Template Parameters

NOTE: Since version 2.3, icon template can be used for nodes and areas.

• IconUrl: the URL of the icon
• Width: the width of the icon, entered as the zoom factor value (required)
• HAlign and VAlign: specify horizontal and vertical alignment of the icon. Can be one of the following values: Center, Near, Far. Icons are centered by default

Using Colors

Colors can be entered as HTML color names, examples: "black", "white", "red", "#00FF00". Also, Kosmos supports the ARGB scheme, which means that you can also specify the alpha value of the color. This can be helpful if you want to use transparency effect. Example: color "#80FFFF00" means half-transparent yellow. The lower the alpha value is, more transparent will the template be.

Zoom Factor Values

Zoom factor values allow you to specify how the certain property will change its value according to the zoom level. Basically, you specify the property values for certain zoom levels, and the rest is calculated (interpolated) by Kosmos based on known points you specified. Example:

Width=1:1;9:1.5;17:6

means that the width used by the template will be 1 pixel on zoom level 1, 1.5 pixels on zoom level 9 and 6 pixels on zoom level 17. Everything in between is interpolated, so for example on zoom level 12 the width will be 3.1875

You can specify as many known points as you like. In addition, zoom level need not be an integer value.

Dash Styles

The following values are currently supported:

• Solid, _________
• Dash, - - - - -
• Dot, . . . . .
• DashDot -.-.-.- and
• DashDotDot. -..-..-..-

Example:

DashStyle=Dash

See [1] for examples.

Line Caps

Example:

LineEndCap=Round, LineStartCap=Round

See [2] for a list of all cap styles.

Hatch Styles

We may be able to take examples and supported values from [3]. -LastGrape/Gregory (LwD)

Rendering Options

These are some additional options which can change the behavior of the template. Currently only one option is available: EliminateSeams.

EliminateSeams can be used on a polyline template. If this option is turned on, Kosmos will try to connect all the ways of the same type before actually drawing them on the screen. This means that seams are then eliminated.

However, this only works for ways rendered with the same rendering rule. Also, seam elimination prevents using Curved=true option for ways, since the combination can get ugly. On the example image, three ways are drawn instead of two.

Obviously, seam elimination algorithm has to be improved in the future.

Layering in Kosmos

Kosmos draws OSM elements in a certain order. This order defines what element comes above other element. Elements which are drawn first can be come partially or fully covered by other elements. More on this on Kosmos Layering.

Performance Considerations

In order for Kosmos rendering engine to draw as quickly as possible, following things should be avoided, especially when rendering a large OSM data set:

• Do not use complex selectors on OSM nodes. Complex selector require considerably more processing to be evaluated and since there are a lot of nodes to process, this could take a while.
• If you need to select OSM data based on a multiple tags criterion, use simple element selector instead of the complex one. Complex selectors should only be used in cases when something has to be calculated or compared (for example, showing peaks that are higher than 2000 meters). If you do have a special case and you think it is a common usage, you can post a question to the talk page. If the selector is useful to a general public and is not too specific, I will try to implement it directly in the code, which means that it will run much quicker than by using complex selectors.

Limitations

The rendering engine has certain limitations, most of which stem from the fact that it uses .NET GDI+ for rendering. Also, since the engine is still in development, there will be continual improvements.

The limitations are:

• Only up to 32 characters will be rendered by the Text template when drawn along polylines.

Things still to be done:

• Rendering of one-way streets
• Dead-end streets are not drawn closed

Links

• Beautify Your UIs with Perfect Pen and Brush Control - contains a list of line caps, hatches etc. supported by GDI+
• HatchStyle chart
• Common fonts to all versions of Windows & Mac equivalents