Prev (Install Maps & DEM Data) | Home | Manual | Index | (Control maps and DEM files) Next

Table of contents

• Basic knowledge about maps and DEM files
  • Map formats
    • Vector Maps
    • Raster Maps
    • Online Maps
    • DEM Files
  • Projection and Scaling
  • GDAL *.vrt Maps
  • WMTS Maps
  • TMS Maps
  • Mapsforge Maps

QMapShack supports the following map formats:

The default basic projection used by QMapShack is Mercator. The geographic datum is WGS84. However, you can use maps with different projection and datum as QMapShack will re-project them on-the-fly. The same applies to the scale. QMapShack uses a fixed logarithmic scale. All maps will be re-scaled to this scale on-the-fly.

It is also possible to change the basic projection via "View->Setup Map Workspace".

All raster maps handled by GDAL have to be wrapped by a virtual map. You can do this with gdalbuildvrt. A virtual map can contain one or several map files (you can replace .tif with any other extension supported by GDAL, e.g. .hgt).

gdalbuildvrt My_Map_Name.vrt path1/file1.tif path2/file2.tif

If you have a lot of files you can use wildcards:

gdalbuildvrt My_Map_Name.vrt path1/*.tif

If you use the wacky console of Windows you have to do this in two steps:

for %f in (*.tif) DO echo %f >> hgt_list.txt
gdalbuildvrt My_Map_Name.vrt -input_file_list hgt_list.txt

You can define a no data value, too. This is quite useful for DEM data that does not cover a complete rectangular area:

gdalbuildvrt -vrtnodata 32767  ASTER_GDEM2_Europe.vrt europe/*.tif

Important: All files must have the same color mode and the same projection/datum/scaling.

If the files are large it will take a lot of memory and time to display them in the outer zoom levels. You might consider to use gdaladdo to add overview levels to the files.

gdaladdo My_Map_Name.vrt 2 4 8 16

This will create a file My_Map_Name.vrt.ovr next to My_Map_Name.vrt containing scaled overviews by factor 2 4 8 16.

A Web Map Tile Service (WMTS) is a standard protocol for serving pre-rendered georeferenced map tiles over the Internet (says Wikipedia). The capabilities of a WMTS server are defined in an XML document named WMTSCapabilities.xml. It can be found on the server:

http://<server_address>/<optional_path>/1.0.0/WMTSCapabilities.xml

For example there is a variety of free worldwide WMTS map from ArcGIS. The capability sheet of the topo map can be found at:

http://services.arcgisonline.com/arcgis/rest/services/World_Topo_Map/MapServer/WMTS/1.0.0/WMTSCapabilities.xml

Or satellite images:

http://services.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/WMTS/1.0.0/WMTSCapabilities.xml

To use the map you download the XML file and rename it, let's say: World_Topo.wmts. Move the file into QMapShack's map path and you can use the map online.

For some servers, the "capabilities" XML sheet may need some hand tuning (comparing with the above working ones from ArcGIS may greatly help in fixing it). For example, there is some detailed info about French IGN WMTS server in the "maps tips & tricks" section.

If your WMTS provider needs some custom HTTP headers you can specify them in the XML file :

<?xml version="1.0" encoding="UTF-8"?>
...
<Capabilities>
...
    <Contents>
        ...
        <RawHeader>
            <Value name="User-Agent">Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0</Value>
        </RawHeader>
        ...
    </Contents>
</Capabilities>

For more information compare also the page "Frequently Asked Questions - Maps".

To access TMS servers you have to define a few properties via XML file. This is an example for definition file with two layers.

<TMS>
 <Title>OSM D-Land TK 50</Title>
 <MinZoomLevel>3</MinZoomLevel>
 <MaxZoomLevel>18</MaxZoomLevel>
 <Layer idx="0">
  <Title>Open Topo Map</Title>
  <ServerUrl>http://a.tile.opentopomap.org/%1/%2/%3.png</ServerUrl>
  <MinZoomLevel>3</MinZoomLevel>
  <MaxZoomLevel>11</MaxZoomLevel>
 </Layer>
 <Layer idx="1">
  <Title>Trails</Title>
  <ServerUrl>http://tile.waymarkedtrails.org/hiking/%1/%2/%3.png</ServerUrl>
  <MinZoomLevel>3</MinZoomLevel>
  <MaxZoomLevel>9</MaxZoomLevel>
 </Layer>
 <RawHeader>
   <Value name="User-Agent">Whatever</Value>
 </RawHeader>
 <Copyright>Map data: (c) OpenStreetMap contributors, ODbL | Rendering: (c) OpenTopoMap, CC-BY-SA | Trails by tile.waymarkedtrails.org </Copyright>
</TMS>

<Title>: This tag is currently of no use and just for backward compatibility to QLandkarte

<Copyright>: A copyright notice for the maps displayed.

<RawHeader>: An optional list of name/value pairs to be inserted into the HTTP header of the request. Some servers want to see special value here. Example:

<RawHeader>
<Value name="User-Agent">Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36</Value>
</RawHeader>

<MinZoomLevel>: Can be 0..17. 0 is the most detailed level. Below this level tiles from the specified level will be taken and scaled.

<MaxZoomLevel>: Can be 1..18. 1 is the most detailed level. Above this level the map will not be drawn.

MinZoomLevel and MaxZoomLevel will be taken as default for the layers. Note: zoom level = 18 - map level

<Layer idx="0">: Specifies a layer. idx gives the order to display layers. 0 is first.

On each layer you can define:

<Title>: A name for the layer. If no title is given, "Layer" with the index number is used.

<ServerUrl>: This is the servers URL with placeholders. %1 is for the map level (z), %2 for the column (x) and %3 for the row (y). If the URL contains special characters, you have to escape them according to the HTML specification, e.g. & becomes &

<MinZoomLevel>: Override the default MinZoomLevel for this layer. Can be 0..17. 0 is the most detailed level. Below this level tiles from the specified level will be taken and scaled.

<MaxZoomLevel>: Override the default MaxZoomLevel for this layer. Can be 1..18. 1 is the most detailed level. Above this level the map will not be drawn.

Next to the normal TMS naming scheme for URLs the URL can be formed by a bit of JavaScript. Here is an example for Microsoft's Bing:

<TMS>
<Title>Bing</Title>
<Layer idx="0">
<Script><![CDATA[
(
function convert(z1, x1, y1)
{
  serverpart = 0
  serverpart = (serverpart + 1) % 4;
  function encodeQuadTree(zoom, tilex, tiley)
  {
    var tileNum = []
    for (var i = zoom - 1; i >= 0; i--)
    {
      var num = (tilex % 2) | ((tiley % 2) << 1);
      tileNum[i] = new String(num);
      tilex >>= 1;
      tiley >>= 1;
    }
    return tileNum.join("");
  }
  return "http://ecn.t" + serverpart + ".tiles.virtualearth.net/tiles/a" + encodeQuadTree(z1,x1,y1) + ".jpeg?g=1036";
}
)
]]></Script>
</Layer>
<Copyright>Microsoft - Bing</Copyright>
</TMS>

Instead of a <ServerUrl>: the layer has a <Script>: tag with JavaScript code.

Although QMapShack does not natively Mapsforge maps (i.e. from openandromaps.org) stored as offline files, you can use a local tile server and a TMS file to display the maps nevertheless.

To set up the tile server, open mapsforgesrv repository at GitHub and download JAR file mapsforgesrv-fatjar.jar from latest release.

Now download some map(s) of interest into a folder of your choice. Then create tile server's configuration folder containing server configuration file server.properties and a subfolder tasks. Create task configuration file(s) <task>.properties within subfolder tasks.

Simple server configuration file server.properties example:

port=8080

Simple Map task configuration file Map.properties example:

mapfiles=Map_folder/Alps_oam.osm.map

Note:
URL to request tiles from tile server is scheme://address:port/zoom/x/y.format?task=name, where

• scheme is protocol either http or https
• address is tile server's IP address
• port is tcp port to request tiles
• zoom is zoom level of requested tile
• x is tile number in x direction (longitude)
• y is tile number in y direction (latitude)
• format is tile image format png, jpg, tif, bmp, ...
• name is task configuration's file name with extension .properties cut off

URL example corresponding to example configuration above:

http://127.0.0.1:8080/14/8584/5595.png?task=Map

Using Java 11 or higher, start tile server from command line ...

java -jar JAR_Folder/mapsforgesrv-fatjar.jar -c Configuration_Folder

... and get an output like this:

2025-01-25 11:28:37.386 MapsforgeSrv - a mapsforge tile server. version: 0.23.0.2
2025-01-25 11:28:37.394 Java runtime version: 11.0.25+9-adhoc..jdk11u
2025-01-25 11:28:37.682 ################## SERVER PROPERTIES ##################
2025-01-25 11:28:37.697 Browser cache ttl         : default [0]
2025-01-25 11:28:37.697 Out of range TMS url      : default [null]
2025-01-25 11:28:37.698 Accept terminate request  : default [false]
2025-01-25 11:28:37.698 Request log format        : default [From %{client}a Get %U%q Status %s Size %O bytes Time %{ms}T ms]
2025-01-25 11:28:37.703 ################ TASK 'Map' PROPERTIES ################
2025-01-25 11:28:37.705 Map file(s)               : defined [{Alps_oam.osm.map}]
2025-01-25 11:28:37.706 Append built-in world map : default [false]
2025-01-25 11:28:37.706 Preferred map language    : default [null]
2025-01-25 11:28:37.707 Theme file                : default [OSMARENDER]
2025-01-25 11:28:37.707 Theme style               : default [null]
2025-01-25 11:28:37.707 Theme overlay(s)          : default [undefined]
2025-01-25 11:28:37.707 DEM folder                : default [undefined]
2025-01-25 11:28:37.708 Hillshading algorithm     : default [undefined]
2025-01-25 11:28:37.709 Hillshading magnitude     : default [1.0]
2025-01-25 11:28:37.709 Hillshading minimum zoom  : default [undefined]
2025-01-25 11:28:37.710 Hillshading maximum zoom  : default [undefined]
2025-01-25 11:28:37.710 Contrast stretch          : default [0]
2025-01-25 11:28:37.710 Gamma correction          : default [1.0]
2025-01-25 11:28:37.710 Device scale factor       : default [1.0]
2025-01-25 11:28:37.710 User scale factor         : default [1.0]
2025-01-25 11:28:37.710 Text scale factor         : default [1.0]
2025-01-25 11:28:37.710 Symbol scale factor       : default [1.0]
2025-01-25 11:28:37.710 Line scale factor         : default [1.0]
2025-01-25 11:28:37.711 ################ STARTING SERVER ################
2025-01-25 11:28:38.372 Virtual threads are disabled
2025-01-25 11:28:38.382 ################ STARTING TASK 'Map' ################
2025-01-25 11:28:38.383 ------------------- MAPS INFO --------------------
2025-01-25 11:28:38.401 'Alps_oam.osm.map' supported languages: {de,en,fr,it,sl}
2025-01-25 11:28:38.522 --------------------------------------------------
2025-01-25 11:28:38.552 jetty-11.0.24; built: 2024-08-26T18:11:22.448Z; git: 5dfc59a691b748796f922208956bd1f2794bcd16; jvm 11.0.25+9-adhoc..jdk11u
2025-01-25 11:28:38.642 Started ServerConnector@766653e6{HTTP/1.1, (http/1.1, h2c)}{0.0.0.0:8080}
2025-01-25 11:28:38.666 Started Server@3d3e5463{STARTING}[11.0.24,sto=0] @1682ms
2025-01-25 11:28:38.666 Started QueuedThreadPool[qtp980697799]@3a7442c7{STARTED,8<=8<=200,i=5,r=-1,t=59946ms,q=0}[ReservedThreadExecutor@1852a3ff{reserved=0/4,pending=0}]

If this is successful, you can add a TMS file, e.g. Mapsforge Map.tms to your QMS maps folder with following contents:

<TMS>
<Layer idx="0">
<Title>Mapsforge Map</Title>
<MinZoomLevel>1</MinZoomLevel>
<MaxZoomLevel>17</MaxZoomLevel>
<ServerUrl>http://127.0.0.1:8080/%1/%2/%3.png?task=Map</ServerUrl>
</Layer>
</TMS>

If you want to use a different theme and style for the map, you can download any Mapsforge theme that does or does not use style menus. From openandromaps.org you can download the Elevate 5 theme aka OpenAndroMaps style. This is the extended Maps.properties example:

mapfiles=Map_folder/Alps_oam.osm.map
themefile=Theme_folder/Elevate.xml
style=elv-city

For detailed tile server configuration requirements and options see tile server's README.

Alternatively, a wrapper script with graphical user interface based on above information makes Mapsforge maps available in QMapShack, amongst others OpenAndroMaps maps. Wrapper script lets the user interactively and conveniently select from locally stored Mapsforge maps and themes as well as pass further options to tile server. It allows for easily switching map(s) and theme while QMapShack keeps running. In addition, option settings automatically get saved and restored. Tile server and QMapShack get started/restarted by script using these settings. Script Mapsforge-for-QMapShack.tcl is written in Tcl/Tk command language and is executable on Microsoft Windows and Linux operating system. For more information, downloads, installation, usage and example see Mapsforge-for-QMapShack git repository.

Prev (Install Maps & DEM Data) | Home | Manual | Index | Top | (Control maps and DEM files) Next