Map Rendering style - .render.xml

OsmAnd rendering style is a special XML file that describes how vector map features should be displayed on the map. It is typically quite large by lines of code and highly customizable.

In this article

In case you want to modify a default rendering style, take a look at Github definition. Here you can also find all different styles, so in case you want to create your own style, you can find the easiest example.

In case you consider creating your own rendering style, you might need to create your own maps to add custom features display.

Map style sections

Map style file consists of several sections.

SectionDescription
HeaderConsists of name (style name), defaultColor (default map color could be overridden by attribute defaultColor) and depends (inherits all properties from parent style).
ParametersDefined as <renderingProperty> has attr which will be used in the style as a parameter name and name, description will be displayed to user.
Attributes and constantsDefined as <renderingAttribute> and as <renderingConstant> allows to reuse same blocks of rendering styles for different map objects
Order sectionDefined as a block <order>. Each map object is searched in the order-section to get whether it will be rendered as point, line or polygon (objectType) and in which order should be displayed.

Search parameters (input): tag, value, zoom, point (true or false), area (osm type), cycle (start and end point are same).

Search result (output): objectType (point = 1, line = 2, polygon = 3), order (0-255). Order of rendering is defined as: polygons, line-shadows, lines, points. If order is the same for polygons, then polygons are displayed from the largest polygon to the smallest. Note: polygons shouldn't overlap partially otherwise behavior is not defined.
Text sectionDefined as a block <text>. Each displayed map object is searched whether it should display the text and how it should be displayed.

Search parameters (input): tag, value, zoom, nameTag (each text tag is checked).

Search result (output): textOnPath, textMinDistance (margin between same texts i.e. road names, refs ), textSize, textColor, textHaloRadius, textOrder, textDy, textBold, nameTag2 (extra name in the braces if present), textShield (background arond text), icon (icon instead of text), textItalic, textWrapWidth, intersectionMargin (extra margin to not overlap text).
Point sectionDefined as a block <point>. Each displayed point map object (defined in order-section) is searched in this section to determine how it should be displayed.

Search parameters (input): tag, value, zoom, e.

Search result (output): shield (icon shield), icon, iconVisibleSize (extra space to not clutter icons), iconOrder, intersectionSizeFactor.
Polygon sectionDefined as a block <polygon>. Each displayed polygon map object (defined in order-section) is searched in this section to determine how it should be displayed.

Search parameters (input): tag, value, zoom .

Search result (output): color (color to fill the polygon), shader (fill polygon with same icon), color_2, color_N (color of stroke around polygon), strokeWidth_2 (stroke width), pathEffect_2, cap_2.
Line sectionDefined as a block <line>. Each displayed line map object (defined in order-section) is searched whether in this section to determine how it should be displayed. 1 line object could be rendered as multiple combined lines up to -2 layers below and up to 7 layers on top.

Search parameters (input): tag, value, zoom, nameTag (each text tag is checked), .

Search result (output): color, color_* (color of stroke around polygon), strokeWidth, strokeWidth_* (stroke width), pathEffect, pathEffect_* (path effect), cap, cap_* (BUTT, ROUND, SQUARE), pathIcon, pathIconStep, shadowRadius (shadow around line).

Map feature selectors

To determine which attributes should be retrieved from rendering style, following search procedure is completed:

  • Find the most inner <case> that corresponds to Search input parameters tag/value/zoom i.e. for highway=primary - <case tag="highway" value="primary"> will be found.
  • All internals of <case> are applied sequentially deep and output parameters are collected
    • <case><apply output="1"/><apply_if zoom="15" output="2"> <case> - output will be 2 in case zoom=15 and output will be 1 otherwise.
  • Checked if <case> is part of any <switch> and if it is then all apply and apply_if of that switch will be evaluated as well

Evaluation rules:

  • In each case, apply_if, switch, apply input attributes are checked to match (evalute to true), otherwise section is skipped and output attributes are not collected.
  • All rules evaluated sequentially and output parameters could be overridden by folowing rules
  • additional=? is a special input attribute that checks additional tags of the object
  • Map style parameters are input search parameters as well next to tag/value/zoom
    • Example: <apply_if nightMode="false" streetLightingNight="false" shield="street_lamp_lit_no_shield"/>. Input parameters: nightMode, streetLightingNight; output parameters - shield.

