Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Next revisionBoth sides next revision
en:help:maps:stored:custom [2016/02/08 17:01] – [Advanced example] psyberiaen: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> <sub>[[en:help|Online Help]] > [[en:help:maps|Maps & Layers]]</sub>
  
-====== How to create custom maps? ======+====== How to create 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: Here is a simple example to access the default [[http://www.openstreetmap.org/]] map:
  
 <file xml TEST1.AQX> <file xml TEST1.AQX>
 <?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="7">+<aqx version="9">
  
   <name>Simple Test AQX</name>   <name>Simple Test AQX</name>
Line 18: Line 22:
   <source id="MAP01">   <source id="MAP01">
     <name>Standard Mapnik</name>     <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>   </source>
  
Line 27: Line 32:
 This example will be displayed like this in the application: This example will be displayed like this in the application:
 {{ :en:help:maps:stored:custom-preview-1.jpg?nolink }} {{ :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. 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 ===== ===== Advanced example =====
 +\\
 A lot of optional fields have been omitted in the basic example, so here is a more complete example: A lot of optional fields have been omitted in the basic example, so here is a more complete example:
  
 <file xml TEST2.AQX> <file xml TEST2.AQX>
 <?xml version="1.0" encoding="utf-8" ?> <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="7">+<aqx version="9">
  
   <name>Simple Test AQX</name>   <name>Simple Test AQX</name>
   <description>© OpenStreetMap</description>   <description>© OpenStreetMap</description>
  
-  <source id="MAP01">+  <source id="MAP01" type="topo">
      
     <name>Standard Mapnik</name>     <name>Standard Mapnik</name>
Line 51: Line 58:
     <preview-location>5.90,44.80,12</preview-location>     <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>   </source>
  
Line 71: Line 81:
 {{ :en:help:maps:stored:custom-preview-2.jpg?nolink }} {{ :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: 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">   <source id="MAP02">
     <name>Quadtree Map Example</name>     <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>   </source>
 </code> </code>
  
-===== Custom variables =====+\\
  
 +===== Custom variables =====
 +\\
 In addition to the variables provided by default, you can create your own variables defined by mathematical expressions: 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">   <source id="MAP03">
     <name>Custom Variables Map Example</name>     <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>   </source>
 </code> </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. 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">   <source id="MAP04">
     <name>WMS Map Example</name>     <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>   </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> </code>