Differences

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

--- en:help:v2:maps:on-demand-create [2022/05/26 18:22] – [Global parameters] alpinequest
+++ en:help:v2:maps:on-demand-create [2025/05/01 13:48] (current) – psyberia
@@ Line 1: / Line 1: @@
-<sub>[[en:help|Online Help]] > [[en:help:v2|AlpineQuest 2.x]] > [[en:help:v2:maps|Maps & Layers]]</sub>
+<sub>[[en:help|Online Help]] > [[en:help:v2|AlpineQuest 2.x]] > [[en:help:v2:maps|Maps & Layers]] > How to create a custom map?</sub>
 ====== 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).
+The application uses an XML based format for its custom on-demand maps configuration. Files must have an ''"**.aqx**"'' extension.
-See [[en:help:v2:settings:storage#how_to_locate_the_application_folder|how to locate the application folder here]].
+To import an ''"**.aqx**"'' configuration file, you can simply select it from your device file manager, and choose the application when asked which application to use to open the file. The file will be imported and the maps it contains will be added to the on-demand maps list.
+Alternatively, you can manually put the configuration file in the ''"**[application folder]/datastore/maps/**"'' folder. See [[en:help:v2:settings:storage#how_to_locate_the_application_folder|how to locate the application folder here]].
 \\
@@ Line 15: / Line 17: @@
 <file xml TEST1.AQX>
 <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="9">
+<aqx version="11">
   <name>Simple Test AQX</name>
@@ Line 22: / Line 24: @@
   <source id="MAP_UID">
     <name>Standard Mapnik</name>
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
+    <zoom-levels z="1-17">
       <server><![CDATA[https://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
     </zoom-levels>
@@ Line 34: / Line 36: @@
 Note that the application will recognize the ''**{$x}**'', ''**{$y}**'' and ''**{$z}**'' variable and replace them with correct values.
+If the map server uses the TMS standard (reversed y values compared to the Google/OSM standard), use ''**{$!y}**'' instead of ''**{$y}**''.
 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 45: / Line 49: @@
 <file xml TEST2.AQX>
 <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="9">
+<aqx version="11">
   <name>Simple Test AQX</name>
@@ Line 56: / Line 60: @@
     <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>
+    <default-location>5.90,44.80</default-location>
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
+    <zoom-levels z="1,3,5,7,8,9,10,11,12,13,14,15,16,17" insecure="true">
       <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>
+      <user-agent>MyApp</user-agent>
       <server><![CDATA[https://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
@@ Line 76: / Line 81: @@
 </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**"''.
+The ''"**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.
@@ Line 82: / Line 87: @@
 The ''**<preview-location>**'' tag (approximate longitude, latitude and OSM zoom id) allows the application to display the map with a preview background:
 {{ :en:help:v2:maps:on-demand-create-preview-2.jpg?nolink }}
+The ''**<default-location>**'' tag (longitude, latitude) defines the location to move on when this map is displayed over a location that is not covered.
+The ''"**insecure**"'' attribute tells the application to accepts all HTTPS certificates without checking them (usually fixes most SSL related issues).
 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.
@@ Line 89: / Line 98: @@
 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.
+The ''**<referer>**'' and ''**<user-agent>**'' tags allow you to specify what is sent in the HTTP get headers when contacting the map server.
 \\
@@ Line 100: / Line 109: @@
   <source id="MAP_UID" 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">
+    <zoom-levels z="1-17">
       <server><![CDATA[https://a.tile.openstreetmap.org/{$z}/{$x}/{$y}.png]]></server>
     </zoom-levels>
@@ Line 117: / Line 126: @@
   <source id="MAP_UID">
     <name>Quadtree Map Example</name>
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
+    <zoom-levels z="1-17">
       <server><![CDATA[https://map.example.com/tiles/{$q}]]></server>
     </zoom-levels>
@@ Line 127: / Line 136: @@
 ===== Force a particular map projection =====
 \\
-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:
+By default, the application uses the "WGS 84 / Pseudo-Mercator" map projection ([[https://epsg.io/3857|EPSG:3857]]). You can force a different map projection by using the ''**<projection-code>**'' tag:
 <code xml>
   <source id="MAP_UID_1">
     <name>KKJ/4 Projection</name>
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
+    <zoom-levels z="1-17">
       <projection-code>EPSG:2394</projection-code>
       <server><![CDATA[https://map.example.com/tiles/{$z}/{$x}/{$y}]]></server>
@@ Line 139: / Line 148: @@
 </code>
-In case you want to use map projection which is not known by the application, you can import its WKT definition:
+In case you want to use a map projection which is not known by the application, you can import its WKT or PROJ definition:
 <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>
+  <import-crs-txt-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-crs-txt-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">
+    <zoom-levels z="1-17">
       <projection-code>MY_2394_DEF</projection-code>
       <server><![CDATA[https://map.example.com/tiles/{$z}/{$x}/{$y}]]></server>
@@ Line 156: / Line 165: @@
 ===== 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 in place of the bounding box ''**BBOX**'' WMS parameter. You can specify the coordinate system of the bounding box using the ''**<bbox-crs-code>**'' tag ([[https://epsg.io/3857|EPSG:3857]] by default).
 <code xml>
   <source id="MAP_UID">
     <name>WMS Map Example</name>
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
+    <zoom-levels z="1-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>
@@ Line 167: / Line 176: @@
   </source>
 </code>
+In the server requires a bounding box with integer numbers, you can use the ''**{$ibbox}**'' variable instead of ''**{$bbox}**''.
 \\
@@ Line 177: / Line 188: @@
 <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="9">
+<aqx version="11">
   <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>
@@ Line 211: / Line 222: @@
 </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).
+To get the ''**<projection-resolution>**'' from a ''**ScaleDenominator**'', just multiply this value by ''**0.00028**'' (which is the "standardized rendering pixel size", in meters).
 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/]].
@@ Line 226: / Line 237: @@
   <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">
+    <zoom-levels z="1-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>
@@ Line 236: / Line 247: @@
 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.
+The ''**<expression>**'' tag and custom variables can only be used inside the zoom levels definition (i.e. a ''**<zoom-level>**'' and ''**<zoom-levels>**'' tag). The usual operator precedence is followed.
 [[en:help:v2:maps:on-demand-create#inline_expressions|See here for more details on available operators and functions.]]
@@ Line 249: / Line 262: @@
 <code xml>
 <?xml version="1.0" encoding="utf-8" ?>
-<aqx version="9">
+<aqx version="11">
   <name>Test global parameter</name>
@@ Line 257: / Line 270: @@
   <source id="MAP_UID_1">
     <name>Map 1</name>
-    <zoom-levels z="5,6,7,8,9,10,11,12,13,14,15">
+    <zoom-levels z="5-15">
       <server><![CDATA[https://example.server.com/style1/{$z}/{$x}/{$y}?token={$param:key}]]></server>
     </zoom-levels>
@@ Line 264: / Line 277: @@
   <source id="MAP_UID_2">
     <name>Map 2</name>
-    <zoom-levels z="5,6,7,8,9,10,11,12,13,14,15">
+    <zoom-levels z="5-15">
       <server><![CDATA[https://example.server.com/style2/{$z}/{$x}/{$y}?token={$param:key}]]></server>
     </zoom-levels>
@@ Line 308: / Line 321: @@
 <code xml>
    ...
-    <zoom-levels z="3,5,7,8,9,10,11,12,13,14,15,16,17">
+    <zoom-levels z="1-17">
       <header>Accept: */*</header>
       <cookie>_usr_name=Name;_usr_password=123</cookie>
@@ Line 319: / Line 332: @@
 ===== Appendices =====
-==== AQX versions ====
-\\
-^  AQX file 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.  |
-\\
 ==== Inline expressions ====
@@ Line 377: / Line 381: @@
 | ''**charAt**(string,long)''  | ''string''  | Returns the char value at the specified index.  |
 | ''**cos**(double)''  | ''double''  | Returns the trigonometric cosine of an angle.  |
+| ''**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) )''.  |
 | ''**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]]. Example: ''format("%tm",(unixtime(1)))'' gives the current month number with two digits.  |
+| ''**hash**(string,string)''  | ''string''  | Returns the hash of the second string parameter, using the algorithm given in the first string parameter.  |
 | ''**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.  |
@@ Line 386: / Line 393: @@
 | ''**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.  |
+| ''**md5**(string)''  | ''string''  | Returns the [[https://en.wikipedia.org/wiki/MD5|MD5 hash]] of the string parameter.  |
 | ''**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.  |
+| ''**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.  |
 | ''**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.  |
+| ''**sha1**(string)''  | ''string''  | Returns the [[https://en.wikipedia.org/wiki/SHA-1|SHA-1 hash]] of the string parameter.  |
 | ''**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.  |
@@ Line 404: / Line 416: @@
 <sup>1. Available from AQ 2.2.8c</sup>
+\\
-=== List of specialized functions ===
+==== AQX versions ====
+\\
-^ Function  ^ Return type  ^ Note  ^
+^  AQX file version  ^  Min. app version  ^  Notable changes  ^
-| ''**deg_to_rad**(double)''  | ''double''  | Converts from degrees to radians.  |
+|  13  |  2.3.9b  | Added support for dynamic map parameters, including Yeti service input form.  |
-| ''**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) )''.  |
+|  12  |  2.3.3  | Map resolution for geodetic CRS now expressed in deg/px instead of m/px. Default CRS for WMS BBOX is now EPSG:3857 (WGS 84 / Pseudo-Mercator). Added support for ''**sha1**'' and ''**hash**'' hash functions.  |
-| ''**md5**(string)''  | ''string''  | Returns the [[https://en.wikipedia.org/wiki/MD5|MD5 hash]] of the string parameter.  |
+|  11  |  2.3.0  | Added support for ''**polar stereographic**'' projections.  |
-| ''**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]].  |
+|  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.  |
-| ''**rad_to_deg**(double)''  | ''double''  | Converts from radians to degrees.  |
+|  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.  |
-| ''**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.  |
+|  8  |  2.0.0  | Added support for ''**zoom-level**'' and ''**zoom-levels**'' definitions. Added support for ''**replace**'' and ''**format**'' functions.  |