Attributes (special) & Constants

Rendering constants & rendering attributes are interchangeable and could be used to simplify rendering style and avoid copy/pasting of values or blocks of code. In case attribute like color is a single value, it is preferred to use rendering constant cause it greatly speeds up rendering style performance.

Rendering constants could be used only with one given value: <renderingConstant name="motorwayShadowRadius" value="1.6"/> and later in feature selectors as <apply_if shadowRadius="$motorwayShadowRadius"/>.

Rendering attributes could have embedded structure with extra selectors and output one of the following attributes (attrColorValue, attrBoolValue, attrFloatValue, attrIntValue, attrStringValue). Example:

    <renderingAttribute name="motorroadShadowColor">
        <case attrColorValue="#5f5fff"/>
    </renderingAttribute>
    .....
    <case showAccess="true" additional="motorroad=yes" attrColorValue="$motorroadShadowColor"/>

Special attributes

Special attributes are <renderingAttribute > that are not used by selectors but used directly by the code to query specific feature which is drawn in application like a navigation route, ruler, gpx track, etc.

Special attributeDescription
measureDistanceLineLine rendering for Plan Route feature
markerGuideline, markerPlanRoutelineRendering lines to the markers
routeRendering a navigation route
gpxRendering a GPX track
publicTransportLineRendering a public transport navigation route
walkingRouteLineRendering a public transport navigation: pedestrian route between stops
rulerLineFont, rulerLine, rulerCircleAlt, rulerCircleHow to render Radius-Ruler widget and measure distance by tap
defaultColorDefault color to fill the map (switches night / day mode)
shadowRenderingInternal how to render shadow with Skia
routeInfo_*Example: routeInfo_surface, routeInfo_roadClass are used to produce classes of roads to be displayed in the legend of the route.
polygonMinSizeToDisplayInternals how to render small lines and small polygons
roadDensityZoomTileInternals how to render small lines and small polygons
roadsDensityLimitPerTileInternals how to render small lines and small polygons
defaultSymbolPathSpacingInternals how to render small lines and small polygons
defaultBlockPathSpacingInternals how to render small lines and small polygons
globalPathPaddingInternals how to render small lines and small polygons
debugTextDisplayBBoxAttributes to debug text rendering and positioning
debugTextDisplayShieldBBoxAttributes to debug text rendering and positioning
debugTextDoNotFindIntersectionsAttributes to debug text rendering and positioning
debugTextDoNotFindIntersectionsSameNameAttributes to debug text rendering and positioning
debugTextDisplayShortRoadNamesAttributes to debug text rendering and positioning

Map Style Parameters

Map style parameters allow to combine multiple rendering style within one file definition i.e. there is no need to have separate 'my_custom_style_night_mode.render.xml', it is possible to define parameter like night_mode (enabled by default) and customize certain rules (like colors) using this parameter. Later in the User interface it's possible to easy switch that parameter and have a different map style in OsmAnd.

Here is a definition of baseAppMode parameter. possibleValues are values will be displayed in OsmAnd UI, category assists in which UI category this property belongs to.

<renderingProperty attr="baseAppMode" name="Default Rendering mode" description="Map optimization for respective User Profile based on base (parent) profile"
        type="string" possibleValues="default, car, bicycle, pedestrian, public_transport, boat, ski"/>

Later in the selection style you can specify when this selector could be applied i.e. for which application mode specified by the user

<renderingAttribute name="roadsDensityLimitPerTile">
        
        <case moreDetailed="true" attrIntValue="55"/>
        <case baseAppMode="pedestrian" attrIntValue="40"/>
        <case baseAppMode="bicycle" attrIntValue="40"/>
        <case attrIntValue="60"/>
    </renderingAttribute>

So if user selects moreDetailed=true then output value for density will be 55 and if baseAppMode=pedestrian (another parameter) it wil be 40, otherwise 60.

Did this doc help you?

Privacy policy

Help us make these docs great!

All OsmAnd docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.