# Mobile Atlas Creator - Read-me

Welcome to Mobile Atlas Creator read-me file for end users.

Before January 2010 this project was known as "TrekBuddy Atlas Creator".

Mobile Atlas Creator is an open source project hosted on SourceForge.net:
http://mobac.dnsalias.org

## Table of contents

- License
- Description
- Requirements
  - SQLite atlas formats
  - Java Advanced Imaging" (JAI)
- Installation
- Application start
- The different atlas formats
  - AFTrack (OSZ)
  - AndNav
  - Big Planet Tracks
  - CacheWolf
  - Garmin Custom maps
  - Glopus
  - Glopus Map File / AFTrack (GMF)
  - Google Earth Overlay (KMZ)
  - Magellan RMP
  - MAPLORER
  - Maverick
  - Mobile Trail Explorer (MTE)
  - NaviComputer
  - OruxMaps
  - Osmdroid
  - OSMTracker
  - OziExplorer / large PNG image
  - PathAway
  - RMaps
  - [Nokia] Sports Tracker
  - Touratech QV
  - TrekBuddy
- Enhancement requests
- Problems, Bugs & Errors
- Known problems and limitations
- Details for advanced users
  - Custom map sources
  - Custom multi-layer map sources

## License

Mobile Atlas Creator is under GNU General Public License Version 2 (GPL). For details on the GPL see the license file gpl.txt.
The source code is available on the SourceForge.net for download and in the project's source code Subversion repository.

## Description

Mobile Atlas Creator creates atlases for several applications. For example TrekBuddy and Mobile Trail Explorer (MTE), the Android applications AndNav, Maverick, Big Planet Tracks, RMaps, OruxMaps, the Pocket PC application Glopus and the commercial Windows application OziExplorer. The map image created for OziExplorer can also be used with any PNG capable image viewer (map image in one large PNG file).

## Requirements

This application requires that a Java Runtime Environment Version 6 Update 14 (v1.6.0_14) or higher is installed on the computer.

If you have the choice between different Java Runtimes you should prefer the Java Runtime provided by Sun/Oracle. Especially the OpenJDK has some bugs regarding MOBAC and tends to crash on certain situations.

### SQLite (optional)

Some atlas formats uses a SQLite database for storing the tiles. For creating SQLite database the additional Java library SQLiteJDBC is required. MOBAC has been tested with sqlitejdbc-v056.jar - newer versions should also work.

Installation of the additional SQLite libraries is pretty simple: Just jownload the JAR file and place it in the same directory where `Mobile_Atlas_Creator.jar` is located. Alternatively you can place it in any path covered by the JAVA search path. The next time MOBAC is started the SQLite library is loaded and can be used.

### Java Advanced Imaging (optional)

For reducing the color depth of downloaded tiles the library files of the "Java Advanced Imaging" (JAI) have to be present on the system respectively in the same directory as Mobile_Atlas_Creator.jar. Ready to use binary builds of the Java Advanced Imaging library can be obtained at https://jai.dev.java.net/binary-builds.html

## Installation

Copy or move the unzipped files to a folder where you would like to have Mobile Atlas Creator installed. On computers running Windows please make sure not to install MOBAC into Program Files sub-directory!

## Application start

### Windows

The application is started by executing the `Mobile Atlas Creator.exe`. During the first application start all necessary files and folders are automatically created by the application.

### Linux and OSX

You can start MOBAC by executing the start-up script `start.sh`. Before starting MOBAC the first time it may be necessary to set the executable bit for `start.sh` e.g. by executing the following command:

    chmod u+x start.sh

During the first application start all necessary files and folders are automatically created by the application.

## The different atlas formats

### AFTrack OSZ

For creating atlases compatible with AFTrack (Symbian S60) you have to select AFTrack (OSZ) as format in section Atlas settings on the left side of the main window.

OSZ is a ZIP-archive. Within this zip archive a (large) number of tiles with the calibrated folder structure (coordinates) are stored. OSZ only works if each tile has got a resolution of 256x256 Pixels. So be sure to uncheck Recreate/adjust map tiles (CPU intensive).

The output format is one file for each layer in the corresponding folder.

#### Restrictions

Depending on the device free memory the file maybe not work. So more then 80000 tiles should not be used.

### Creating and using atlases with AndNav

For creating atlases compatible with AndNav you have to select AndNav atlas format as format in section Atlas settings on the left side of the main window.
As atlases for AndNav do not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases for AndNav:

- Change height or width of the map tiles
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)

### Creating and using atlases with Big Planet Tracks

