Custom XML Map Sources

From MOBAC Wiki
Revision as of 12:17, 20 June 2016 by Zshtadler (Talk | contribs) (→‎Custom WMS map sources: Use of a `<![CDATA[ ]]>` element. Replaced the retired TerraServer with a working WMS server.)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Overview

Custom map sources which uses a similar URL scheme as Google/OpenStreetMap can be added to MOBAC. There are several types of map sources. Most of them are defined in an xml file in the mapsources directory.

Note: For simple testing a custom XML map source you can also use MapEvaluator. Simply copy and paste the content of an custom map source XML file into the editor and execute it.

Simple custom map sources

The following section shows is an example how the xml file has to be formatted. It defines an additional map source named "Custom OSM Mapnik" which shows map tiles identical to the predefined map source "OpenStreetMap Mapnik". 

<?xml version="1.0" encoding="UTF-8"?>
<customMapSource>
   <name>Custom OSM Mapnik</name>
   <minZoom>0</minZoom>
   <maxZoom>18</maxZoom>
   <tileType>png</tileType>
   <url>http://tile.openstreetmap.org/{$z}/{$x}/{$y}.png</url>
   <tileUpdate>None</tileUpdate>
   <backgroundColor>#000000</backgroundColor>
   <ignoreErrors>false</ignoreErrors>
   <serverParts></serverParts>
</customMapSource>

The most important part of this definition is the <url> entry. It is a template containing specific placeholders, which are encapsulated by curly braces, and specify the requested tile.

Example file for download
Example custom map source.xml

Custom WMS map sources

A WMS server can be defined as a map source. Currently only EPSG:4326 is supported as the coordinate system . 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customWmsMapSource>
   <name>USGS EROS Ortho WMS</name>
   <minZoom>0</minZoom>
   <maxZoom>22</maxZoom>
   <tileType>PNG</tileType>
   <version>1.1.1</version>
   <layers>0</layers>
   <url>http://isse.cr.usgs.gov/arcgis/services/Orthoimagery/USGS_EROS_Ortho/ImageServer/WMSServer?</url>
   <coordinatesystem>EPSG:4326</coordinatesystem>
   <aditionalparameters><![CDATA[&STYLES=default]]></aditionalparameters>
   <backgroundColor>#000000</backgroundColor>
</customWmsMapSource>

It is recommended to wrap any field that has special charcters, such as an ampersand, inside a `<![CDATA[ ]]>` element. Otherwise you have to use their XML encoding, such as `&amp;`

Example file for download
Example custom WMS map source.xml

Custom CloudMade map sources

The CloudMade map service offers a large number of OpenStreetMap based maps with different styles. Each style is accessible through it's styleID . Custom CloudMade maps can be added to MOBAC via a simple XML file containing a map name used by MOBAC and a styleID: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cloudMade>
   <displayName>CloudMade Fine Line</displayName>
   <styleID>2</styleID>
</cloudMade>
Example file for download
Example CloudMade Fine Line.xml

Local Tile files

Existing atlases or locally rendered tiles can be directly integrated into MOBAC as custom map source without having to set-up a local web-server.

Note
At the moment the formats used by OSMTracker, AndNav, BackCountry Navigator, Maverick and OSMAND are supported. 
<?xml version="1.0" encoding="UTF-8"?>
<localTileFiles>
   <name>Custom map from tile files</name>
   <sourceType>DIR_ZOOM_X_Y</sourceType>
   <sourceFolder>D:\MOBAC\LocalTiles\OSMAND\TilesAtHome</sourceFolder>
   <invertYCoordinate>true</invertYCoordinate> <!-- optional -->
   <backgroundColor>#000000</backgroundColor>
</localTileFiles>
Example file for download
Example custom tile files source.xml file, adapt the <sourceFolder> entry and place it in the mapsources directory.

Local Tiles in Zip file

Tiles can also be packed into one or more zip files and directly used by MOBAC. 

<?xml version="1.0" encoding="UTF-8"?>
<localTileZip>
   <name>Custom map from tile zips</name>
   <sourceType>QUADKEY</sourceType>
   <zipFile>D:\MOBAC\LocalTiles\MapCruncher_test.zip</zipFile>
   <backgroundColor>#000000</backgroundColor>
</localTileZip>
Example file for download
Example custom tile zip source.xml
Note
Java 7 is required when working with ZIP files larger than 4 GB

Local Tiles in SQLite file

SQLite based atlas formats can also be used directly by MOBAC. Supported atlas formats are: RMaps, MBTiles, BigPlanetTracks, NaviComputer and OSMAND. Not supported: OruxMaps and Osmdroid 

