# 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://trekbuddyatlasc.sourceforge.net

## Table of contents

- License
- Description
- Requirements
- Installation
- Application start
- The different atlas formats
  - Creating and using atlases with TrekBuddy
  - Creating and using atlases with Mobile Trail Explorer (MTE)
  - Creating and using atlases with Maverick
  - Creating and using atlases with AndNav
  - Creating atlases for OSMTracker
  - Creating and using atlases with BigPlanet / RMaps
  - Creating and using atlases with OziExplorer / large PNG image
  - Creating and using atlases with Touratech QV / large PNG image
  - Creating atlases for Glopus
  - Creating atlases for CacheWolf
  - Creating Garmin Custom maps
  - Creating Magellan RMP atlases
- Enhancement requests
- Problems, Bugs & Errors
- Known problems and limitations
- Details for advanced users

## License

Mobile Atlas Creator is under GNU General Public License Version 2 (GPL). For details on the GPL see the license file gpl.txt

## Description

This application creates atlases for the J2ME applications TrekBuddy and Mobile Trail Explorer (MTE), the Android applications AndNav, Maverick, BigPlanet-Maps, RMaps, 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.

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.

## Application start

The application is started by executing the `Mobile Atlas Creator.exe` in a Windows environment or the `start.sh` under a Linux / Unix environment (it may be necessary to set the executable bit for the script). At the first application start all necessary files and folders are automatically created by the application.

## The different atlas formats

### 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).

### 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 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 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 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 BigPlanet / RMaps

For creating offline atlases compatible with BigPlanet-Maps and RMaps (both Android applications) you have to select BigPlanet 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.

#### SQLite native library

The BigPlanet atlas format uses a SQLite database for storing the tiles. For creating SQLite database an additional native library is required. The correspondent Java classes are already part of Mobile Atlas Creator - only the platform dependent native library of JavaSQLite wrapper by Christian Werner is missing. For installing the SQLite wrapper copy the file `sqlite_jni.dll` (Windows) respectively `sqlite_jni.so` (Linux/Unix) into the program directory of Mobile Atlas Creator (where the Mobile_Atlas_Creator.jar is located).

For Windows and Linux (32bit and 64bit) there are pre-compiled binaries available Other operating systems systems have to compile the wrapper using the sources:

    wget http://www.ch-werner.de/javasqlite/javasqlite-20090430.tar.gz
    tar xzvf javasqlite-20090430.tar.gz
    cd javasqlite-20090430/
    ./configure
    make
    cp .lib/lib* /[MOBAC installation path]

### 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 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 atlases for Glopus

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

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.

### 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 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.

## 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]