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 `&`

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..2^zoom level]
{$y} for the y tile coordinate - number range: [0..2^zoom 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: & - 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: & - 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> The directory structure and file names in the atlas
<backgroundColor> Optional: The background color to be used if tiles have transparency
<invertYCoordinate> Optional. Inverts the y coordinate

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

<customMapSource>... A simple custom map source
<customWmsMapSource>... A WMS map source. Supported in MOBAC 1.9.10 or later
<cloudMade>... A cloudMade map source
<localTileFiles>... Local Tile files
<localTileZip>... Local Tiles in Zip 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.

Custom XML Map Sources

Contents