User Tools

Site Tools


manual:advanced:customization:online_maps

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:advanced:customization:online_maps [2015/05/22 14:45]
mstupka
manual:advanced:customization:online_maps [2019/07/03 16:33]
mstupka
Line 2: Line 2:
  
 ---- ----
-<WRAP todo round center 40%>Page under re-construction</WRAP>+
 ===== Basic information ===== ===== Basic information =====
  
-  * **required version:** 1.9.5 +  * **XML file** - contains description of Online map providers (more below). Name and path to this file on storage card (or internal memory) is ///CARD_ROOT/Locus/mapsOnline/custom/<somename>.xml// (you can have more than one xml in the folder, Locus Map will add all of them) 
-  * **XML file** - that contains description of Online map providers (more below). Name and path to this file on storage card (or internal memory) is ///CARD_ROOT/Locus/mapsOnline/custom/<somename>.xml// (you can have more than one xml in the folder, Locus will add all of them) +  * **PNG images (optional)** - for every map provider name. This icon is not required! It's just displayed next to the map name in the Map manager. Name of this icon should be the same as text in name tag.
-  * **PNG images (optional)** - for every map provider name. This icon is not required! It's just displayed next to maps in Online manager. Name of this icon should be same as text in name tag+
  
-===== Example map =====+===== Sample map =====
  
-Example of OpenPiste map (OSM based) created from three layers+A example of OpenPiste map (OSM based) created from three layers:
- +
-  - layer is background, which is not visible in list but required. +
-  - layer is contour layer, which is visible but not really required. On some places should not be this layer, so when server return 404 code for tile, you can still see background layer! +
-  - layer is shade. This layer will be visible is map list, so fill correct "mode" and "area" (optional). This layer is also not required.+
  
 +  - background layer not visible in the map list but required.
 +  - contour layer, visible but not really required. If this layer is not visible on some places and when the server returns 404 code for missing tiles you can still see background layer.
 +  - shade layer, also not required. This layer is visible in the map list - fill correct "mode" and "area" (optional). 
 +Referer added to the header is not recommended in this case. 
 ==== Map code in providers.xml file ==== ==== Map code in providers.xml file ====
- 
-Example of OpenPiste map (OSM based) created from two layers here (in app is together with third shade layer). First layer is background, which is not visible in list but required. Second is contour layer, which is visible but not really required. On some places should not be this layer so when server return 404 code for tile, you can still see background layer! Referer added to header is not recommended in this case. It's only as example. 
  
 <code xml providers.xml> <code xml providers.xml>
Line 27: Line 24:
           <name>OSM</name>           <name>OSM</name>
           <mode>background</mode>           <mode>background</mode>
