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:v2:maps:on-demand-create [2020/12/01 10:33] – [AQX versions] alpinequesten:help:v2:maps:on-demand-create [2021/07/22 21:55] alpinequest
Line 20: Line 20:
   <description>© OpenStreetMap</description>   <description>© OpenStreetMap</description>
  
-  <source id="MAP01">+  <source id="MAP_UID">
     <name>Standard Mapnik</name>     <name>Standard Mapnik</name>
     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
Line 35: Line 35:
 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 should only contain characters and numbers. It is used internally by the application to identify the data storage of the map.
  
 \\ \\
Line 50: Line 50:
   <description>© OpenStreetMap</description>   <description>© OpenStreetMap</description>
  
-  <source id="MAP01" type="topo">+  <source id="MAP_UID" type="topo">
      
     <name>Standard Mapnik</name>     <name>Standard Mapnik</name>
Line 75: Line 75:
 </aqx> </aqx>
 </file> </file>
 +
 +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**"''.
  
 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. 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.
Line 83: Line 85:
 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 ''**<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**"''.+You can limit the number of threads used to download the map using the ''**<max-threads>**'' tag. The default and maximum value is ''**3**''
 + 
 +The ''**<key-url>**'' tag can be used to provide a link to the key (legend) of the map. The map key is available from the menu of a map. 
 + 
 +The ''**<user-agent>**'' and ''**<referer>**'' tags allow you to specify what is sent in the HTTP get headers when contacting the map server. 
 + 
 +\\
  
-==== Map layer ====+===== 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: 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> <code xml>
-  <source id="LAYER01" layer="true" opacity="50">+  <source id="MAP_UID" layer="true" opacity="50">
     <name>Map Layer Example</name>     <name>Map Layer Example</name>
     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
Line 107: Line 115:
  
 <code xml> <code xml>
-  <source id="MAP02">+  <source id="MAP_UID">
     <name>Quadtree Map Example</name>     <name>Quadtree Map Example</name>
     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
Line 117: Line 125:
 \\ \\
  
-===== Custom variables =====+===== Force a particular map projection =====
 \\ \\
-In addition to the variables provided by default, you can create your own variables defined by mathematical expressions:+By default, the application uses the "WGS 84 / Pseudo-Mercator" (EPSG:3857) map projection. You can force a different map projection using the ''**<projection-code>**'' tag:
  
 <code xml> <code xml>
