Kosmos/Layering

This page describes a historic artifact in the history of OpenStreetMap. It does not reflect the current situation, but instead documents the historical concepts, issues, or ideas.

---

Kosmos draws OSM elements in a certain order. This order defines what element comes above other element. Elements which are drawn first can become partially or fully covered by elements drawn after it.

Ordering of elements is based on several criteria, described below (in descending order of importance):

1. Painting stage of the template used.
2. OSM layer of the element drawn.
3. Ordering of the rule in the rules table.

Painting Stages

Kosmos cannot rely simply on OSM layer tagging to achieve proper mapping effects. Example: Kosmos draws transparent relief shading over features such as forests, but all of the roads have to be drawn the without underlying relief shading. Another example: we always want map labels to be drawn above all other map features, regardless of any OSM layer tagging.

Because of this, when drawing map, Kosmos separates the process into several painting stages:

1. Background1 - land areas (forests, rivers, farms, sporting grounds etc) are drawn in this stage
2. Background2 - reserved for transparent rasters (shading reliefs, for example)
3. Infrastructure - all non-area ways (roads, canals, etc) are drawn in this stage
4. Symbols - all symbols and icons are drawn in this stage
5. Labels - all texts on maps are drawn in this stage
6. MapLegend - for future use

By choosing which type of a template you use for a certain OSM element, you tell Kosmos in which stage this element should be drawn. Currently, the mapping from a template type to a painting stage is fixed, so you cannot for example instruct Kosmos to draw forests above roads. However, with new versions of Kosmos additional painting stages may be introduced if there is a need. So I am open to suggestions regarding this.

OSM Layers

As described above, OSM layering information (layer=*) is not a top-level deciding factor on what gets drawn above what. OSM layers, however, are used by Kosmos within an individual painting stage. So a road, for example, will be drawn above railway if the road layer is higher than the railway's.

TopLevel Template Option

Since version 1.12 Kosmos allows overriding the OSM layering information so that a template can be rendered above all others, regardless of its OSM layer. Example:

Rule Name	Targets	Selector	Template	Options	Comment
HighwayCycleway		highway=cycleway	Polyline (MinZoom=13, Color=#0202FE, DashStyle=Dash, Width=13:1;17:4, Options=TopLevel)	EliminateSeams

will render cycleways above all other features in the Infrastructure painting stage.

Rule Ordering

If Kosmos encounters two OSM elements which should be drawn in the same painting stage and which are part of the same layer, then the ordering of the rule in the rules table will decide what gets drawn first. Example: we have a residential road and a primary road. They are both tagged with layer=1. If the rule for rendering residential roads is higher to the top of the rendering rules table, then the primary road will be drawn above the residential road (this is important when two roads meet at the crossing). That is why it is important to sort rendering rules table according to the "importance" of an OSM feature (at least for related types of features).