This is an old revision of the document!


Online Help > AlpineQuest 2.x > Maps & Layers

How to create a custom map?


The application uses an XML based format for its maps configuration. Files must have an .aqx extension and be placed in the [application folder]/datastore/custom-maps/ folder (you may need to create the custom-maps sub-folder if it doesn't exist).

See how to locate the application folder here.


Basic example


Here is a simple example to access the default http://www.openstreetmap.org/ map:

TEST1.AQX
<?xml version="1.0" encoding="utf-8" ?>
<aqx version="9">
 
  <name>Simple Test AQX</name>
  <description>© OpenStreetMap</description>
 
  <source id="MAP01">
    <name>Standard Mapnik</name>
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <server><![CDATA[https://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
    </zoom-levels>
  </source>
 
</aqx>

This example will be displayed like this in the application: on-demand-create-preview-1.jpg

Note that the application will recognize the {$x}, {$y} and {$z} variable and replace them with correct values.

The source id field must be unique in the file, and contains only characters and numbers. It is used internally by the application to identify the data storage of the map.


Advanced example


A lot of optional fields have been omitted in the basic example, so here is a more complete example:

TEST2.AQX
<?xml version="1.0" encoding="utf-8" ?>
<aqx version="9">
 
  <name>Simple Test AQX</name>
  <description>© OpenStreetMap</description>
 
  <source id="MAP01" type="topo">
 
    <name>Standard Mapnik</name>
 
    <outline>2.54,49.49 2.54,51.51 6.41,51.51 6.41,49.49</outline>
    <preview-location>5.90,44.80,12</preview-location>
 
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
 
      <update-delay>3M</update-delay>
      <max-threads>2</max-threads>
      <user-agent>MyApp</user-agent>
      <key-url><![CDATA[https://www.openstreetmap.org/key]]></key-url>
      <referer><![CDATA[https://www.openstreetmap.org/]]></referer>
 
      <server><![CDATA[https://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
      <server><![CDATA[https://b.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
      <server><![CDATA[https://c.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
 
    </zoom-levels>
 
  </source>
 
</aqx>

An <outline> tag (pairs of longitudes/latitudes, space separated) can be used to define the area covered by the map. When the map is selected while another area is displayed, the application will ask the user if he wants to move the map over the covered area.

The <preview-location> tag (approximate longitude, latitude and OSM zoom id) allows the application to display the map with a preview background: on-demand-create-preview-2.jpg

The <update-delay> tag indicates after how many time the stored map data should be updated if it's used again. The default is None, meaning the application will never try to update the stored data. Must end with D (number of days), W (weeks), M (months) or Y (years). For example, 3M means 3 months. Use 0D to force the application to update the data on each display.

The optional type attribute allows to define the type of the map. If no preview is available, the application will use common preview based on the map type. Can be one of roads, topo, satellite, hybrid, nautical, aeronautical, historical, hillshade, contours.

Map layer


The difference between regular maps and map layers is that a map layer is added over the current map when being selected. This is usually used for maps having a transparent background. Here is how to define a map layer:

  <source id="LAYER01" layer="true" opacity="50">
    <name>Map Layer Example</name>
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <server><![CDATA[https://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
    </zoom-levels>
  </source>

The optional opacity attribute allows to define an initial opacity, given in percent.


Quadtree encoded tiles


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

  <source id="MAP02">
    <name>Quadtree Map Example</name>
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <server><![CDATA[https://map.example.com/tiles/{$q}]]></server>
    </zoom-levels>
  </source>


Custom variables


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

  <source id="MAP03">
    <name>Custom Variables Map Example</name>
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <expression set="my_variable" type="int">iif( z>10, x*y, x+y )</expression>
      <server><![CDATA[https://map.example.com/tiles/{$my_variable}.png]]></server>
    </zoom-levels>
  </source>

The set attribute defines the name of the custom variable, the type attribute tells how to display the variable (either int, long, float or double).

Most common functions and operators can be used, for example abs(x), sqrt(x), hypot(x,y), cos(x), charat(str,index), replace(str,target,replace), deg_to_rad(x), dist_eucl(x1,y1,x2,y2), md5(str), rand_uni(), quadtree(x,y,z), etc.


WMS servers


To access WMS servers, just use the {$bbox} variable. You can specify the coordinate system of the bounding box using the <bbox-crs-code> tag.

  <source id="MAP04">
    <name>WMS Map Example</name>
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <bbox-crs-code>EPSG:4326</bbox-crs-code>
      <server><![CDATA[https://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>
    </zoom-levels>
  </source>


WMTS server


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

<?xml version="1.0" encoding="utf-8" ?>
<aqx version="9">
 
  <import-ogc-wkt-def code="EPSG:4218">GEOGCS["Bogota 1975",DATUM["Bogota_1975",SPHEROID["International 1924",6378388,297,AUTHORITY["EPSG","7022"]],TOWGS84[307,304,-318,0,0,0,0],AUTHORITY["EPSG","6218"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4218"]]</import-ogc-wkt-def>
 
  <source id="MAP05">
    <name>WMTS Map Example</name>
 
    <zoom-levels z="8">
      <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, expressed as "min x,min y,max x,max y" -->
      <referer>https://server.example.com/wmts/</referer><!-- optional, default is empty -->
      <server>https://server.example.com/wmts/{$z}/{$y}/{$x}.png</server>
    </zoom-levels>
 
     <zoom-levels z="9">
      <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>https://server.example.com/wmts/</referer><!-- optional, default is empty -->
      <server>https://server.example.com/wmts/{$z}/{$y}/{$x}.png</server>
    </zoom-levels>
 
  </source>
 
</aqx>

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

If you want to use a projection which is not natively supported by the application, you need to import its definition using the <import-ogc-wkt-def> tag. You can find the OGC WKT definition of almost all projections here: http://www.spatialreference.org/.


Advanced features

Make a color or a color range transparent


You can make a color become transparent (erase the color) of any map. Just specify the RGB values of the color:

   ...
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <clear-color r="255" g="255" b="255" />
      ...
    </zoom-levels>
   ...

This example will make all white areas transparent.

You can also clear a color range:

   ...
    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
      <clear-color r="240-255" g="240-255" b="240-255" />
      ...
    </zoom-levels>
   ...

AQX versions

Version Min. app version Notable changes
10 2.2.5 Added support for composite sources. Added support for insecure parameter. Added support for unixtime and tostring(int,radix) functions. Added support for {$y!} variable.
9 2.0.4 Added support for default-location tag. Added support for china-offset and clear-color parameters. Added support for md5 function. Sources parameter opacity expressed in percent (0-100) instead of 0-255.
8 2.0.0 Added support for zoom-level and zoom-levels definitions. Added support for replace and format functions.