<?xml version="1.0" encoding="UTF-8"?>
<localTileSQLite>
   <name>Custom SQLite atlas</name>
   <sourceFile>D:\MOBAC\LocalTiles\Region.Mapnik.sqlitedb</sourceFile>
   <atlasType>OSMAND</atlasType>
   <backgroundColor>#000000</backgroundColor>
   <tileImageType>PNG</tileImageType> <!-- optional -->
</localTileSQLite>
Example file for download
Example custom tile SQLite source.xml

Custom BeanShell map sources

BeanShell map sources as the can be developed using MapEvaluator can be used by MOBAC. To do so place the saved BeanShell code file (file extension .bsh ) in the mapsources directory. It will be loaded on next start-up of MOBAC.

Note
It is recommended to add a line defining the unique name of the map source to the BeanShell code.
name = "Your map source name here";
Example file for download
Example beanshell map source.bsh

Custom multi-layer map sources

Map sources which consist of two or more layers can be defined, similar to single-layer custom map sources.

Note
All map source layers, except the first in the list (the background layer), must have transparent parts. A non-transparent layer will hide all layers listed before it.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<customMultiLayerMapSource>
   <name>Custom OSM Mapnik with Hills (Ger)</name>
   <tileType>png</tileType>
   <backgroundColor>#000000</backgroundColor>
   <layersAlpha>1.0 0.8</layersAlpha>
   <layers>
      <customMapSource>
         <name>Custom OSM Mapnik</name>
         <minZoom>0</minZoom>
         <maxZoom>18</maxZoom>
         <tileType>png</tileType>
         <tileUpdate>None</tileUpdate>
         <url>http://tile.openstreetmap.org/{$z}/{$x}/{$y}.png</url>
      </customMapSource>
      <customMapSource>
         <name>Custom transparent hillshade</name>
         <minZoom>0</minZoom>
         <maxZoom>18</maxZoom>
         <tileType>png</tileType>
         <tileUpdate>None</tileUpdate>
         <url>http://www.wanderreitkarte.de/hills/{$z}/{$x}/{$y}.png</url>
       </customMapSource>
   </layers>
</customMultiLayerMapSource>

The most important part of this definition is the <layers> entry. It is an ordered list of map sources to be layered one on top of the other, where the last map source is the top-most.

Example files for download
Example custom multi-layer map source.xml
Example custom multi-layer map source2.xml

Custom Built-in Map Pack

Developing a custom built-in map pack requires at least basic Java skills. Therefore the description on how to develop a custom map pack is only part of the source code release of MOBAC. You can get the source code of MOBAC by using the latest src release available in the files section at SourceForge or you can get it directly from the Subversion code repository using the latest trunk version.

customMapSource

Type
Optional Entry
Description
Defines a map source by the <url> of its tiles.
Contents
  • <name> The name of the map source
  • <minZoom> The minimum zoom level provided by the map source
  • <maxZoom> The maximum zoom level provided by the map source
  • <tileType> The image type provided by the map source
  • <url> The URL for the tiles of the map source
  • <invertYCoordinate> Optional. Inverts the y coordinate so that it starts south
  • <serverParts> Optional. Use multiple servers for the map source
  • <backgroundColor> Optional. The background color of a map
  • <tileUpdate> Optional. The server capabilities for conditional downloading of new/updated tiles
  • <ignoreErrors> Optional. Handling of missing tiles


name

Type
Required entry
Description
Map source name as it appears in the map sources list. The name has to be unique among the names of all map sources in MOBAC - built-in and user defined. The list of all available map sources and their names can be obtained via Show all map source names in the Debug menu.

minZoom

Type
Required entry
Description
The minimum zoom level provided by the map source. For world wide maps this is usually 0 (one 256x256 tile showing the whole world) tile or sometimes 1 (four tiles showing the world). For regional map sources that cover only certain countries for example the value can be higher.

maxZoom

Type
Required entry
Description
The maximum zoom level provided by the map source.

tileType

Type
Required entry
Description
The image type provided by the map source.
Possible values are
  • PNG
  • JPG
  • GIF.
Note
values are case insensitive

url

Type
Required entry
Description
The URL for the tiles of the map source. It is a template containing specific placeholders which are encapsulated by curly brace:
Tile selection
  • {$z} for the zoom level - number range: [minZoom .. maxZoom]
  • {$x} for the x tile coordinate - number range: [0..2zoom level]
  • {$y} for the y tile coordinate - number range: [0..2zoom level]

