View source for Custom XML Map Sources

= 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 <tt>mapsources</tt> 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|customMapSource]]>
    <[[#name|name]]>Custom OSM Mapnik</name>
    <[[#minZoom|minZoom]]>0</minZoom>
    <[[#maxZoom|maxZoom]]>18</maxZoom>
    <[[#tileType|tileType]]>png</tileType>
    <[[#url|url]]><nowiki>http://tile.openstreetmap.org/{$z}/{$x}/{$y}.png</nowiki></url>
    <[[#tileUpdate|tileUpdate]]>None</tileUpdate>
    <[[#backgroundColor|backgroundColor]]>#000000</backgroundColor>
    <[[#ignoreErrors|ignoreErrors]]>false</ignoreErrors>
    <[[#serverParts|serverParts]]></serverParts>
 </customMapSource>

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

;Example file for download:  [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20map%20source.xml 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|customWmsMapSource]]>
    <[[#name|name]]>TerraServer WMS</name>
    <[[#minZoom|minZoom]]>12</minZoom>
    <[[#maxZoom|maxZoom]]>18</maxZoom>
    <[[#tileType|tileType]]>JPG</tileType>
    <version>1.1.1</version>
    <layers>DRG</layers>
    <url><nowiki>http://terraserver-usa.com/ogcmap6.ashx?</nowiki></url>
    <coordinatesystem>EPSG:4326</coordinatesystem>
    <aditionalparameters>&amp;EXCEPTIONS=BLANK&amp;Styles=</aditionalparameters>
    <[[#backgroundColor|backgroundColor]]>#000000</backgroundColor>
 </customWmsMapSource>

;Example file for download: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20WMS%20map%20source.xml Example custom WMS map source.xml]

== Custom CloudMade map sources ==
The [http://maps.cloudmade.com/ 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|cloudMade]]>
    <displayName>CloudMade Fine Line</displayName>
    <styleID>2</styleID>
 </cloudMade>

;Example file for download: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20CloudMade%20Fine%20Line.xml 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|localTileFiles]]>
    <[[#name|name]]>Custom map from tile files</name>
    <[[#sourceType|sourceType]]>DIR_ZOOM_X_Y</sourceType>
    <sourceFolder>D:\MOBAC\LocalTiles\OSMAND\TilesAtHome</sourceFolder>
    <invertYCoordinate>true</invertYCoordinate> <nowiki><!-- optional --></nowiki>
    <[[#backgroundColor|backgroundColor]]>#000000</backgroundColor>
 </localTileFiles>

;Example file for download: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20tile%20files%20source.xml 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|localTileZip]]>
    <name>Custom map from tile zips</name>
    <[[#sourceType|sourceType]]>QUADKEY</sourceType>
    <zipFile>D:\MOBAC\LocalTiles\MapCruncher_test.zip</zipFile>
    <backgroundColor>#000000</backgroundColor>
 </localTileZip>

;Example file for download: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20tile%20zip%20source.xml 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|localTileSQLite]]>
    <[[#name|name]]>Custom SQLite atlas</name>
    <sourceFile>D:\MOBAC\LocalTiles\Region.Mapnik.sqlitedb</sourceFile>
    <[[#atlasType|atlasType]]>OSMAND</atlasType>
    <[[#backgroundColor|backgroundColor]]>#000000</backgroundColor>
    <tileImageType>PNG</tileImageType> <nowiki><!-- optional --></nowiki>
 </localTileSQLite>

;Example file for download: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20tile%20SQLite%20source.xml Example custom tile SQLite source.xml]

==  Custom BeanShell map sources ==
BeanShell map sources as the can be developed using [http://sourceforge.net/apps/mediawiki/mobac/index.php?title=MapEvaluator 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: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20beanshell%20map%20source.bsh 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|customMultiLayerMapSource]]>
    <[[#name|name]]>Custom OSM Mapnik with Hills (Ger)</name>
    <[[#tileType|tileType]]>png</tileType>
    <[[#backgroundColor|backgroundColor]]>#000000</backgroundColor>
    <layersAlpha>1.0 0.8</layersAlpha>
    <[[#layers|layers]]>
       <[[#customMapSource|customMapSource]]>
          <[[#name|name]]>Custom OSM Mapnik</name>
          <[[#minZoom|minZoom]]>0</minZoom>
          <[[#maxZoom|maxZoom]]>18</maxZoom>
          <[[#tileType|tileType]]>png</tileType>
          <[[#tileUpdate|tileUpdate]]>None</tileUpdate>
          <[[#url|url]]><nowiki>http://tile.openstreetmap.org/{$z}/{$x}/{$y}.png</nowiki></url>
       </customMapSource>
       <[[#customMapSource|customMapSource]]>
          <[[#name|name]]>Custom transparent hillshade</name>
          <[[#minZoom|minZoom]]>0</minZoom>
          <[[#maxZoom|maxZoom]]>18</maxZoom>
          <[[#tileType|tileType]]>png</tileType>
          <[[#tileUpdate|tileUpdate]]>None</tileUpdate>
          <[[#url|url]]><nowiki>http://www.wanderreitkarte.de/hills/{$z}/{$x}/{$y}.png</nowiki></url>
        </customMapSource>
    </layers>
 </customMultiLayerMapSource>

The most important part of this definition is the <[[#layers|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: [https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20multi-layer%20map%20source.xml Example custom multi-layer map source.xml]
:[https://mobac.svn.sourceforge.net/svnroot/mobac/trunk/MOBAC/mapsources/Example%20custom%20multi-layer%20map%20source2.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 [https://sourceforge.net/projects/mobac/files/Mobile%20Atlas%20Creator/ files section at SourceForge] or you can get it directly from the [https://sourceforge.net/scm/?type=svn&group_id=238075 Subversion code repository] using the latest [http://mobac.svn.sourceforge.net/viewvc/mobac/trunk/ trunk] version.

= customMapSource =
;Type: Optional Entry

;Description: Defines a map source by the <[[#url|url]]> of its tiles.
;Contents:

* '''<[[#name|name]]>''' The name of the map source
* '''<[[#minZoom|minZoom]]>''' The minimum zoom level provided by the map source
* '''<[[#maxZoom|maxZoom]]>''' The maximum zoom level provided by the map source
* '''<[[#tileType|tileType]]>''' The image type provided by the map source
* '''<[[#url|url]]>''' The URL for the tiles of the map source
* '''<[[#invertYCoordinate|invertYCoordinate]]>''' Optional. Inverts the y coordinate so that it starts south
* '''<[[#serverParts|serverParts]]>''' Optional. Use multiple servers for the map source
* '''<[[#backgroundColor|backgroundColor]]>''' Optional. The background color of a map
* '''<[[#tileUpdate|tileUpdate]]>''' Optional. The server capabilities for conditional downloading of new/updated tiles
* '''<[[#ignoreErrors|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..2<sup>zoom</sup> level]
* '''{$y}''' for the y tile coordinate - number range: [0..2<sup>zoom</sup> level]
Alternatively for map sources that are using the quadtree key syntax (similar as it is used on [http://msdn.microsoft.com/en-us/library/bb259689.aspx 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|serverParts]]> entry


;Note:
Ampersand characters '''&''' in an url have to be entity-escaped: '''&amp;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 [http://www.w3schools.com/xml/xml_cdata.asp CDATA] section:

Example URL outside of MOBAC: '''<nowiki>http://example.org/map&x={$x}&y={$y}&z={$z}</nowiki>''' <br/>
The same URL, prepared for MOBAC XML map source:
* encoded: <pre><nowiki><url>http://example.org/map&amp;amp;x={$x}&amp;amp;y={$y}&amp;amp;z={$z}</url></nowiki></pre>
* or in CDATA: <pre><nowiki><url><![CDATA[http://example.org/map&x={$x}&y={$y}&z={$z}]]></url></nowiki></pre>

== 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 <tt>{$serverpart}</tt> variable in the specified <[[#url|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><nowiki>http://{$serverpart}.openstreetmap.example/{$z}/{$x}/{$y}.png</nowiki></url>
 <serverParts>a b 6 test</serverParts>

Requests will be sent to 
 <nowiki>http://a.openstreetmap.example/...</nowiki>
 <nowiki>http://b.openstreetmap.example/...</nowiki>
 <nowiki>http://6.openstreetmap.example/...</nowiki>
 <nowiki>http://test.openstreetmap.example/...</nowiki>

== 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 [http://en.wikipedia.org/wiki/Web_colors 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|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|name]]>''' The name of the map source to appear in MOBAC
* '''<[[#minZoom|minZoom]]>''' The minimum zoom level provided by the WMS server
* '''<[[#maxZoom|maxZoom]]>''' The maximum zoom level provided by the WMS server
* '''<[[#tileType|tileType]]>''' The image type provided by the server
* '''<[[#url|url]]>''' The base URL of the WMS server
** '''Note:''' Ampersand characters '''&''' in an url have to be entity-escaped: '''&amp;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|backgroundColor]]>''' Optional. The background color of a map

= cloudMade =
;Type: Optional entry
;Description: Allows the use of a [http://maps.cloudmade.com/editor 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|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|sourceType]]>''' The directory structure and file names in the atlas
* '''<[[#backgroundColor|backgroundColor]]>''' Optional: The background color to be used if tiles have transparency
* '''<[[#invertYCoordinate|invertYCoordinate]]>''' Optional. Inverts the y coordinate

== sourceType ==
;Type: Mandatory entry for <[[#localTileFiles|localTileFiles]]> and <[[#localTileZip|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|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|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|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|atlasType]]>''' The type of the SQL file. 
* '''<[[#backgroundColor|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|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|name]]>''' The name of the map source to appear in MOBAC
* '''<[[#layers|layers]]>''' A list of map sources
* '''<[[#backgroundColor|backgroundColor]]>''' Optional. The background of the entire set of map sources. The <[[#backgroundColor|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|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:
* '''<[[#customMapSource|customMapSource]]>...''' A simple custom map source
* '''<[[#customWmsMapSource|customWmsMapSource]]>...''' A WMS map source. Supported in MOBAC 1.9.10 or later
* '''<[[#cloudMade|cloudMade]]>...''' A cloudMade map source
* '''<[[#Local_Tile_files|localTileFiles]]>...''' Local Tile files
* '''<[[#Local_Tiles_in_SQLite_file|localTileZip]]>...''' Local Tiles in Zip file
* '''<[[#Local_Tiles_in_SQLite_file|localTileSQLite]]>...''' Local Tiles in SQLite file
* '''<mapSource>...''' Use another map source by giving its name. For example:
        <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.