LoMaps themes & generator

This project contains the default themes for offline LoMaps used in Locus Map app. LoMaps are vector maps generated by Mapsforge Map-Writer. This DOC contains useful information for creators of alternative theme for LoMaps maps.

Project structure

Project consists from three main parts:

• android module - custom module for automatic usage of theme in the app
• theme generator - python tools that generates themes from custom XML templates
• themes - default internal LoMaps themes

POI Themes

LoMaps V4 still do not use MapsForge POI database but custom format of POIs (and offline address database). Locus app loads the POIs on the fly and displays the POIs in clickable layer above the map.

In the previous version of LoMaps (V3), the POI symbol (icon, zoom level, etc.) defined in one map theme. For LoMaps V4 a new approach is used. When styles for POIs are defined in a separate theme file. This POI theme is a standard MapsForge theme with only rules for points of interest. The following rules apply for the POI theme:

• the file must be located in the same directory as the map theme
• the file name must be in the form nameOfMapTheme_layerId.poi.xml
  • see for example the files in theme folder, when:
    • theme.xml - base map theme
    • theme_ski.poi.xml - POI theme for layer with id 'ski'

The POI theme is optional thr Hike & Bike POI theme is used as default when POI theme doesn't exist.`

Theme Generator

The final LoMaps theme is prepared by our simple generator that has two main functionalities:

• the possibility to use variables in theme
• the ability to customize a specific section in a theme and convert it for another section

Theme Generator Usage

python theme_generator.py [-h] [-bt BASETEMPLATE] [-rt RESULTTHEME] [-tc TEMPLATECONFIG] [-ac APDBCONFIG] [-c] [-pa]

Options

Short	Long	Description	Default
-h	--help	Show help
-bt	--baseTemplate	Path to cheetah template (custom theme file with variables and custom methods)	xml_templates/theme_template.xml
-rt	--resultTheme	Path to file to export the generated themes	../theme/theme.xml
-tc	--templateConfig	Path to file with variables for theme template	xml_templates/config.py
-ac	--apdbConfig	Path to file with configuration of Offline POI database	xml_templates/config_apDb.xml
-c	--copyToDevice	Copy theme files to the Android device	false
-pa	--publishForAndroid	Copy theme files to the custom Android module folder	false

Template config

Generator uses a Cheetah3 template engine to replace variables in base theme template and generate final theme. The variables are defined in template config file

Generator actions

In addition to the mentioned template system, the generator offers specific actions for generating parts of the theme (railway bridges, marked trails, ...)

For these actions, it is always necessary to define a section that will be used as the source for generating a new section from the source section. Section is defined as attribute: gen_section="sectionId"

See the example bellow when source section that render the railway and generator action that convert these section into bridge

<!-- railway source section -->
<rule e="way" k="railway" v="light_rail" zoom-min="12" gen_section="railway_sec">
    <line stroke="#4d4d4d" stroke-width="1.5" stroke-linecap="butt"/>
    <line stroke="#EDEDED" stroke-width="1" stroke-dasharray="7,0.5" stroke-linecap="butt" scale="all"/>
</rule>

        <!-- railway tunnel as dashed line -->
<rule e="way" k="tunnel" v="yes">
    <generator action="$gen_action_create_highway_tunnels" source_section="railway_sec"/>
</rule>

The output from generator:

<rule e="way" k="railway" v="light_rail" zoom-min="12">
    <line stroke="#4d4d4d" stroke-width="1.5" stroke-linecap="butt"/>
    <line stroke="#EDEDED" stroke-width="1" stroke-dasharray="7,0.5" stroke-linecap="butt"
          scale="all"/>
</rule>

        <!-- railway tunnel as dashed line -->
<rule e="way" k="tunnel" v="yes">
    <line stroke="#707070" stroke-width="1.5" stroke-dasharray="6,6" stroke-linecap="butt" scale="all"/>
</rule>

The source may be more complex. Please see the theme template for more examples.
Unfortunately the actions are little hardcoded for LoMaps style and can't be customized at this moment.

Possible actions:

• action_create_tunnels - convert straight line into semi-transparent dashed line
• action_create_railway_bridge - adds thin lines representing a bridge
• action_create_osmc_colors - the source section is definition of marked trails and this action copy this section for all OSM colors ( "red", "black", "blue", "brown", "gray", "green", "orange", "purple", "yellow")
• action_sac_scales_to_lwn - copy SAC rules for hiking routes that aren't defined by OSMC symbol or color
• action_create_cycle_icn - duplicate style of RCN to ICN cycle routes and change line colors to ICN style
• action_create_mtb_scale_0_from_basic - duplicate style of basic cycle way for MTB trails with mtb:scale=0 and change color to MTB style
• action_create_osmc_symbols_order - duplicate OSMC symbols part symbols to display symbols along line with different repeat-start
• action_copy_section - simple copy content of section into different place

Copy to device and refresh theme

Theme generator script is able to copy the generated theme to android device and refresh the last used theme in Locus Map app. It may be useful if you testing theme directly in Locus Map app.

Prerequisites:

• adb is installed on your PC
• Locus Map 4 is installed on Android device
• check the options android_module_path locus_theme_path in options.yaml and change the paths based on your Locus working directory and name of the theme.

Please note that only theme .xml file are copied to the android device. It's required to copy symbols, patterns manually.