Alternatively for map sources that are using the quadtree key syntax (similar as it is used on Bing maps) there is the possibility to use the following parameter:

  • {$q} for a quadtree key that encodes both the zoom level and the x and y tile coordinates
Server selection
  • {$s} for selection of a server defined by the optional <serverParts> entry


Note

Ampersand characters & in an url have to be entity-escaped: &amp; - otherwise you will get an error when MOBAC is starting and tries to load the custom map. Alternatively you can put the URL in an CDATA section:

Example URL outside of MOBAC: http://example.org/map&x={$x}&y={$y}&z={$z}
The same URL, prepared for MOBAC XML map source:

  • encoded: 
    <url>http://example.org/map&amp;x={$x}&amp;y={$y}&amp;z={$z}</url>
  • or in CDATA: 
    <url><![CDATA[http://example.org/map&x={$x}&y={$y}&z={$z}]]></url>

invertYCoordinate

Type
Optional entry

Description: If set to true, it inverts the y coordinate so that it starts south (min=0) and increases towards north (max=2^zoom -1). Supported since MOBAC 1.9.2

Default value if not present
false: Start north and increase towards south.

serverParts

Type
Optional entry
MOBAC version
Supported since MOBAC 1.9 beta 7
Description
Use multiple servers for the map source. Contains a space-separated list of parts that replace the {$serverpart} variable in the specified <url> pattern. This is especially useful for servers that perform load balancing among multiple server with different DNS names.
Example
(not functional - just to demonstrate how it works):
<url>http://{$serverpart}.openstreetmap.example/{$z}/{$x}/{$y}.png</url>
<serverParts>a b 6 test</serverParts>

Requests will be sent to 

http://a.openstreetmap.example/...
http://b.openstreetmap.example/...
http://6.openstreetmap.example/...
http://test.openstreetmap.example/...

backgroundColor

Type
Optional entry
Description
The background color of a map. This is useful for maps that use transparency. Additionally the background color will be used in case of missing tiles or tiles that could not be downloaded for atlas formats that require rectangular selections like OziExplorer, TrekBuddy, ...
Format
A hash character followed by a Hex triplet for an RGB color or quadruplet for an RGB color plus alpha transparency
Examples
  • White: #FFFFFF or #FFFFFFFF
  • Red: #FF0000
  • Gray: #808080
  • Transparent: #00000000
  • White with 50% transparency: #FFFFFF80
Default value if not present
Black: #000000FF

tileUpdate

Type
Optional entry
Description
The server capabilities for conditional downloading of new/updated tiles.
Note
A tile is only downloaded if it is not present in the tile store or if the downloaded tile in the tile store has expired.
Possible Values
  • IfNoneMatch: When a new tile is downloaded an If-None-Match entry is added to the request header. Requires the server to provide an ETag value in each HTTP response and support of If-None-Match request header.
  • ETag: Before downloading a tile completely an HTTP HEAD request is performed for checking the ETag value of the tile. An actual download is only performed in case the ETag value is different to the stored one. Requires the server to provide an ETag value in each HTTP response.
  • IfModifiedSince: When a new tile is downloaded an If-Modified-Since entry is added to the request header. Requires the server to provide a Last-Modified value in each HTTP response and support of If-Modified-Since request header.
  • LastModified Before downloading a tile completely an HTTP HEAD request is performed for checking the Last-Modified value of the tile. An actual download is only performed in case the Last-Modified value is newer than the stored one. Requires the server to provide a Last-Modified value in each HTTP response.
  • None: No checking is performed - if a tile has expired it is directly downloaded.
Default value if not present
None

ignoreErrors

Type
Optional entry
Description
Handling of missing tiles errors. Useful for map sources that do only cover some tiles (sparse).
Possible Values
  • false or value not specified: Missing tiles will be shown as a red cross in the map preview and tiles will not be included in the created map
  • true: All errors including missing tiles will be ignored. Instead an empty image tile will be created using the color specified by the <backgroundColor> entry.
Default value if not present
false

customWmsMapSource

Type
Optional entry
Description
Allows the use of a WMS server as a map source.
Contents
  • <name> The name of the map source to appear in MOBAC
  • <minZoom> The minimum zoom level provided by the WMS server
  • <maxZoom> The maximum zoom level provided by the WMS server
  • <tileType> The image type provided by the server
  • <url> The base URL of the WMS server
    • Note: Ampersand characters & in an url have to be entity-escaped: &amp; - otherwise you will get an error when MOBAC is starting and tries to load the custom map.
  • <version> The version the WMS tile server
  • <layers> The layers requested from the WMS tile server
  • <coordinatesystem> The coordinate system requested from the WMS server. Currently only EPSG:4326 is supported as the coordinate system
  • <aditionalparameters> Optional. Any additional parameters to be sent to the WMS server
  • <backgroundColor> Optional. The background color of a map

cloudMade

Type
Optional entry
Description
Allows the use of a CloudMade map source.
Contents
  • <displayName> The name of the map source to appear in MOBAC
  • <styleID> The CloudMade style ID

localTileFiles

Type
Optional entry
Description
Allows the use of atlases or locally rendered tiles as a map source.
MOBAC version
MOBAC 1.9.3 and higher
Contents
  • <name> The name of the map source to appear in MOBAC
  • <sourceFolder> The directory in which the existing atlas is located
<sourceFolder>D:\MOBAC\LocalTiles\OSMAND\TilesAtHome</sourceFolder>

sourceType

Type
Mandatory entry for <localTileFiles> and <localTileZip> entries
Description
Specifies the directory structure and file name for local tile file and inside a tile Zip file
MOBAC version
MOBAC 1.9.3 and higher
Possible values
  • DIR_ZOOM_X_Y The directory structure is "zoom/x/y.png". Other file extensions like "jpg", "gif", "png.andnav2", and "jpg.xyz" are also supported.
  • DIR_ZOOM_Y_X The directory structure is "zoom/y/x.png". Other file extensions like "jpg", "gif", "png.andnav2", and "jpg.xyz" are also supported.
  • QUADKEY The directory structure is a single directory with quad-key file names that have png, gif or jpg extension. The regular expression for the file name is: [0123]+\.(png|gif|jpg)

localTileZip

Type
Optional entry
Description
Allows the use of atlases or locally rendered tiles and stored in a Zip file as a map source.
MOBAC version
MOBAC 1.9.3 and higher
Contents
  • <name> The name of the map source to appear in MOBAC
  • <zipFile> The full path to the zip file containing the tile images. If more than one zipFile entry exists, the Zip files are searched in the order they were specified. If a tile is not found in a Zip file, the search continues in the next file.
<zipFile>D:\MOBAC\LocalTiles\MapCruncher_test.zip</zipFile>
  • <sourceType> The directory structure and file names in the atlas.
  • <invertYCoordinate> Optional. Invert the direction of the Y coordinate

localTileSQLite

Type
Optional entry
Description
Allows the use of atlases or locally rendered tiles and stored in a SQL file as a map source. Not
Contents
  • <name> The name of the map source to appear in MOBAC
  • <sourceFile> The full path to the SQL file containing the tile images.
<sourceFile>D:\MOBAC\LocalTiles\Region.Mapnik.sqlitedb</sourceFile>
  • <atlasType> The type of the SQL file.
  • <backgroundColor> Optional: The background color to be used if tiles have transparency
  • <tileImageType> Optional: Specify the image type: PNG JPG or GIF. If not specified, the image type is detected automatically
<tileImageType>PNG</tileImageType>

atlasType

Type
Mandatory entry for <localTileSQLite> entries
Description
Specifies the directory type of the SQL file, case sensitive.
Possible values
  • RMaps
  • MBTiles
  • BigPlanetTracks
  • NaviComputer
  • OSMAND

customMultiLayerMapSource

Type
Optional entry
Description
Allows the use of multiple map sources as a layered map source
Contents
  • <name> The name of the map source to appear in MOBAC
  • <layers> A list of map sources
  • <backgroundColor> Optional. The background of the entire set of map sources. The <backgroundColor> entry of the individual map sources is ignored
  • <layersAlpha> Optional. A list of opacity values for each layer, from bottom (first) to top (last). A value of 0.0 is fully transparent or invisible, while a value of 1.0 is fully opaque. Usually the first layer should use 1.0 = 100% opacity

layers

Type
Mandatory entry for the <customMultiLayerMapSource> entry
Description
Specifies the map sources that will be combined into a single map. The first layer is located at the bottom, overlayed by all other map sources, and the top layer should be last.
Note
Make sure all the maps after the first contain transparent regions or use a <layersAlpha> entry to add some transparency to them. Otherwise lower (earlier) layers will not be visible.
Possible content
       <mapSource>
           <name>Mapnik</name>
       </mapSource>
Note
All built-in and BeanShell-defined map sources can be used freely. Moreover, a multi-layer map source described in file b.xml could use a map source from file a.xml.
Retrieved from "http://mobac.sourceforge.net/wiki/index.php?title=Custom_XML_Map_Sources&oldid=179"