For creating offline atlases compatible with Big Planet Tracks (Android application) you have to select Big Planet Tracks SQLite as format in section Atlas settings on the left side of the main window.
Please not that this atlas format requires additional libraries which are not shipped with Mobile Atlas Creator. Read section SQLite library for details what libraries are required and how to obtain them.
The atlas format BigPlanet SQLite does not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases using this output format:

- Recreate/adjust map tiles (custom tile size and image format)
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)
- Atlases created after another are merged into one Database named `BigPlanet_maps.sqlitedb` which is located in the atlas output directory.

### Creating atlases for CacheWolf

For creating atlases compatible with CacheWolf you have to select CacheWolf WFL as format in section Atlas settings on the left side of the main window.

#### Custom tile processing settings enabled

Maps that have custom tile processing options set are saved as tiled images with one WFL calibration file for each tile. All processing options such as image format and tile size can be used.

#### Custom tile processing settings disabled

In this mode automatic tiling is disabled and the same restrictions and the warning as for the OziExplorer output format apply.

The output format of an "atlas" for CacheWolf is one subdirectory per layer and within this subdirectory one `PNG` image and one `WFL` file per defined map.

### Creating Garmin Custom maps

For creating atlases of Creating Garmin Custom maps you have to select Garmin Custom Map (KMZ) as format in section Atlas settings on the left side of the main window. Details about the Garmin Custom Map format can be found in the Garmin Forums

Using this atlas output format the following features are ignored when creating atlases:

- Recreate/adjust map tiles (custom tile size and image format)

The output format of an "atlas" for Garmin Custom maps is one `KMZ` file per layer containing all maps (max 100) as seperate `JPG` image files. The JPEG compression rate can be specified for each map/image using image format selector in the custom tile processing section. The Garmin Custom Map format defines a maximum image size of 1024x1024 pixels. If a map is larger it will be automatically scaled down to fit into this size. You can prevent scaling when setting the max map size in the settings dialog to 1024.

### Creating atlases for Glopus

For creating atlases compatible with Glopus you have to select Glopus (PNG & KAL) or Glopus Map File (GMF) as format in section Atlas settings on the left side of the main window.

#### Glopus (PNG & KAL)

Using this atlas output format the same restrictions and the warning as for the OziExplorer output format apply.

The output format of an "atlas" for Glopus is one subdirectory per layer and within this subdirectory one `PNG` image and one `KAL` file per defined map.

#### Glopus Map File (GMF)

Within this file a (large) number of tiles with its calibrated coordinates are stored. Glopus works best if each tile has a resolution of 1024x1024 pixels. So check Recreate/adjust map tiles (CPU intensive). Width and height should be set to 1024.

The output format is one file for each layer in the corresponding folder.

### Glopus Map File (GMF) / AFTrack

For creating atlases compatible with AFTrack (Symbian S60) you have to select Glopus Map File (GMF) as format in section Atlas settings on the left side of the main window.

Within this file a (large) number of tiles with its calibrated coordinates are stored. AFTrack works best if each tile has got a resolution of 256x256 Pixels. So uncheck Recreate/adjust map tiles (CPU intensive).

The output format is one file for each layer in the corresponding folder.

#### Restrictions

AFTrack can handle a maximum of 4096 tiles - so be sure not to select more.

### Google Earth Overlay (KMZ)

For creating Google Earth Overlays you have to select Google Earth Overlay (KMZ) as format in section Atlas settings on the left side of the main window.

Using this atlas output format the following features are ignored when creating atlases:

- Recreate/adjust map tiles (custom tile size and image format)

#### WARNING

The Google Earth Overlay atlas format uses JPG images. The image size depends on the selected maximum map size (see settings dialog). The theoretical maximum map size for this atlas format is 25000. However it is strongly recommended not to set the maximum map size higher than 10000 (this will result in a image with uncompressed size about 286 MB).

### Creating Magellan RMP atlases

For creating atlases of Creating Garmin Custom Maps you have to select Magellan (RMP) as format in section Atlas settings on the left side of the main window. Additionally you have to set the maximum map size to 18000 (Settings dialog, tab "map size").

Using this atlas output format the following features are ignored when creating atlases:

- Recreate/adjust map tiles (custom tile size and image format)

Additionally some other limitations may apply, based on which device and firmware version you are using. Mobile Atlas Creator does not chek those limitations - therefore it may work or not if you are using:

- An atlas with more than 5 maps.
- Maps with a zoom level higher than 15.

