This is an old revision of the document!


Custom stored maps

AlpineQuest allows you to create your own stored map configurations and access a wide range of on-line map servers.

Stored maps are defined using an XML based file format offering a powerful configuration flexibility. Files must have a “.aqx” extension to be recognized in AlpineQuest. These AQX files must be placed on the device memory like an on-board map, and selected be added to the stored map list.

The AQX file format

The AQX format used to create custom stored maps requires only few information.

Basic example

Here is a simple example to access an OSM-like tile server:

example_1.aqx
<?xml version="1.0" encoding="utf-8"?>
<aqx version="3">
 
  <name>Map Examples</name>
 
  <source id="ID1">
    <name>Map Example</name>
    <level type="rest">
      <zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>
      <servers>
        <server>http://server1.example.com/tiles/{$z}/{$x}/{$y}.png</server>
        <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
        <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
      </servers>
    </level>
  </source>
 
</aqx>



This example is composed of the following required elements:

  • The generic XML and AQX declarations:
<?xml version="1.0" encoding="utf-8"?>
<aqx version="3">


  • The name of the AQX file maps set:
<name>Map Examples</name>


  • The definition of the first map inside the AQX file:
<source id="ID1">

The “id” attribute value must be unique inside the file, and is used to create the cache storage file.
Other maps can be added to the file.

  • The name of the map:
<name>Map Example</name>


  • The definition of the zoom levels of the map:
<level type="rest">

The “type” attribute specify type of the tile server being accessed. Use “rest” for OSM-like server.

  • The zoom values being used for this map:
<zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>


  • The URL of the tile servers:
<servers>
  <server>http://server1.example.com/tiles/{$z}/{$x}/{$y}.png</server>
  <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
  <server>http://server3.example.com/tiles/{$z}/{$x}/{$y}.png</server>
</servers>

Any number of “<server>” tag can be added.
The {$x}, {$y} and {$z} variables are used to define the tiles.

Advanced example

In addition to the required tags, additional ones are available:

example_2.aqx
<?xml version="1.0" encoding="utf-8"?>
<aqx version="3">
 
  <name>Map Examples</name>
 
  <source id="ID1_1">
    <name>Map Example 1</name>
    <description>Description</description>
    <data-source>http://www.example.com/viewer/</data-source>
    <outline>2.54,49.49 2.54,51.51 6.41,51.51 6.41,49.49</outline>
    <copyright>2014 Example</copyright>
    <icon-data>(base 64 encoded 69*69px icon data)</icon-data>
    <level type="rest">
      <zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>
      <tiles-size>256</tiles-size>
      <update-delay>None</update-delay>
      <servers>
        <referer>http://server1.example.com/</referer>
        <max-threads>2</max-threads>
        <server>http://server1.example.com/tiles/{$z}/{$x}/{$y}.png</server>
        <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
        <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
      </servers>
    </level>
  </source>
 
  <source id="ID1_2" layer="true">
    <name>Map Example 2</name>
    <description><![CDATA[<html>HTML description...</html>]]></description>
    <level type="rest">
      <zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>
      <server>http://server.example.com/tiles/{$z}/{$x}/{$y}.png</server>
    </level>
  </source>
 
</aqx>

Quadtree encoded tiles

Instead of using the classical {$x} / {$y} / {$z} variables, you can use the {$q} variable that contains the quadtree encoded coordinates of the tiles, like in this example:

  <source id="ID2">
    <name>Quadtree Map Example</name>
    <level type="rest">
      <zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>
      <servers>
        <server>http://server1.example.com/tiles/{$q}</server>
        <server>http://server2.example.com/tiles/{$q}</server>
        <server>http://server3.example.com/tiles/{$q}</server>
      </servers>
    </level>
  </source>

Custom variables / Expression

