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.

Whilst QMapShack doesn't support Mapsforge maps (i.e. from openandromaps.org), you can use a local tile server and a TMS file to display the maps nevertheless.

To set up the tile server, you have to download (or clone) appropriate branch of mapsforgesrv repository, either master for Java11 and newer or Java8 for Java8 and newer. Copy the contents of the jars_ready2use folder to an easily accessible path. You can delete the rest.

Now download some map of interest into any folder that suits you. To conveniently start the tile server create a .cmd file where you copied the contents of jars_ready2use and add this as contents:

java -jar \path\to\jarfile.jar -m \path\to\mapfile.map -sft 1.2 -sfs 0.8
pause

Double-click the .cmd file to start tileserver, you should get something like this as output:

2022-04-27 09:14:03.974 MapsforgeSrv - a mapsforge tile server. version: 0.17.5
2022-04-27 09:14:03.985 ################## CONFIG INIT ##################
2022-04-27 09:14:03.989 Listening TCP port        : default [8080]
2022-04-27 09:14:03.989 Server interface          : default [localhost]
2022-04-27 09:14:04.048 Map file(s)               : defined [{Alps_oam.osm.map}]
2022-04-27 09:14:04.048 Theme                     : default [OSMARENDER]
2022-04-27 09:14:04.049 Theme style               : default [null]
2022-04-27 09:14:04.049 Theme overlay(s)          : default [undefined]
2022-04-27 09:14:04.049 Preferred map language    : default [null]
2022-04-27 09:14:04.049 Contrast stretch          : default [0]
2022-04-27 09:14:04.052 Gamma correction          : default [1.0]
2022-04-27 09:14:04.052 Hillshading magnitude     : default [1.0]
2022-04-27 09:14:04.053 DEM                       : default [undefined]
2022-04-27 09:14:04.053 Renderer algorithm        : default [database]
2022-04-27 09:14:04.053 Device scale factor       : default [1.0]
2022-04-27 09:14:04.053 User scale factor         : default [1.0]
2022-04-27 09:14:04.053 Text scale factor         : default [1.2]
2022-04-27 09:14:04.054 Symbol scale factor       : default [0.8]
2022-04-27 09:14:04.054 Browser cache ttl         : default [0]
2022-04-27 09:14:04.054 Out of range TMS url      : default [null]
2022-04-27 09:14:04.054 Append built-in world map : default [false]
2022-04-27 09:14:04.055 Server max queue size     : default [256]
2022-04-27 09:14:04.055 Server max thread(s)      : default [8]
2022-04-27 09:14:04.055 Server min thread(s)      : default [0]
2022-04-27 09:14:04.055 Connection idle timeout   : default [0]
2022-04-27 09:14:04.055 Server connector(s)       : default [{http11}]
2022-04-27 09:14:04.076 Logging initialized @309ms to org.eclipse.jetty.util.log.Slf4jLog
2022-04-27 09:14:04.354 ################### MAPS INFO ###################
2022-04-27 09:14:04.370 'Alps_oam.osm.map' supported languages: {de,en,fr,it,sl}
2022-04-27 09:14:04.461 ################ STARTING SERVER ################
2022-04-27 09:14:04.465 jetty-9.4.46.v20220331; built: 2022-03-31T16:38:08.030Z; git: bc17a0369a11ecf40bb92c839b9ef0a8ac50ea18; jvm 1.8.0_331-b09
2022-04-27 09:14:04.507 Started ServerConnector@737996a0{HTTP/1.1, (http/1.1, [proxy])}{127.0.0.1:8080}
2022-04-27 09:14:04.507 Started @741ms
2022-04-27 09:14:04.508 server connector configured with accept queue size '128', idle timeout '0'
2022-04-27 09:14:04.508 job executor configured with threads min '0', max '8', idle timeout '0'
2022-04-27 09:14:04.508 job queue configured with max size '256'
2022-04-27 09:14:04.508 server is up and listening on 'localhost:8080'

If this is successful, you can add a TMS file to your QMS map folder with following contents:

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

Further options are explained on the git site of the tile server.

If you want to use a different theme for the map, you can download any theme that does or does not use style menus. This is because recent tile server supports style menus too. From openandromaps.org you can download the Elevate 5 theme aka OpenAndroMaps style. Again, save theme files to some convenient folder and edit the contents for your .cmd file to:

java -jar \path\to\jarfile.jar -m \path\to\mapfile.map -t \path\to\themefile.xml
pause

or to choose a different style than the theme's default style:

java -jar \path\to\jarfile.jar -m \path\to\mapfile.map -t \path\to\themefile.xml -s \style\of\theme
pause

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 comfortably 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