-  <source id="MAP03"> +  <source id="MAP_UID_1"> 
-    <name>Custom Variables Map Example</name> +    <name>KKJ/4 Projection</name> 
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17"> +    <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+      <projection-code>EPSG:2394</projection-code
-      <server><![CDATA[https://map.example.com/tiles/{$my_variable}.png]]></server>+      <server><![CDATA[https://map.example.com/tiles/{$z}/{$x}/{$y}]]></server>
     </zoom-levels>     </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**"'').+In case you want to use map projection which is not known by the applicationyou can import its WKT definition:
  
-Most common functions and operators can be usedfor 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.+<code xml> 
 +  <import-ogc-wkt-def code="MY_2394_DEF">PROJCS["KKJ / Finland zone 4",GEOGCS["KKJ",DATUM["Kartastokoordinaattijarjestelma_1966",SPHEROID["International 1924",6378388,297,AUTHORITY["EPSG","7022"]],AUTHORITY["EPSG","6123"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.01745329251994328,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4123"]],UNIT["metre",1,AUTHORITY["EPSG","9001"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",30],PARAMETER["scale_factor",1],PARAMETER["false_easting",4500000],PARAMETER["false_northing",0],AUTHORITY["EPSG","2394"],AXIS["Y",EAST],AXIS["X",NORTH]]</import-ogc-wkt-def> 
 +  <source id="MAP_UID_2"> 
 +    <name>KKJ/4 Projection</name> 
 +    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">     
 +      <projection-code>MY_2394_DEF</projection-code> 
 +      <server><![CDATA[https://map.example.com/tiles/{$z}/{$x}/{$y}]]></server> 
 +    </zoom-levels> 
 +  </source> 
 +</code>
  
 \\ \\
Line 142: Line 159:
  
 <code xml> <code xml>
-  <source id="MAP04">+  <source id="MAP_UID">
     <name>WMS Map Example</name>     <name>WMS Map Example</name>
     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">     <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
Line 164: Line 181:
   <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>   <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">+  <source id="MAP_UID">
     <name>WMTS Map Example</name>     <name>WMTS Map Example</name>
          
Line 201: Line 218:
  
 ===== Advanced features ===== ===== Advanced features =====
 +
 +==== Custom variables ====
 +\\
 +In addition to the variables provided by default, you can create your own variables defined by mathematical expressions:
 +
 +<code xml>
 +  <source id="MAP_UID">
 +    <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>
 +</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**"'').
 +
 +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.
 +
 +[[en:help:v2:maps:on-demand-create#inline_expressions|See here for more details on available operators and functions.]]
 +
 +\\
 +
 +==== Global parameters ====
 +\\
 +You can declare parameters at the file level, which may be useful to store a key or a token that is used in multiple places within the file.
 +
 +<code xml>
 +<?xml version="1.0" encoding="utf-8" ?>
 +<aqx version="9">
 +
 +  <name>Test global parameter</name>
 +
 +  <param name="key">8451-5814-5311</param>
 +
 +  <source id="MAP_UID_1">
 +    <name>Map 1</name>
 +    <zoom-levels z="5,6,7,8,9,10,11,12,13,14,15">
 +      <server><![CDATA[https://example.server.com/style1/{$z}/{$x}/{$y}?token={$param:key}]]></server>
 +    </zoom-levels>
 +  </source>
 +
 +  <source id="MAP_UID_2">
 +    <name>Map 2</name>
 +    <zoom-levels z="5,6,7,8,9,10,11,12,13,14,15">
 +      <server><![CDATA[https://example.server.com/style2/{$z}/{$x}/{$y}?token={$param:key}]]></server>
 +    </zoom-levels>
 +  </source>
 +
 +</aqx>
 +</code>
 +
 +\\
  
 ==== Make a color or a color range transparent ==== ==== Make a color or a color range transparent ====
Line 230: Line 300:
 \\ \\
  
-===== AQX versions =====+==== Send cookies or headers to the map server ==== 
 +\\ 
 +You can send headers using the ''**<header>**''" tag and cookies using the ''**<cookies>**'' tag, as shown in the example below: 
 + 
 +<code xml> 
 +   ... 
 +    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17"> 
 +      <header>Accept: */*</header> 
 +      <cookie>_usr_name=Name;_usr_password=123</cookie> 
 +      ... 
 +    </zoom-levels> 
 +   ... 
 +</code> 
 + 
 +\\ 
 + 
 +===== Appendices ===== 
 + 
 +==== AQX versions ====
 \\ \\
 ^  AQX file version  ^  Min. app version  ^  Notable changes  ^ ^  AQX file version  ^  Min. app version  ^  Notable changes  ^
Line 237: Line 325:
 |  8  |  2.0.0  | Added support for ''**zoom-level**'' and ''**zoom-levels**'' definitions. Added support for ''**replace**'' and ''**format**'' functions.  | |  8  |  2.0.0  | Added support for ''**zoom-level**'' and ''**zoom-levels**'' definitions. Added support for ''**replace**'' and ''**format**'' functions.  |
  
 +\\
 +
 +==== Inline expressions ====
 +
 +\\
 +
 +=== List of operators ===
 +
 +^ Operator  ^ Note  ^
 +|  ''**+**''  | Additive operator (also used for string concatenation).  |
 +|  ''**-**''  | Subtraction operator.  |
 +|  ''*****''  | Multiplication operator.  |
 +|  ''**/**''  | Division operator.  |
 +|  ''**%**''  | Remainder operator.  |
 +|  ''**^**''  | Power operator.  |
 +|  ''**==**''  | Equal to operator (also used for string).  |
 +|  ''**!=**'' <sup>1</sup>  | Not equal to operator (also used for string).  |
 +|  ''**>**''  | Greater than operator.  |
 +|  ''**> =**''  | Greater than or equal to operator.  |
 +|  ''**<**''  | Less than operator.  |
 +|  ''**< =**''  | Less than or equal to operator.  |
 +|  ''**&&**''  | Conditional AND operator.  |
 +|  ''**||**''  | Conditional OR operator.  |
 +|  ''**!**''  | Logical complement operator.  |
 +|  ''**< <**''  | Signed left shift operator.  |
 +|  ''**> >**''  | Signed right shift operator.  |
 +<sup>1. Available from AQ 2.2.8c</sup>
 +
 +
 +=== List of variables ===
 +
 +^ Variable  ^ Note  ^
 +|  ''**c**''  | The speed of light in vacuum.  |
 +|  ''**e**''  | Euler's number.  |
 +|  ''**h**''  | Planck's constant.  |
 +|  ''**k**''  | Boltzmann's constant.  |
 +|  ''**pi**''  | The number ''π'' |
 +|  ''**q**''  | The elementary charge.  |
 +
 +
 +=== List of common functions ===
 +
 +^ Function  ^ Return type  ^ Note  ^
 +| ''**abs**(double)''  | ''double''  | Returns the absolute value of a double value.  |
 +| ''**acos**(double)''  | ''double''  | Returns the arc cosine of a value; the returned angle is in the range ''0.0'' through ''π'' |
 +| ''**asin**(double)''  | ''double''  | Returns the arc sine of a value; the returned angle is in the range ''-π÷2'' through ''π÷2'' |
 +| ''**atan**(double)''  | ''double''  | Returns the arc tangent of a value; the returned angle is in the range ''-π÷2'' through ''π÷2'' |
 +| ''**ceil**(double)''  | ''long''  | Returns the smallest (closest to negative infinity) double value that is greater than or equal to the argument and is equal to a mathematical integer.  |
 +| ''**charAt**(string,long)''  | ''string''  | Returns the char value at the specified index.  |
 +| ''**cos**(double)''  | ''double''  | Returns the trigonometric cosine of an angle.  |
 +| ''**exp**(double)''  | ''double''  | Returns Euler's number ''e'' raised to the power of a double value.  |
 +| ''**fact**(long)''  | ''long''  | Return the product of all positive integers less than or equal to the specified value.  |
 +| ''**floor**(double)''  | ''long''  | Returns the largest (closest to positive infinity) double value that is less than or equal to the argument and is equal to a mathematical integer.  |
 +| ''**format**(string,double)''  | ''string''  | Returns a formatted string of the second parameter value, using the format string specified by the first parameter. [[https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax|See here for the format details]].  |
 +| ''**hypot**(double,double)''  | ''double''  | Returns ''sqrt(x²+y²)'' without intermediate overflow or underflow.  |
 +| ''**iif**(double,mixed,mixed)''  | ''mixed''  | If the first parameter is different from ''0.0'', return the second parameter, else the third one.  |
 +| ''**len**(string), **length**(string)''  | ''long''  | Returns the length of a string.  |
 +| ''**ln**(double)''  | ''double''  | Returns the natural logarithm (base ''e'') of a double value.  |
 +| ''**log**(double)''  | ''double''  | Returns the base 10 logarithm of a double value.  |
 +| ''**not**(double)''  | ''long''  | If the parameter is different from ''0.0'', return ''0'', else return ''1'' |
 +| ''**pow**(double,double)''  | ''double''  | Returns the value of the first argument raised to the power of the second argument.  |
 +| ''**replace**(string,string,string)''  | ''string''  | Replaces each substring of a string (first parameter) that matches the literal target sequence (second parameter) with the specified literal replacement sequence (third parameter).  |
 +| ''**round**(double)''  | ''long''  | Returns the closest long to the argument, with ties rounding to positive infinity.  |
 +| ''**sin**(double)'' <sup>1</sup>  | ''double''  | Returns the trigonometric sine of an angle.  |
 +| ''**sqrt**(double)''  | ''double''  | Returns the correctly rounded positive square root of a double value.  |
 +| ''**substr**(string,long)''  | ''string''  | Returns a string that is a substring of the string given in the first parameter. The substring begins with the character at the index specified by the second parameter and extends to the end of the string.  |
 +| ''**substr**(string,long,long)''  | ''string''  | Returns a string that is a substring the string given in the first parameter. The substring begins with the character at the index specified by the second parameter and extends to the character at the index specified by the third parameter, minus 1.  |
 +| ''**tan**(double)''  | ''double''  | Returns the trigonometric tangent of an angle.  |
 +| ''**toDouble**(mixed)''  | ''double''  | Returns a double holding the value represented by the argument. If the parameter is a long or double, the same value is returned. If the parameter is a string, it will be converted to a double value using [[https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-|this method]].  |
 +| ''**toLong**(mixed)''  | ''long''  | Returns a long holding the value represented by the argument. If the parameter is a long, the same value is returned. If the parameter is a double, the rounded value is returned. If the parameter is a string, it will be converted to a long value using [[https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#valueOf-java.lang.String-|this method]].  |
 +| ''**toString**(mixed)''  | ''string''  | Returns a string representing the value represented by the argument. If the parameter is a long, it is returned as a signed decimal representation. If the parameter is a double, it is returned as a string that represents its sign and magnitude (absolute value). If the parameter is a string, the same value is returned.  |
 +| ''**toString**(mixed,long)''  | ''string''  | Returns a string representing the value represented by the argument. If the parameter is a long, it is returned as a signed decimal representation in the radix specified by the second parameter. If the parameter is a double, it is returned as a string that represents its sign and magnitude (absolute value). If the parameter is a string, the same value is returned.  |
 +| ''**unixtime**()''  | ''long''  | Returns the current time in seconds.  |
 +| ''**unixtime**(long)''  | ''long''  | If the parameter is ''1'', returns the current time in milliseconds, otherwise returns the current time in seconds.  |
 +| ''**valueAt**(long,mixed...)''  | ''mixed''  | Returns the value at the index (starting from zero after the first parameter) specified by the first parameter.  |
 +<sup>1. Available from AQ 2.2.8c</sup>
  
  
 +=== List of specialized functions ===
  
 +^ Function  ^ Return type  ^ Note  ^
 +| ''**deg_to_rad**(double)''  | ''double''  | Converts from degrees to radians.  |
 +| ''**dist_eucl**(double,double,double,double)''  | ''double''  | Computes the Euclidean distance between to points ''x1'' (first parameter), ''y1'' (second parameter) and ''x2'' (third parameter), ''y2'' (fourth parameter) as defined by ''hypot( (x2-x1), (y2-y1) )'' |
 +| ''**md5**(string)''  | ''string''  | Returns the [[https://en.wikipedia.org/wiki/MD5|MD5 hash]] of the string parameter.  |
 +| ''**quadtree**(long,long,long)''  | ''string''  | Combines the x (first parameter), x (second parameter) and zoom (third parameter) values into a one-dimensional [[https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system?redirectedfrom=MSDN#tile-coordinates-and-quadkeys|quadtree key string]].  |
 +| ''**rad_to_deg**(double)''  | ''double''  | Converts from radians to degrees.  |
 +| ''**rand_uni**()''  | ''double''  | Returns a double value with a positive sign, greater than or equal to ''0.0'' and less than ''1.0''. Returned values are chosen pseudorandomly with (approximately) uniform distribution from that range.  |