The output format of an "atlas" for Magellan is one `RMP` file in the atlas directory. You can directly load this file in Magellan VantagePoint or transfer it onto your device.

### Creating atlases for MAPLORER

For creating atlases compatible with MAPLORER you have to select the Maplorer format in the Atlas settings section on the left side of the main window. You have to choose JPG image format under Layer settings/tile format (PNG is not supported by Maplorer).

There are no specific limits on tile sizes and/or numbers; good results for hiking/biking can be obtained using zoom level 15, custom tile size of 1024x1024 (check Recreate/adjust map tiles (CPU intensive) under Layer settings. For good performance, avoid using too big or too many tiles (the maximum number of columns in Maplorer is currently 26 ('A' to 'Z'), but it is preferable to use less).

After defining the maps and layers (select region and click Add selection under Atlas Content) for the atlas, click the button Create Atlas. Once atlas download and creation has completed, all necessary files belonging to the atlas can be found in the directory `atlases\[atlas name]_[current date and time]`.

To install the atlas on your device, simply connect it to your PC and copy the content of the respective atlas subdirectory (i.e. all .jpg and .pos files generated) to the Maplorer directory (the one which contains maplorer.exe) on your device. Starting Maplorer on the device will automatically read all tiles and create the index map. Detailed instructions on making maps for Maplorer can be found at http://maplorer.com

### Creating and using atlases with Maverick

For creating atlases compatible with Maverick you have to select Maverick atlas format as format in section Atlas settings on the left side of the main window.
As atlases for Maverick do not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases for AndNav:

- Recreate/adjust map tiles (custom tile size and image format)
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)

### Creating and using atlases with Mobile Trail Explorer (MTE)

For creating atlases compatible with Mobile Trail Explorer you have to select Mobile Trail Explorer Cache as format in section Atlas settings on the left side of the main window.
If a map source uses an image format different to PNG the tiles will be automatically converted to the PNG format.
The output is one `MTEFileCache` file per atlas which contains all maps. An existing cache file can not be updated. If you want to add maps to an existing `MTEFileCache` please use the atlas format Mobile Trail Explorer which creates a file structure identical to JTileDownloader and then process the maps using MTE CacheCreator.
As atlases for Mobile Trail Explorer does not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases for Mobile Trail Explorer:

- Recreate/adjust map tiles (custom tile size and image format)
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)

### Creating atlases for NaviComputer

For creating atlases, compatible with NaviComputer, you have to select NaviComputer (NMAP) in the section Atlas settings on the left side of the MOBAC main window.
Please not that this atlas format requires additional libraries which are not shipped with Mobile Atlas Creator. Read section SQLite library for details what libraries are required and how to obtain them.
After defining the maps and layers for the atlas to be created, start atlas download and creation via the button Create Atlas. Once download and creation has completed, the generated file with the extension nmap can be found in the MOBAC output directory. This *.nmap-file is the required input file for NaviComputer.

### Creating OruxMaps atlases

For creating atlases compatible with OruxMaps as format you have to select OruxMaps in section Atlas settings on the left side of the main window.

Using this atlas output format the following features are ignored when creating atlases:

- Layer settings, custom tile size. OruxMaps always uses 512x512 tile size. You can select the tile format (PNG or JPEG). If you do not select any, default value is JPEG - quality 90.

The output format of an "atlas" for OruxMaps is one or more map directories in the atlas directory. You have to copy those maps onto your device (default directory: /oruxmaps/mapfiles/).

If you select OruxMaps Sqlite format, then you need SQLite native libraries; see SQLite atlas formats

### Creating atlases for Osmdroid

For creating atlases compatible with Osmdroid you have to select Osmdroid ZIP as format in section Atlas settings on the left side of the main window.
As atlases for Osmdroid do not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases for Osmdroid:

- Change height or width of the map tiles
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)

### Creating atlases for OSMTracker

For creating atlases compatible with OSMTracker you have to select OSMTracker tile storage as format in section Atlas settings on the left side of the main window.
As atlases for OSMTracker do not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases for OSMTracker:

- Change height or width of the map tiles
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)

### Creating and using atlases with OziExplorer / large PNG image export

For creating atlases compatible with OziExplorer you have to select OziExplorer (PNG & MAP) as format in section Atlas settings on the left side of the main window.

#### Restrictions

As OziExplorer does not support tiled maps some features are ignored when creating atlases in this format:

- Image output format is fix: 24bit PNG
- Recreate/adjust map tiles custom tile is ignored

