Maps Widget - Notes and Restrictions

Notes

Offline Warning Plugin

To indicate for the user that currently no online data is available the OfflineWarning plugin is displayed within the right upper corner of the Maps Widget.

The plugin is enabled by default and to disable or adjust it the function setPluginData() (plugin = "offlinewarning") can be used.

Following plugin specific settings are available and can be adapted:

  • "textSize" - Default:14
  • "textColor" - Default: "#00ffff"
  • "offlineText" - Default: "OFFLINE"

Example

To disable the plugin following command can be used:

MyMapsWidget.setPluginData("offlinewarning", "enabled", FALSE);
Note:

The displayed text of the plugin is not localized. To update the text to the project language you are using, the offlineText setting of the plugin must be changed manually in Control.

Cache Loading Order - Project / Product

The overall order of loading files for the Map Widget is identical to the default behavior of the product. The Widget tries to load files from the project directory and if they are not available within the project the installation directory of the product is used.

Unlike the default behavior the searched directory names are different between project and product. While the product uses the structure <product>/data/marble/maps/earth/ the project must use the folder structure <project>/data/maps/maps/earth/.

When the project directory is used to store tiles of an existing map theme (e. g. OpenStreetMap), it is sufficient to only store the new tiles in the project, existing data from the product (e. g. dgml file, level 0 tile) will be automatically taken from there, as long as the same directory name is used, e. g.:

<product>
-data
--marble
---maps
----earth
-----openstreetmap
------0
-------0
------openstreetmap.dgml
<project>
-data
--maps
---maps
----earth
-----openstreetmap
------1
-------0
-------1
-----2
------0
------1
------2
------3
-----...

If the same map tile exists in several places, the user-specific cache has the highest priority, followed by the project directory, then by the product directory.

The user-specific cache is located under:

  • Windows: C:\Users\<user>\AppData\Local\.marble\data\maps\earth
  • Linux: /home/<user>/.local/share/marble/maps

Regardless where the tile is found, if it is older then the map themes expiry interval, a download will be attempted if online, and the most recent tile will be put into the user-specific cache (and will have highest priority). On the other hand, if it is not expired, no download attempt will be made.

Cache limits

Changing a cache limit (volatileTileCacheLimit or persistentTileCacheLimit) will only be applied after restarting the UI. The limits are also only applied for the current OS user.

For the persistent tile cache the primary layers (1-3) within a map will never be deleted. They are also not considered for any cache limits.

Directories within the cache are never deleted.

Map Widget Properties within .dgml File

Please be aware that loading a mapThemeId might change settings already made within GEDI or Control as specific map settings and displaying options are predefined within a map theme. Changing the properties after loading the .dgml file or adapting the .dgml file will prevent unexpected changes.

Read DGML Files

A small CTRL library for reading .dgml files within Control can be found within the Maps Widget Demonstration panel folder.

Localization of coordinates

The functions working with coordinates provide the option to either work with float or string coordinate inputs. For string coordinate inputs it must be considered that they are localized. Therefor they must be stated with the corresponding equivalents to (N)orth, (S)outh, (E)ast and (W)est.

It is recommended to use these string versions only if necessary for user input.

OpenStreetMap File Size

Export files from the OSM database (.osm) contain all data for the selected region, including history information (like author, timestamp, version) together with a lot of information that is not relevant for our use case.

Loading .osm files into Marble requires a signification amount of memory (at least 5 times the size of the .osm file), so it is important to remove all irrelevant information from these files before opening them in Marble or the Maps Widget.

Filtering

Osmfilter (https://wiki.openstreetmap.org/wiki/Osmfilter) is a program that does exactly that: take an *.osm file, remove information not needed, and write the result into a smaller .osm file. Detailed documentation is available online, here’s an example:

A download of Eisenstadt and the surrounding area yielded a .osm file of about 95 MB.

Figure 1. OSM - Eisenstadt

The following command was used to filter this file to include only necessary information to display the data visible in the screenshot above:

SET PROJ_DIR=D:\WinCC_OA_Proj\Lang3\data\maps
osmfilter --parameter-file=.\filter.txt %PROJ_DIR%\eisenstadtKomplett.osm >%PROJ_DIR%\eisenstadtFiltered.osm

All filter parameters are contained in the file filter.txt:

--drop-version
--keep=
  highway=motorway =motorway_link =primary =primary_link=secondary =secondary_link
  admin_level
  natural=coastline =water =wood
  landuse
  railway=rail =light_rail
  place=city =town =village
  waterway=river =stream
 marble_land=landmass

This produced a .osm file of about 9 MB. The parameter --drop-version removes all history information, while --keep specifies which objects will be contained in the result.

Depending on the application, it has to be decided which information to include in the filter. The basic problem is the fact that to generate a filtered file, you’ll need to start from a (typically) very large complete file.

There is also a download server that allows to exactly specify which parts of the OSM database to download, but it also has quite some limitations. More details can be found here: https://wiki.openstreetmap.org/wiki/Overpass_API.

Compression

.osm files are XML files, which isn’t very efficient. Therefore, there is also a binary format for these files called.o5m and a converter tool to convert from one format to the other. The 9 MB file from above can be converted with the following command:

osmconvert64 --out-o5m %PROJ_DIR%\eisenstadtFiltered.osm >%PROJ_DIR%\eisenstadt.o5m

The resultant file is a little bit about 1 MB in size. The memory consumption doesn’t change (about 50 MB for the filtered version), but the file is faster to download and distribute when necessary.

Connection Loss / Alive Time-out

In case of a connection loss due to the alive time-out in case a Desktop UI or Mobile UI Application is used for displaying huge maps inside of the Maps Widget increasing the [ui] aliveTimeout will give additional time for downloading the project files.

Restrictions

Following restrictions must be considered when using the Maps Widget.

  • Due to restrictions of the operating system the Maps Widget is not supported for the iOS version of the Mobile UI Application.
  • The Maps Widget is not allowed to be used for security/safety relevant projects
  • Displaying map content is not pixel precise and due to internal render calculations overlapping objects (rivers, towns, etc.) and annotations inside of the map may be displayed differently or hidden each time the map is opened.
  • Map files with more than 300MB cannot be loaded.