Differences

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

--- en:help:v2:maps:on-demand-create [2022/12/02 19:13] – alpinequest
+++ en:help:v2:maps:on-demand-create [2025/06/24 18:24] (current) – new function as of 2.4.0 psyberia
@@ Line 3: / Line 3: @@
 ====== 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/maps/**"'' folder.
+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 58: / 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="1,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 78: / 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 84: / 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 91: / 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 129: / 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>
@@ Line 141: / 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>
@@ Line 158: / 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>
@@ Line 169: / Line 176: @@
   </source>
 </code>
+In the server requires a bounding box with integer numbers, you can use the ''**{$ibbox}**'' variable instead of ''**{$bbox}**''.
 \\
-===== WMTS server =====
+===== WMTS and custom projection server =====
 \\
 To access WMTS servers, you need to manually configure each levels:
@@ Line 213: / 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).
+The application will transform a coordinate on Earth (in degrees) to an image tile (in pixels) as follow:\\
+  - Project the coordinate in degrees into a coordinate in meters, using a map projection. The map projection can be defined by one of the following method, depending on which tags are provided:
+    * By using the ''**<projection-code>**'' tag to specify the EPSG code of a //projected// coordinate system (PROJCS). The application will use the true and false origins as defined by the PROJCS. Exemple: \\ <code>
+<projection-code>EPSG:28992</projection-code></code>
+    * By using the ''**<projection-code>**'' tag to specify the EPSG code of a //geodetic// coordinate system (GEOCS). Such GEOCS do not define true and false origins. The true origin (which can be seen as an offset applied before calling the map projection) can be applied using the ''**<projection-true-origin-x>**'' and ''**<projection-true-origin-y>**'' tags (usually in degrees). Exemple: \\ <code>
+<projection-code>EPSG:4326</projection-code>
+<projection-true-origin-x>-125.0</projection-true-origin-x>
+<projection-true-origin-y>15.0</projection-true-origin-y></code>
+    * By using the ''**<projection-name>**'' and ''**<projection-geoid>**'' tags to specify the name of a map projection. In this case too, the ''**<projection-true-origin-x>**'' and ''**<projection-true-origin-y>**'' tags are taken into account. Exemple: \\ <code><projection-name>mercator</projection-name>
+<projection-geoid>WGS 84</projection-geoid></code>
+  - Apply an optional false origin (which can be seen as an offset applied after calling the map projection), by using the ''**<projection-false-origin-x>**'' and ''**<projection-false-origin-y>**'' tags (usually in meters). Exemple: \\ <code><projection-false-origin-x>-285400.00</projection-false-origin-x>
+<projection-false-origin-y>903400.0</projection-false-origin-y></code>
+  - Convert the coordinate in meters to a coordinate in tiles, using one of the following method depending on which tags are provided:
+    * By using the ''**<projection-factor-x>**'' and ''**<projection-factor-y>**'' tags (in tiles/m) and the ''**<projection-offset-x>**'' and ''**<projection-offset-y>**'' tags (in tiles).
+    * By using the ''**<projection-resolution>**'' tag (in m/px). If the tiles are not 256px in size, this one must be defined by the ''**<tiles-size>**'' or ''**<tiles-size-x>**'' and ''**<tiles-size-y>**'' tags (in px). The application will compute the correct factor to apply using the formula ''projection-factor-x = ( 1.0 / ( projection-resolution * tiles-size-x ) )'' and ''projection-factor-y = ( 1.0 / ( projection-resolution * tiles-size-y ) )''.
+    * By using the ''**<projection-scale-denominator>**'' tag (ratio, no units). The application will compute the projection resolution using the formula ''projection-resolution = ( projection-scale-denominator * 0.00028 )'', and then proceed as above using the computed projection-resolution. Note that ''0.00028'' is the standardized rendering pixel size.
+    * By computing automatically the projection factor and offset, if none of the above tags are provided. In this case the application uses the standard OpenStreetMap zoom levels scales.
 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 238: / Line 264: @@
 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 322: / Line 350: @@
 ===== Appendices =====
-==== AQX versions ====
 \\
-^  AQX file version  ^  Min. app version  ^  Notable changes  ^
-|  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.  |
+==== Supported map projections ====
-|  11  |  2.3.0  | Added support for ''**polar stereographic**'' projections.  |
-|  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.  |
+^ EPSG Code  ^ Names  ^
-|  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.  |
+| 1024  | Popular Visualisation Pseudo Mercator, Mercator Auxiliary Sphere  |
-|  8  |  2.0.0  | Added support for ''**zoom-level**'' and ''**zoom-levels**'' definitions. Added support for ''**replace**'' and ''**format**'' functions.  |
+| 1026  | Mercator Spherical  |
+| 1028  | Equidistant Cylindrical, Equirectangular  |
+| 1029  | Equidistant Cylindrical (Spherical)  |
+| 9801  | Lambert Conic Conformal (1SP)  |
+| 9802  | Lambert Conic Conformal (2SP)  |
+| 9803  | Lambert Conic Conformal (2SP Belgium)  |
+| 9804  | Mercator (1SP), Mercator (Variant A)  |
+| 9805  | Mercator (2SP), Mercator (Variant B)  |
+| 9806  | Cassini Soldner  |
+| 9807  | Transverse Mercator, Gauss Boaga, Gass Kruger  |
+| 9808  | Transverse Mercator (South Orientated)  |
+| 9809  | Stereographic, Oblique Stereographic, Double Stereographic, Roussilhe  |
+| 9810  | Polar Stereographic (Variant A)  |
+| 9812  | Hotine Oblique Mercator, Hotine Oblique Mercator (Variant A)  |
+| 9815  | Oblique Mercator, Hotine Oblique Mercator (Variant B), Hotine Oblique Mercator Azimuth Center  |
+| 9817  | Lambert Conic Near Conformal  |
+| 9823  | C.f. 1029  |
+| 9825  | Pseudo Plate Carree  |
+| 9826  | Lambert Conic Conformal (West Orientated)  |
+| 9827  | Bonne  |
+| 9828  | Bonne (South Orientated)  |
+| 9829  | Polar Stereographic (Variant B)  |
+| 9842  | C.f. 1028  |
 \\
@@ Line 347: / Line 396: @@
 |  ''**^**''  | Power operator.  |
 |  ''**==**''  | Equal to operator (also used for string).  |
-|  ''**!=**'' <sup>1</sup>  | Not equal to operator (also used for string).  |
+|  ''**!=**''  | Not equal to operator (also used for string).  |
 |  ''**>**''  | Greater than operator.  |
 |  ''**> =**''  | Greater than or equal to operator.  |
@@ Line 357: / Line 406: @@
 |  ''**< <**''  | Signed left shift operator.  |
 |  ''**> >**''  | Signed right shift operator.  |
-<sup>1. Available from AQ 2.2.8c</sup>
@@ Line 390: / Line 438: @@
 | ''**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.  |
+| ''**indexOf**(string,string)''  | ''long''  | Returns the position of the first occurrence of the second parameter inside the first parameter.  |
+| ''**lastIndexOf**(string,string)''  | ''long''  | Returns the position of the last occurrence of the second parameter inside the first parameter.  |
 | ''**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.  |
+| ''**lower**(string)''  | ''string''  | Returns parameter as lower case.  |
 | ''**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''.  |
@@ Line 402: / Line 453: @@
 | ''**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.  |
+| ''**sin**(double)''  | ''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.  |
@@ Line 413: / Line 464: @@
 | ''**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.  |
+| ''**upper**(string)''  | ''string''  | Returns parameter as upper case.  |
 | ''**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>
+\\
+==== AQX versions ====
+\\
+^  AQX file version  ^  Min. app version  ^  Notable changes  ^
+|  13  |  2.3.9b  | Added support for dynamic map parameters, including Yeti service input form.  |
+|  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.  |
+|  11  |  2.3.0  | Added support for ''**polar stereographic**'' projections.  |
+|  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.  |