The output format of an "atlas" for OziExplorer is one subdirectory per layer and within this subdirectory one `PNG` image and one `MAP` file per defined map. For opening a map in OziExplorer select the menu File → Load from File → Load from MAP file, browse to the layer directory of the created atlas and select the MAP file.

If you are only interested in the map image you can safely delete the created map file.

#### Warning

Mobile Atlas Creator uses a highly sophisticated and optimized algorithm for creating the PNG files for OziExplorer use. This algorithm allows to create very large maps images at low memory usage. OziExplorer and most image viewers do not use such sophisticated algorithms which can lead to the situation that you can create very large map images - but OziExplorer and other image viewers are not able to open the image.

### Creating atlases for PathAway

For creating atlases compatible with PathAway you have to select PathAway tile cache as format in section Atlas settings on the left side of the main window.
As atlases for PathAway do not support all features provided by Mobile Atlas Creator the following restrictions apply when creating atlases for PathAway:

- The maximum zoom level is 16 - higher zoom levels are not possible with this atlas format
- Tile width and width can not be changed (settings will be ignored)
- Name of all layers and maps is ignored
- Structure of the atlas is ignored (which maps belongs to which layer)

### Creating and using atlases with RMaps

For creating offline atlases compatible with RMaps (Android application) you have to select RMaps SQLite as format in section Atlas settings on the left side of the main window.
Please not that this atlas format requires additional libraries which are not shipped with Mobile Atlas Creator. Read section SQLite library for details what libraries are required and how to obtain them.
The atlas format BigPlanet SQLite does not support all features provided by Mobile Atlas Creator the following settings are ignored when creating atlases using this output format:

- Recreate/adjust map tiles (custom tile size and image format)
- Name of all layers and maps
- Structure of the atlas (which maps belongs to which layer)
- Atlases created after another are merged into one Database named `BigPlanet_maps.sqlitedb` which is located in the atlas output directory.

### [Nokia] Sports Tracker

For creating atlases compatible with Sports Tracker(ST) you have to select Sports Tracker (NOT GPS Sportstracker) as format in section Atlas settings on the left side of the main window.

Do not select Recreate/adjust map tiles.

Maximum Zoomlevel of Sports Tracker is 17, default is 13.

Copy the created atlas (the whole folder) into the following folder of youre phone (depending of the Sports Tracker version):