In addition to the variables provided by default, you can create your own variables defined by mathematical expressions for each levels:

  <source id="ID3">
    <name>Expressions Map Example</name>
    <level type="rest">
      <zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>
      <expression set="k" type="int">iif( z>10, x*y, x+y )</expression>
      <servers>
        <server>http://server.example.com/tiles/{$k}.png</server>
      </servers>
    </level>
  </source>

The “set” attribute defines the name of the new variable, the “type” attribute tells that the result should be displayed as an integer when using it.

WMS servers

To access WMS servers, you must use the level type wms. The application will then replace the {$bbox} variable by the tile coordinates.

You can specify the coordinate system of the bounding box using the <bbox-crs-code> tag.

Here is an example of how to access tiles from a WMS server:

  <source id="ID4">
    <name>WMS Map Example</name>
    <level type="wms">
      <zoom-values>5,7,9,11,12,13,14,15,16,17</zoom-values>
      <servers>
        <bbox-crs-code>EPSG:4326</bbox-crs-code>
        <server><![CDATA[http://server.example.com/wms/Service?REQUEST=GetMap&VERSION=1.1.1&LAYERS=layer&FORMAT=image/png&BBOX={$bbox}&SRS=EPSG:4326&WIDTH=256&HEIGHT=256]]></server>
      </servers>
    </level>
  </source>

WMTS servers

To access WMTS servers, you need to manually configure each levels:

  <source id="ID5">
    <name>WMTS Map Example</name>
 
    <level type="rest">
      <zoom-values>8</zoom-values>
      <projection-code>EPSG:4218</projection-code>
      <projection-resolution>2.645833333</projection-resolution>
      <projection-offset-x>-450000.0</projection-offset-x><!-- optional, default is 0 -->
      <projection-offset-y>-800000.0</projection-offset-y><!-- optional, default is 0 -->
      <tiles-size>256</tiles-size><!-- optional, default is 256 -->
      <tiles-bounds>104,80,527,423</tiles-bounds><!-- optional -->
      <referer>http://server.example.com/wmts/</referer><!-- optional, default is empty -->
      <server>http://server.example.com/wmts/{$z}/{$y}/{$x}.png</server>
    </level>
 
    <level type="rest">
      <zoom-values>9</zoom-values>
      <projection-code>EPSG:4218</projection-code>
      <projection-resolution>1.322916667</projection-resolution>
      <projection-offset-x>-450000.0</projection-offset-x><!-- optional, default is 0 -->
      <projection-offset-y>-800000.0</projection-offset-y><!-- optional, default is 0 -->
      <tiles-size>256</tiles-size><!-- optional, default is 256 -->
      <tiles-bounds>208,160,1047,839</tiles-bounds><!-- optional -->
      <referer>http://server.example.com/wmts/</referer><!-- optional, default is empty -->
      <server>http://server.example.com/wmts/{$z}/{$y}/{$x}.png</server>
    </level>
 
  </source>

To get the <projection-resolution> from a ScaleDenominator, just multiply this value by 0.00028 (which is the “standardized rendering pixel size”, in meter).

Mixed servers

You can also create maps that use different services based on the zoom levels:

  <source id="ID6">
    <name>Mixed Map Example</name>
 
    <level type="rest">
      <zoom-values>5,7,9,11,12</zoom-values>
      <servers>
        <server>http://server1.example.com/tiles/{$z}/{$x}/{$y}.png</server>
        <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
        <server>http://server2.example.com/tiles/{$z}/{$x}/{$y}.png</server>
      </servers>
    </level>
 
    <level type="wms">
      <zoom-values>13,14,15,16,17</zoom-values>
      <servers>
        <bbox-crs-code>EPSG:4326</bbox-crs-code>
        <server><![CDATA[http://server.example.com/wms/Service?REQUEST=GetMap&VERSION=1.1.1&LAYERS=layer&FORMAT=image/png&BBOX={$bbox}&SRS=EPSG:4326&WIDTH=256&HEIGHT=256]]></server>
      </servers>
    </level>
 
  </source>