-          <url><![CDATA[http://tiles.openpistemap.org/nocontours/{z}/{x}/{y}.png]]></url>+          <url><![CDATA[http://tiles.openpistemap.org/nocontours/{z}/{x}/{y}.png?v={ts}]]></url>
           <zoomPart>{z}-8</zoomPart>           <zoomPart>{z}-8</zoomPart>
           <zoomMin>8</zoomMin>           <zoomMin>8</zoomMin>
           <zoomMax>24</zoomMax>           <zoomMax>24</zoomMax>
           <tileSize>256</tileSize>           <tileSize>256</tileSize>
 +          <tileScale dpi="0" multi="2.0" replace="19" />
           <extraHeader>Referer#http://locus.asamm.cz/</extraHeader>           <extraHeader>Referer#http://locus.asamm.cz/</extraHeader>
        </provider>        </provider>
Line 37: Line 35:
           <name>OSM</name>           <name>OSM</name>
           <mode>contours</mode>           <mode>contours</mode>
-          <url><![CDATA[http://tiles.openpistemap.org/contours-only/{z}/{x}/{y}.png]]></url>+          <url><![CDATA[http://tiles.openpistemap.org/contours-only/{z}/{x}/{y}.png?v={ts}]]></url>
           <zoomPart>{z}-8</zoomPart>           <zoomPart>{z}-8</zoomPart>
           <zoomMin>8</zoomMin>           <zoomMin>8</zoomMin>
           <zoomMax>24</zoomMax>           <zoomMax>24</zoomMax>
           <tileSize>256</tileSize>           <tileSize>256</tileSize>
 +          <tileScale dpi="0" multi="2.0" replace="19" />
           <extraHeader>Referer#http://locus.asamm.cz/</extraHeader>           <extraHeader>Referer#http://locus.asamm.cz/</extraHeader>
        </provider>        </provider>
Line 47: Line 46:
           <name>OSM</name>           <name>OSM</name>
           <mode>OpenPiste</mode>           <mode>OpenPiste</mode>
-          <url><![CDATA[http://tiles2.openpistemap.org/landshaded/{z}/{x}/{y}.png]]></url>+          <url><![CDATA[http://tiles2.openpistemap.org/landshaded/{z}/{x}/{y}.png?v={ts}]]></url>
           <zoomPart>{z}-8</zoomPart>           <zoomPart>{z}-8</zoomPart>
           <zoomMin>8</zoomMin>           <zoomMin>8</zoomMin>
           <zoomMax>24</zoomMax>           <zoomMax>24</zoomMax>
           <tileSize>256</tileSize>           <tileSize>256</tileSize>
 +          <tileScale dpi="0" multi="2.0" replace="19" />
           <countries>World</countries>           <countries>World</countries>
           <usage>hiking,ski</usage>           <usage>hiking,ski</usage>
Line 61: Line 61:
 ==== Specifications of map definition ==== ==== Specifications of map definition ====
  
-  * **id** - required identificator, must be greater or equal 1000. Values before are reserved to Locus+  * **id** - required identifier, must be higher than or equal to 1000. Lower values are reserved for Locus Map.
   * **type** - type of map provider   * **type** - type of map provider
     * **0** - Spherical mercator, projection Spheric, inverse Y     * **0** - Spherical mercator, projection Spheric, inverse Y
Line 68: Line 68:
     * **3** - Spherical mercator, projection Ellipsoid, normal Y     * **3** - Spherical mercator, projection Ellipsoid, normal Y
     * **4** - Spherical Mercator, projection Spheric, Y from center     * **4** - Spherical Mercator, projection Spheric, Y from center
-    * **5** - Spherical mercator, projection Spheric, Quadkey map system (more info http://msdn.microsoft.com/en-us/library/bb259689.aspx)+    * **5** - Spherical mercator, projection Spheric, Quadkey map system (more info here: http://msdn.microsoft.com/en-us/library/bb259689.aspx)
       * use {c} for coordinate part only. There are no X, Y, Z coordinates in URL, just {c}!       * use {c} for coordinate part only. There are no X, Y, Z coordinates in URL, just {c}!
-  * **visible** - if provider will be visible in list +  * **visible** - visibility of provider in the list 
-  * **required** - is tile from this provider required? When server returns 404, use rest of multilayer map or not?+  * **required** - is tile from this provider required? When the server returns 404, use rest of multilayer map or not?
   * **background** - ID of background layer   * **background** - ID of background layer
   * **name** - name of provider   * **name** - name of provider
-  * **mode** - little description+  * **mode** - short description
   * <del>area</del> - deprecated, not used anymore   * <del>area</del> - deprecated, not used anymore
-  * **url** - http://tile... - base url for tiles which don''change with requests. {z}/{x}/{y} syntax for tiles, where {x} and others will be replaced for X, Y coordinates and Zoom +  * **url** - http://tile... - base url for tiles that does not change with requests. {z}/{x}/{y} syntax for tiles, where {x} and others replace X, Y coordinates and Zoom 
-    * **{x}** - replace by X tile +    * **{x}** - replaces  X tile 
-    * **{y}** - replace by Y tile +    * **{y}** - replaces  Y tile 
-    * **{z}** - replace by zoom level after applied **zoomPart** computation +    * **{z}** - replaces zoom level after **zoomPart** computation is applied 
-    * **{s}** (optional) - replace by server text +    * **{ts}** -  tileScale replaces value 
-  * **serverPart** - you can define {s} item in main url. In serverPart can then be defined array of items that will be randomly set as {s} item. So for example <serverPart>0;1;2</serverPart> and url started as <url><![CDATA[http://tiles{s}.open ..... {z}/{x}/{y}.png]]></url> will set every call to be randomly http://tiles0.open..., or http://tiles1.open..., or http://tiles2.open... +    * **{s}** (optional) - replaces the server text 
-  * **zoomPart** - {z}-8 - syntax for recompute correct zoom value for request. This value is usually Zoom - minimum zoom, but should be different+  * **serverPart** - {s} item can be defined in the main url. In serverPart an array of items can then be defined  that will be randomly set as {s} item. So for example <serverPart>0;1;2</serverPart> and url started as <url><![CDATA[http://tiles{s}.open ..... {z}/{x}/{y}.png]]></url> will set every call to be randomly http://tiles0.open..., or http://tiles1.open..., or http://tiles2.open...\\ **ServerPart** parameter can be also defined by //x, y// and parameters in a simple mathematic formula:\\ <code> <serverPart>({x}+{y})%4</serverPart></code> 
 +  * **zoomPart** - {z}-8 - syntax for recomputing correct zoom value for the request. This value is usually Zoom - minimum zoom, but can be different
   * **zoomMin** - minimum zoom   * **zoomMin** - minimum zoom
   * **zoomMax** - maximum zoom   * **zoomMax** - maximum zoom
-  * **tileSize** - size of tiles in pixel +  * **tileSize** - size of tiles in pixels 
-  * **countries** - list of countries (separated by comma), where map may be used. These values are used for separating maps in "Online map tab"+  * **tileScale** - defines scaling factor (multi) to be 2x, DPI to which to apply (dpi, 0 = all devices) and value that will be replaced in url (//replace//, must not be empty) 
-  * **usage** - list of possible usage of this map (separated by comma). Current possibilities are: //aero, city, cycle, hiking, nautical, overlay, photo, road, ski, transport//. These values are used for separating maps in "Online map tab"+  * **countries** - list of countries (separated by commasrelevant for the map. These values are used for separating maps in "Online map tab"
-  * **extraHeader** - extra Http request that will be added to tile request on server. These additional data consist of two parts with syntax part1#part2. Part1 is name of this request, Part2 is value of this request. Also this TAG should be in XML for every provider more then once. +  * **usage** - list of possible usages of this map (separated by commas). Current options are: //aero, city, cycle, hiking, nautical, overlay, photo, road, ski, transport//. These values are used for separating maps in "Online map tab"
-  * **attribution** - small text displayed at map screen at bottom. Please use this when you're using maps that have any owner (other then yours) and require attribution in their terms of use+  * **extraHeader** - extra Http request that is added to the tile request on server. These additional data consist of two parts with syntax part1#part2. Part1 is the request name, Part2 is the request value. Also this TAG should be in XML for every provider more than once. 
 +  * **attribution** - short text displayed at the bottom of the map screen. Please use this when you're using copyrighted maps that require attribution in their terms of use.
  
-ZoomValues (zoomMin, zoomMax) have to be counted as valid zoom level by 2^x. So whole world have one tile 256x256 px, which means 2^8, so X = 8!. That's why almost all maps in Locus start with zoomMin = 8 but have zoomPart {z} - 8. This is because in URL, zooms usually starts from 0 some max value+ZoomValues (zoomMin, zoomMax) have to be counted as valid zoom level by 2^x. So the whole World has one tile 256x256 px, which means 2^8, so X = 8!. That's why almost all maps in Locus start with zoomMin = 8 but have zoomPart {z} - 8. This is because in URLs zooms usually start from 0 to some max value.
  
-I'm sure that this solution should be improved so if you have any ideas, tell me. Also if here will be any little bit experienced developer on android, we should try to create some mechanist for adding external providers through ContentProviders or services.+This solution should be improved so if you have any ideas, tell us. Also, an experienced Android developer on should be able to create some mechanism for adding external providers through ContentProviders or services.
  
-Now you know syntax of providersso you should add your custom ones. Please, share links with others and enjoy+Now you know syntax of providers so you should add your custom ones. Please, share links with others and enjoy!
  
 ==== Hints ==== ==== Hints ====
  
-  * providers with same name will be grouped together! +  * providers with the same name will be grouped together 
-  * if you add PNG icon into custom directory with same name as provider name, icon will be attached into online map screen+  * if you add PNG icon into custom directory with the same name as provider name, it will be attached to online map screen
  
 ===== How to obtain required info ===== ===== How to obtain required info =====
  
-Suggested is to use Firefox browser with extension HttpFox+We recommend to use Firefox browser with extension HttpFox:
  
-  * Start Firefox browser and open webpage with map. Nice example on http://www.openstreetmap.org/.+  * Start Firefox browser and open webpage with map. Nice example is http://www.openstreetmap.org/.
   * Open HttpFox from Tools menu or by SHIFT-F2. And press top green Start button.   * Open HttpFox from Tools menu or by SHIFT-F2. And press top green Start button.
-  * Now zoom by one level and you'll see list of requests on map server. Viz screenshot below. +  * Now zoom by one level and you'll see the list of requests on the map server. See screenshot below. 
-  * So I'll take selected URL line. On right side is required URLso when we separate part with coordinates then 12/2215/1389 will be cooPart written as {z}/{x}/{y}. +  * take selected URL line. Required URL is on the right so when we separate part with coordinates then 12/2215/1389 will be cooPart written as {z}/{x}/{y}. 
-  * Rest will be url partso it will look http://c.tile.openstreetmap.org/{c}.png. +  * the rest is url part so it will look like http://c.tile.openstreetmap.org/{c}.png. 
-  * These are main values needed to add map. Tilesize is usually 256px. Min and max zoom values have to be tested manually. Also zoomPart is usually z-8, which mean that zoom 20 in Locus will be served as 12 in request on server.+  * These are main values needed to add map. Tilesize is usually 256 px. Min and max zoom values have to be tested manually. Also zoomPart is usually z-8, which means that zoom 20 in Locus will be served as 12 in request on server.
  
 {{ :manual:advanced:customization:osm_requests.png?nolink |}} {{ :manual:advanced:customization:osm_requests.png?nolink |}}
 +<WRAP center round tip >
 +Another sample of custom online map can be Strava Global Heatmap XML file that we prepared together with our users. It contains cycling and running layers and can be downloaded {{:manual:advanced:customization:strava2.providers.zip|here >>}}. Just unzip it in Locus/mapsOnline/custom directory and enjoy! 
 +</WRAP>
 +===== Own Open Map Tile Server =====
 +==== Disabling map downloading limit ====
 +If you operate your own map tile server you may need to **cancel tile downloading limit** that is set in Locus by default in order to maintain decent downloading traffic per application:
 +  - **Enable mod_headers**: sudo a2enmod headers
 +  - **Edit the Apache configuration file** (/etc/apache2/apache2.conf) and add at the end: Header set locus_disable_download_limit "true"
manual/advanced/customization/online_maps.txt · Last modified: 2019/07/03 16:33 by mstupka