Differences

This shows you the differences between two versions of the page.

--- en:help:maps:stored:custom [2016/09/08 18:59] – psyberia
+++ en:help:maps:stored:custom [2019/05/01 09:55] – alpinequest
@@ Line 1: / Line 1: @@
 <sub>[[en:help|Online Help]] > [[en:help:maps|Maps & Layers]]</sub>
-====== How to create custom maps? ======
+====== How to create a custom map? ======
+\\
+The application uses an XML based format for its maps configuration. Files must have an ''"**.aqx**"'' extention and be placed in the ''"**[application folder]/cache/custom-maps/**"'' folder.
-The application uses an XML based format for its maps configuration. Files must have an ''**.AQX**'' extention and be placed in the "''**[application folder]/cache/custom-maps/**''" folder.
+See [[en:help:settings:storage#how_to_locate_the_application_folder|how to locate the application folder here]].
-===== Basic example =====
+\\
+===== Basic example =====
+\\
 Here is a simple example to access the default [[http://www.openstreetmap.org/]] map:
 <file xml TEST1.AQX>
 <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="7">
+<aqx version="9">
   <name>Simple Test AQX</name>
@@ Line 18: / Line 22: @@
   <source id="MAP01">
     <name>Standard Mapnik</name>
-    <zoom-values>3,5,7,8,9,10,11,12,13,14,15,16,17,18,19</zoom-values>
+    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
-    <server><![CDATA[http://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
+      <server><![CDATA[http://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
+    </zoom-levels>
   </source>
@@ Line 27: / Line 32: @@
 This example will be displayed like this in the application:
 {{ :en:help:maps:stored:custom-preview-1.jpg?nolink }}
 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.
+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:
 <file xml TEST2.AQX>
 <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="7">
+<aqx version="9">
   <name>Simple Test AQX</name>
   <description>© OpenStreetMap</description>
-  <source id="MAP01">
+  <source id="MAP01" type="topo">
     <name>Standard Mapnik</name>
@@ Line 51: / Line 58: @@
     <preview-location>5.90,44.80,12</preview-location>
-    <zoom-values>3,5,7,8,9,10,11,12,13,14,15,16,17,18,19</zoom-values>
+    <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>
+      <update-delay>3M</update-delay>
-    <user-agent>MyApp</user-agent>
+      <max-threads>2</max-threads>
-    <referer><![CDATA[http://www.openstreetmap.org/]]></referer>
+      <user-agent>MyApp</user-agent>
+      <referer><![CDATA[http://www.openstreetmap.org/]]></referer>
+      <server><![CDATA[http://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
+      <server><![CDATA[http://b.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
+      <server><![CDATA[http://c.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
+    </zoom-levels>
-    <server><![CDATA[http://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
-    <server><![CDATA[http://b.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
-    <server><![CDATA[http://c.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
   </source>
@@ Line 71: / Line 81: @@
 {{ :en:help:maps:stored:custom-preview-2.jpg?nolink }}
-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). ''**3M**'' means ''**3 months**''. Use ''**0D**'' to force the application to update the data on each display.
+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.
-===== Quadtree encoded tiles =====
+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:
+<code xml>
+  <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[http://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
+    </zoom-levels>
+  </source>
+</code>
+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:
@@ Line 79: / Line 109: @@
   <source id="MAP02">
     <name>Quadtree Map Example</name>
-    <zoom-values>3,5,7,8,9,10,11,12,13,14,15,16,17,18,19</zoom-values>
+    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
-    <server><![CDATA[http://map.example.com/tiles/{$q}]]></server>
+      <server><![CDATA[http://map.example.com/tiles/{$q}]]></server>
+    </zoom-levels>
   </source>
 </code>
-===== Custom variables =====
+\\
+===== Custom variables =====
+\\
 In addition to the variables provided by default, you can create your own variables defined by mathematical expressions:
@@ Line 91: / Line 124: @@
   <source id="MAP03">
     <name>Custom Variables Map Example</name>
-    <zoom-values>3,5,7,8,9,10,11,12,13,14,15,16,17,18,19</zoom-values>
+    <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>
+      <expression set="my_variable" type="int">iif( z>10, x*y, x+y )</expression>
-    <server><![CDATA[http://map.example.com/tiles/{$my_variable}.png]]></server>
+      <server><![CDATA[http://map.example.com/tiles/{$my_variable}.png]]></server>
+    </zoom-levels>
   </source>
 </code>
-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**'').
+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**"'').
-===== WMS servers =====
+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.
@@ Line 106: / Line 144: @@
   <source id="MAP04">
     <name>WMS Map Example</name>
-    <zoom-values>3,5,7,8,9,10,11,12,13,14,15,16,17,18,19</zoom-values>
+    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
-    <bbox-crs-code>EPSG:4326</bbox-crs-code>
+      <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>
+      <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>
+    </zoom-levels>
   </source>
+</code>
+\\
+===== WMTS server =====
+\\
+To access WMTS servers, you need to manually configure each levels:
+<code xml>
+<?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 -->
+      <referer>http://server.example.com/wmts/</referer><!-- optional, default is empty -->
+      <server>http://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>http://server.example.com/wmts/</referer><!-- optional, default is empty -->
+      <server>http://server.example.com/wmts/{$z}/{$y}/{$x}.png</server>
+    </zoom-levels>
+  </source>
+</aqx>
+</code>
+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:
+<code xml>
+   ...
+    <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>
+   ...
+</code>
+This example will make all white areas transparent.
+You can also clear a color range:
+<code xml>
+   ...
+    <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>
+   ...
 </code>