TrekBuddy Atlas Creator - Readme

This is readme file for the TrekBuddy Atlas Creator (TAC) application.
TAC is an open source project hosted on SourceForge.net:
http://trekbuddyatlasc.sourceforge.net

Table of contents

License

TrekBuddy Atlas Creator (TAC) 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 TrekBuddy_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 TAC installed.

Application start

The application is started by executing the start.cmd in a Windows environment or the start.sh under a Linux / Unix environment. At the first application start all necessary files and folders are automatically created by the application.

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 and open cr.tar/cr.tba (in the atlas root directory) in TrekBuddy as atlas.

Creating and using atlases with Mobile Trail Explorer (MTE)

For creating atlases compatible with Mobile Trail Explorer you have to select Mobile Trail Explorer 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.
As atlases for Mobile Trail Explorer does not support all features provided by TrekBuddy the following settings are ignored when creating atlases for Mobile Trail Explorer:

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 does not support all features provided by TrekBuddy the following settings are ignored when creating atlases for AndNav:

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 does not support all features provided by TrekBuddy the following settings are ignored when creating atlases for AndNav:

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 TrekBuddy 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 TrekBuddy the following settings are ignored when creating atlases using this output format:

SQLite library

The BigPlanet atlas format uses a SQLite database for storing the tiles. For creating SQLite database additional libraries (Java and native) are required. TrekBuddy Atlas Creator uses the JavaSQLite wrapper by Christian Werner. For installing the SQLite wrapper copy the files sqlite.jar and sqlite_jni.dll (Windows) respectively sqlite_jni.so (Linux/Unix) into the program directory of TrekBuddy Atlas Creator (where the TrekBuddy_Atlas_Creator.jar is located).

For 32 bit Windows systems there are pre-compiled binaries available: SQLite binaries for Win32. Other operating systems have to compile the wrapper using the sources.

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.

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

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

TrekBuddy Atlas Creator uses an 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 Glopus

For creating atlases compatible with OziExplorer 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 following features are ignored when creating atlases:

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.

Enhancement requests

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

Problems, Bugs & Errors

In case of unexpected errors while executing TrekBuddy 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.

If you do not get such a exception dialog but have other general problems using TrekBuddy Atlas Creator you can activate the logging mechanism. To do so download the file log4j.xml and save it in the directory where the jar file of TrekBuddy Atlas Creator is installed to.

The next start TrekBuddy 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

TrekBuddy 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

Details for advanced users

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