- Sports Tracker 1.76: `E:\system\data\Maps\Street\`
- Sports Tracker 2.x: `E:\system\data\Maps\Street\`
- Sports Tracker 3.x: `E:\system\data\STMaps\Street\`

For changing the zoom level inside Storts Tracker press 5 to zoom in and 0 to zoom out.

### Creating and using atlases with Touratech QV / large PNG image export

For creating atlases compatible with Touratech QV you have to select Touratech QV as format in section Atlas settings on the left side of the main window.

#### Restrictions

As Touratech QV does not support tiled maps some features are ignored when creating atlases in this format:

- Image output format is fix: 24bit PNG
- Recreate/adjust map tiles custom tile is ignored

The output format of an "atlas" for Touratech QV is one subdirectory per layer and within this subdirectory one `PNG` image and one `CAL` file per defined map.

If you are only interested in the map image you can safely delete the created cal file.

#### Warning

Mobile Atlas Creator uses a highly sophisticated and optimized algorithm for creating the PNG files for Touratech QV use. This algorithm allows to create very large maps images at low memory usage. Touratech QV and most image viewers do not use such sophisticated algorithms which can lead to the situation that you can create very large map images - but Touratech QV and other image viewers are not able to open the image.

### Creating and using atlases with TrekBuddy

For creating atlases compatible with TrekBuddy you have to select TrekBuddy tared atlas or TrekBuddy untared atlas as format in section Atlas settings on the left side of the main window.

After defining the maps and layers for the atlas to be created start atlas download and creation via the button Create Atlas. Once atlas download and creation has completed all necessary files belonging to the atlas can be found in the directory `atlases\[atlas name]_[current date and time]`.

The atlas itself consists of the atlas startup file `cr.tar` (tar format) or `cr.tba` (regular/untared format) and the subdirectories containing the different maps of the atlas. For using the atlas with TrekBuddy copy the whole directory onto your J2ME device. Then use the Load Atlas function of TrekBuddy and open `cr.tar`/`cr.tba` (in the atlas root directory).

## Enhancement requests

If you are missing the map provider of your choice or have other enhancement ideas for Mobile Atlas Creator feel free to open an Feature Request Ticket at SourceForge.

If have a new online map which is not available in Mobile Atlas Creator there my be change to add it. Before opening a Feature Request please take a look into the list of map sources known to incompatible with Mobile Atlas Creator.

## Problems, Bugs & Errors

In case of unexpected errors while executing Mobile Atlas Creator you may get presented a exception dialog containing detailed information about the problem. In such a case please create a new ticket in the Bug Tracker at SourceForge. Please add the detailed exception information and a detailed description of your last performed actions.

### The default error log

By default Mobile Atlas Creator records all errors of the current session into it's error log file `Mobile Atlas Creator.log`. This log file is located on Windows system in the directory `%APPDATA%\Mobile Atlas Creator\` and on Linux/Unix/OSX system in the directory `~/.mobac/`

### Activate the advanced logging system

If the recorded errors in the error log do not indicate a problem you can activate the overall message logging mechanism of Mobile Atlas Creator:
Download the file log4j.xml and save it in the directory where the jar file of Mobile Atlas Creator is installed to.

The next start Mobile Atlas Creator will create a log file in the current directory (on Windows this is usually the directory where the JAR file is located on Linux usually the profile directory). Please note that the log file is erased on each program start. If you think you have found a bug please file it in the bug tracker at SourceForge.

## Known problems and limitations

### New map sources

Mobile Atlas Creator is limited to map sources that provide their maps if form of map tiles. Each of that map tiles has to be of size 256x256 pixels. Additionally the map source has to use the spherical Mercator projection and the number of tiles forming the world on each zoom level has to be one of the following values: 20, 21, 22 ... 221, 222.
For more details see OpenStreetMap Wiki: Mercator, Height and width of a map and Zoom levels

### Java Bugs

Due to bugs in Java you should not do the following:

- Install Mobile Atlas Creator into a directory which path contains an "!" (exclamation mark) because of this Sun Java bug
- Do not use OpenJDK if you want to work with GPX tracks in Mobile Atlas Creator

## Details for advanced users

### Moving the tile store path

Usually the tile store path where Mobile Atlas Creator saves all downloaded images in is automatically determined.
In case you want to select a different directory perform the following steps:

1. Make sure you have closed MOBAC
2. Open `settings.xml` in an text editor
3. Inside of the tag `<settings>` create a new tag named `<tileStoreDirectory>`
4. Set the path name to the value of this tag (Windows users should replace backslashes with a slashes)
5. (optional) Copy or move the content of the old tile store directory into the new tile store directory.

#### Example

    <settings>
        <tileStoreDirectory>E:/tiles</tileStoreDirectory>
        ...
    </settings>

This specified the windows directory `E:\tiles` as new tile store directory. The previously used tile store will not be used anymore.
Deleting the `<tileStoreDirectory>` tag restores the old behavior (automatically tile store directory selection).

### Custom map sources

Custom map sources which uses a similar URL scheme as Google/OpenStreetMap can be added by editing the file `settings.xml` with an text editor.

Warning: You have to close Mobile Atlas Creator before editing `settings.xml` - otherwise you will lost all made changes when closing Mobile Atlas Creator!

The following example shows what have to be added for defining a custom map source. It defines an additional map Source named "Custom OSM Mapnik" which shows map tiles identical to the predefined map source "OpenStreetMap Mapnik".

    <settings>
        <customMapSources>
            <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>
        </customMapSources>
        ...
    </settings>

The most important part of this definition is the url. It is a template containing specific placeholders which are encapsulated by curly brace:

- {$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]

### Custom multi-layer map sources

The same way map sources which consists of two layers can be added as well. Note that the foreground map source images must have transparent parts - otherwise the background map source will not be visible.

    <settings>
        <customMapSources>
            <customMultiLayerMapSource>
                <name>Custom OSM Mapnik</name>
                <minZoom>0</minZoom>
                <maxZoom>18</maxZoom>
                <tileType>png</tileType>
                <tileUpdate>None</tileUpdate>
                <url>http://topo.openstreetmap.de/topo/{$z}/{$x}/{$y}.png</url>
                <backgroundColor>#000000</backgroundColor>
                <backgroundMapSource>
    	            <name>Custom background unique name</name>
    	            <minZoom>0</minZoom>
    	            <maxZoom>18</maxZoom>
    	            <tileType>png</tileType>
    	            <tileUpdate>None</tileUpdate>
    	            <url>http://tile.openstreetmap.org/{$z}/{$x}/{$y}.png</url>
    	            <backgroundColor>#000000</backgroundColor>
                </backgroundMapSource>
            </customMultiLayerMapSource>
        </customMapSources>
        ...
    </settings>